|
| 1 | +# Use Azure Active Directory (Azure AD) as OAuth 2.0 server |
| 2 | + |
| 3 | +We are going to test 3 OAuth flows: |
| 4 | +1. Access management ui via a browser :ballot_box_with_check: |
| 5 | +2. Access management rest api :construction: |
| 6 | +3. Access AMQP protocol :construction: |
| 7 | + |
| 8 | +## Prerequisites to follow this guide |
| 9 | + |
| 10 | +- Have an account in https://portal.azure.com. |
| 11 | +- Docker |
| 12 | +- Openssl |
| 13 | + |
| 14 | +## Register your app |
| 15 | + |
| 16 | +When using **Azure AD as OAuth 2.0 server**, your client app (in our case RabbitMQ) needs a way to trust the security tokens issued to it by the **Microsoft identity platform**. The first step in establishing that trust is by **registering your app** with the identity platform in Azure AD. |
| 17 | + |
| 18 | +> :blue_book: More details about App registration in Azure AD are available [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) |
| 19 | +
|
| 20 | +Once you have logged onto your account in [Azure Portal](https://portal.azure.com), go to **Azure Active Directory** (use the search bar if you are not able to easily find it). |
| 21 | + |
| 22 | +In the left-hand navigation menu, click on **App Registrations**. Then, select **New registration**. |
| 23 | + |
| 24 | +In the **Register an application** pane, provide the following informations: |
| 25 | + |
| 26 | +- **Name**: the name you would like to give to your application (ex: *rabbitmq-oauth2*) |
| 27 | +- **Supported Account Types**: select **Accounts in this organizational directory only (Default Directory only - Single tenant)** (you can choose other options if you want to enlarge the audience of your app) |
| 28 | +- **Redirect URI**: |
| 29 | + - On the **Select a platform** drop-down list, select **Single-page application (SPA)** |
| 30 | + - Configure the **Redirect URI** to: `https://localhost:15671/js/oidc-oauth/login-callback.html` |
| 31 | + |
| 32 | +> :warning: **IMPORTANT**: As you may have noticed, Azure AD only allows `https` links as **Redirect URI**. To fit this need, we will enable HTTPS for RabbitMQ Management UI, on port `15671`. |
| 33 | +
|
| 34 | +Click on **Register**. |
| 35 | + |
| 36 | + |
| 37 | + |
| 38 | +Note the following values, as we will need it later to configure the `rabbitmq_auth_backend_oauth2` on RabbitMQ side: |
| 39 | +- Directory (tenant ID) |
| 40 | +- Application (client) ID |
| 41 | + |
| 42 | +Click on the **Endpoints** tab and, on the right pane that has just opened, copy the value of **OpenID Connect metadata document** (ex: `https://login.microsoftonline.com/{TENANT_ID}/v2.0/.well-known/openid-configuration`) and open it in your browser. |
| 43 | + |
| 44 | +Note the value of the `jwks_uri` key (ex: `https://login.microsoftonline.com/{TENANT_ID}/discovery/v2.0/keys`), as you will also need it later to configure the `rabbitmq_auth_backend_oauth2` on RabbitMQ side |
| 45 | + |
| 46 | + |
| 47 | + |
| 48 | +## Create a secret for your app |
| 49 | + |
| 50 | +Your application needs a **client secret** to prove its identity when requesting a token. |
| 51 | + |
| 52 | +Still on the **App registrations** page, in the left-hand menu, click on **Certificates & Secrets**, then select the **Client secrets** tab. |
| 53 | + |
| 54 | +In the **Certificates & Secrets** pane, click on **New Client Secret** and, on the right pane that has just opened, enter a description for the secret and choose an expiration time. |
| 55 | + |
| 56 | +Click on **Add**. |
| 57 | + |
| 58 | +> :warning: **IMPORTANT**: Immediately note the value of the secret (as you won't be able to get it later and we will need it to configure the `rabbitmq_auth_backend_oauth2` on RabbitMQ side) |
| 59 | +
|
| 60 | +## Create OAuth 2.0 roles for your app |
| 61 | + |
| 62 | +App roles are defined by using the [Azure portal](https://portal.azure.com) during the app registration process. When a user signs in to your application, Azure AD emits a `roles` claim for each role that the user or service principal has been granted (we will have a look at it at the end of this tutorial). |
| 63 | + |
| 64 | +> :blue_book: More details about roles in Azure AD are available [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps) |
| 65 | +
|
| 66 | +Still in [Azure Portal](https://portal.azure.com), go back to **Azure Active Directory** home page. In the left-hand menu, click on **App Registrations** and then click on your **application name** to open your application **Overview** pane. |
| 67 | + |
| 68 | +### Create a role to allow access to Management UI |
| 69 | + |
| 70 | +In the left-hand menu, click on **App Roles**. Then, click on **Create App Role** to create an OAuth 2.0 role that will be used to give access to the RabbitMQ Management UI. |
| 71 | + |
| 72 | +> :blue_book: More details about how permissions are managed on RabbitMQ when using OAuth2 are available [here](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial#about-permissions). |
| 73 | +
|
| 74 | +On the right menu that has just opened, provide the requested information: |
| 75 | + |
| 76 | +- **Display Name**: the name you want to give to the role (ex: *Management UI Admin*) |
| 77 | +- **Allowed member types**: Both (Users/Groups + Applications) |
| 78 | +- **Value**: `Application_ID.tag:administrator` (where *Application_ID* is the value of the *Application (client) ID* noted earlier in this tutorial) |
| 79 | +- **Description**: briefly describe what this role aims to (here just to give admin access to the RabbitMQ Management UI) |
| 80 | +- **Do you want to enable this app role**: `yes` (check the box) |
| 81 | + |
| 82 | +Click on **Apply**. |
| 83 | + |
| 84 | +### Create a role to grant configure permission on all resources |
| 85 | + |
| 86 | +Click again on **Create App Role**. We are now going to create an OAuth 2.0 role that will be used to give configure access to all the resources on all the RabbitMQ vhosts. |
| 87 | + |
| 88 | +On the right menu that has just opened, fill the form as below: |
| 89 | + |
| 90 | +- **Display Name**: the name you want to give to the role (ex: *Configure All Vhosts*) |
| 91 | +- **Allowed member types**: Both (Users/Groups + Applications) |
| 92 | +- **Value**: `Application_ID.configure:*/*` (where *Application_ID* is the value of the *Application (client) ID* noted earlier in this tutorial) |
| 93 | +- **Description**: briefly describe what this role aims to (here to give permissions to configure all resources on all the vhosts available on the RabbitMQ instance) |
| 94 | +- **Do you want to enable this app role**: `yes` (check the box) |
| 95 | + |
| 96 | +Click on **Apply**. |
| 97 | + |
| 98 | +## Assign App Roles to users |
| 99 | + |
| 100 | +Now that some roles have been created for your application, you still need to assign these to some users. |
| 101 | + |
| 102 | +Still in [Azure Portal](https://portal.azure.com), go back to **Azure Active Directory** home page and, in the left-hand menu, click on **Enterprise Applications**. |
| 103 | + |
| 104 | +In the new left-hand menu, select **Manage -> All applications**. Use the **Search Bar** and/or the available filters to find your application. |
| 105 | + |
| 106 | + |
| 107 | + |
| 108 | +Click on the application you just created, for which you want to assign roles to users/groups, then, in the left-hand navigation menu, Select **Manage -> Users and groups**. |
| 109 | + |
| 110 | +Click on **Add user/group** to open the **Add Assignment** pane. |
| 111 | + |
| 112 | +Below **Users**, click on *None Selected* and, on the **Users** pane that has just opened on the right, search and select the users/groups you want to assign roles to. |
| 113 | + |
| 114 | +Once you've selected users and groups, click on the **Select** button. |
| 115 | + |
| 116 | +Back to the **Add assignment** pane, below **Select a Role**, click on *None Selected* and, on the **Select a role** pane that has just opened on the right, search and select the role you want to assign to the selected users. |
| 117 | + |
| 118 | +> :bulb: If only one role is available for your application, it would be automatically selected and greyed by default |
| 119 | +
|
| 120 | +Choose a role (only a single role can be selected at a time), click on the **Select** button, and click on the **Assign** button to finalize the assignment of users and groups to the app. |
| 121 | + |
| 122 | +:repeat: Repeat the operations for all the roles you want to assign. |
| 123 | + |
| 124 | +## Configure RabbitMQ to use Azure AD as OAuth 2.0 authentication backend |
| 125 | + |
| 126 | +The configuration on Azure side is done. You now have to configure RabbitMQ to use the resources you just created. |
| 127 | + |
| 128 | +[rabbitmq.config](../conf/azure/rabbitmq.config) is a sample RabbitMQ advanced configuration to **enable Azure AD as OAuth 2.0 authentication backend** for the RabbitMQ Management UI. |
| 129 | + |
| 130 | +Update it with the following values (you should have noted these in the previous steps): |
| 131 | +- **Tenant ID** associated to the app that we registered in Azure AD |
| 132 | +- **Application ID** associated to the app that we registered in Azure AD |
| 133 | +- Value of the **secret** we created for our app in Azure AD |
| 134 | +- Value of the **jwks_uri** key from `https://login.microsoftonline.com/{TENANT_ID}/v2.0/.well-known/openid-configuration` |
| 135 | + |
| 136 | +``` |
| 137 | +$ vi rabbitmq.config |
| 138 | +[ |
| 139 | + {rabbit, [ |
| 140 | + {auth_backends, [rabbit_auth_backend_oauth2, rabbit_auth_backend_internal]} |
| 141 | + ]}, |
| 142 | + {rabbitmq_management, [ |
| 143 | + {oauth_enable, true}, |
| 144 | + {oauth_client_id, "PUT YOUR AZURE AD APPLICATION ID"}, |
| 145 | + {oauth_client_secret, "PUT YOUR AZURE AD APPLICATION SECRET"}, |
| 146 | + {oauth_provider_url, "https://login.microsoftonline.com/AZURE_AD_TENANT_ID"} |
| 147 | + ]}, |
| 148 | + {rabbitmq_auth_backend_oauth2, [ |
| 149 | + {resource_server_id, <<"PUT YOUR AZURE AD APPLICATION ID">>}, |
| 150 | + {extra_scopes_source, <<"roles">>}, |
| 151 | + {key_config, [ |
| 152 | + {jwks_url, <<"PUT YOUR AZURE AD JWKS URI VALUE">>} |
| 153 | + ]} |
| 154 | + ]} |
| 155 | +]. |
| 156 | +``` |
| 157 | + |
| 158 | +> :warning: Please update the file available in this tutorial ([here](../conf/azure/rabbitmq.config)), as it will be automatically loaded in the RabbitMQ instance that we are going to deploy later in this tutorial |
| 159 | +
|
| 160 | +### Generate SSL certificate and key |
| 161 | +> :warning: Remember when you have registered your app on Azure AD that it only allows **https** protocol for OAuth2 **Redirect URI**? We will thus need to enable HTTPS for RabbitMQ Management UI amd its underlying API. |
| 162 | +
|
| 163 | +For the purpose of this tutorial, we can generate a self-signed certificate/key pair. |
| 164 | + |
| 165 | +Run the following command (depending on your config, you may have to be root): |
| 166 | +``` |
| 167 | +make start-azure |
| 168 | +``` |
| 169 | + |
| 170 | +This generates the following files in `conf/azure`: |
| 171 | +- **rabbitmq-ca.**crt**: a custom certificate authority that is used to generate and sign a self signed certificate for RabbitMQ |
| 172 | +- **rabbitmq.crt**: a self-signed certificate (cn=localhost) |
| 173 | +- **rabbitmq.key**: the private key associated to the `rabbitmq.crt` certificate |
| 174 | + |
| 175 | +:arrow_right: These files will be mounted into the `rabbitmq` docker container in the next steps of this tutorial, where they will be used to configure HTTPS for the RabbitMQ Management UI/API |
| 176 | + |
| 177 | +## Start RabbitMQ |
| 178 | + |
| 179 | +Run the following commands to run RabbitMQ docker image with the latest changes from `oidc-integration` branch with commit tag `69a4159f3482e5212d364f499b2ca2e05bede0ca`. |
| 180 | + |
| 181 | +> :bulb: All the commits associated to `oidc_integration` branch are available [here](https://github.com/rabbitmq/rabbitmq-server/commits/oidc-integration). Don't hesitate to have a look a it to get the very last commit, as the one advertised in this tutorial may not stay the last one forever! |
| 182 | +
|
| 183 | +``` |
| 184 | +export IMAGE_TAG=69a4159f3482e5212d364f499b2ca2e05bede0ca-otp-min |
| 185 | +export IMAGE=pivotalrabbitmq/rabbitmq |
| 186 | +export MODE=azure |
| 187 | +make start-rabbitmq |
| 188 | +``` |
| 189 | +:arrow_right: This starts a docker container named `rabbitmq`, with RabbitMQ Management UI/API with HTTPS enabled, and configured to use your Azure AD as OAuth2 Authentication Backend, based on the information you provided in `rabbitmq.config` in the previsous steps of this tutorial. |
| 190 | + |
| 191 | +## Verify RabbitMQ Management UI access |
| 192 | + |
| 193 | +Go to RabbitMQ Management UI `https://localhost:15671`. Depending on your browser, ignore the security warnings (raised by the fact that we are using a self-signed certificate) to proceed. |
| 194 | + |
| 195 | +Once on the RabbitMQ Management UI page, click on the **Click here to log in** button, |
| 196 | +authenticate with your **Azure AD user**. The first time, you are likely going to have to give your |
| 197 | +consent (it depends on the policies applied to Azure AD on your side). |
| 198 | + |
| 199 | +> :warning: At first login, you may face the `AADSTS90008` error: just click on **Click here to log in** button |
| 200 | +again and it will disappear (this issue seems to be known, as illustrated [here](https://docs.microsoft.com/en-us/answers/questions/671457/after-34accept34-on-consent-prompt-on-azure-sso-lo.html#answer-893848)) |
| 201 | + |
| 202 | +At the end, you should be redirected back to the RabbitMQ Management UI. |
| 203 | + |
| 204 | +Azure AD issues an access token like this one below. The permissions are managed in the `roles` claim. |
| 205 | +We have configured RabbitMQ with `{extra_scopes_source, <<"roles">>},` which means RabbitMQ uses |
| 206 | +the scopes in the `roles` claim to define permissions for a logged-in user. |
| 207 | + |
| 208 | +``` |
| 209 | +{ |
| 210 | + "aud": "30b61ef8-72d7-4e40-88f2-6e16c8d3fd88", |
| 211 | + "iss": "https://sts.windows.net/1ffc6121-590e-4aa5-bf47-c348674069cb/", |
| 212 | + "iat": 1655740039, |
| 213 | + "nbf": 1655740039, |
| 214 | + "exp": 1655744211, |
| 215 | + "acr": "1", |
| 216 | + "aio": "AUQAu/8TAAAAjvwucwL4nZe83vNZvg6A7sAPscI9zsGvRs8EuT7aVhubpmhRnxJ+X7nbkISoP5eBBMxoi2yiCclnH2Ocjjzsqw==", |
| 217 | + "amr": [ |
| 218 | + "wia" |
| 219 | + ], |
| 220 | + "appid": "30b61ef8-72d7-4e40-88f2-6e16c8d3fd88", |
| 221 | + "appidacr": "1", |
| 222 | + "email": "baptiste.daroit@company.com", |
| 223 | + "idp": "https://sts.windows.net/b3f4f7c2-72ce-4192-aba4-d6c7719b5766/", |
| 224 | + "in_corp": "true", |
| 225 | + "ipaddr": "xxx.xxx.xxx.xxx", |
| 226 | + "name": "Baptiste DA ROIT", |
| 227 | + "oid": "cf2df3b4-03df-4e1e-b5c0-f232932aaead", |
| 228 | + "rh": "0.AR8AgCG80x7L90C1mhVBBXQzQjgoklctsdBMtgYVWFwc4tgfAMQ.", |
| 229 | + "roles": [ |
| 230 | + "30b61ef8-72d7-4e40-88f2-6e16c8d3fd88.tag:monitoring", |
| 231 | + "30b61ef8-72d7-4e40-88f2-6e16c8d3fd88.configure:*/*" |
| 232 | + ], |
| 233 | + "scp": "User.Read", |
| 234 | + "sub": "6aBzW3a1FOTTrnlZEuC1SmwG0sRjVgQU49DvrYK6Rqg", |
| 235 | + "tid": "1ffc6121-590e-4aa5-bf47-c348674069cb", |
| 236 | + "unique_name": "baptiste.daroit@company.com", |
| 237 | + "uti": "QHqwThTqQEK9iMdnRuD_AA", |
| 238 | + "ver": "1.0" |
| 239 | +} |
| 240 | +``` |
0 commit comments