|
| 1 | +--- |
| 2 | +title: OpenID Connect with Azure AD |
| 3 | +description: Learn how to use Azure's Active Directory SSO with Coder. |
| 4 | +--- |
| 5 | + |
| 6 | +This article walks you through setting up single sign-on to Coder using Azure's |
| 7 | +Active directory. |
| 8 | + |
| 9 | +Configuring [Coder's OpenID Connect](/docs/admin/access-control#openid-connect) |
| 10 | +feature requires you to provide three pieces of information from Azure: |
| 11 | + |
| 12 | +- Client ID |
| 13 | +- Client Secret |
| 14 | +- Issuer |
| 15 | + |
| 16 | +This guide will show you how to set up Azure's Active Directory and obtain the |
| 17 | +information you need to provide to Coder. |
| 18 | + |
| 19 | +## Step 1: Register your app with Azure |
| 20 | + |
| 21 | +1. Log in to [Azure](https://portal.azure.com/). |
| 22 | +1. Using the search bar at the top, enter **App registrations** and click the |
| 23 | + matching search result. |
| 24 | + |
| 25 | +  |
| 26 | + |
| 27 | +1. Click **New registration**. |
| 28 | +1. Provide a **Name** for your application. |
| 29 | +1. Select the access option that best fits your needs; the **Default Directory |
| 30 | + only - Single tenant** option should be sufficient for testing, but you may |
| 31 | + need a **multitenant** option for production environments. |
| 32 | + |
| 33 | +  |
| 34 | + |
| 35 | +1. Provide your **Redirect URL** (it will be formatted similar to |
| 36 | + `https://coder.exampleCo.com/oidc/callback`). |
| 37 | +1. Click **Register** to proceed. |
| 38 | + |
| 39 | +When Azure has created your app, you'll be redirected to **Overview**, which |
| 40 | +displays the app information. |
| 41 | + |
| 42 | +## Step 2: Gather your Azure app information |
| 43 | + |
| 44 | +Once you've registered your app, you can obtain your: |
| 45 | + |
| 46 | +- Client ID |
| 47 | +- Client Secret |
| 48 | +- Issuer |
| 49 | + |
| 50 | +### Client ID |
| 51 | + |
| 52 | +On your application's **Overview**, look for the **Application (client) ID** |
| 53 | +under the **Essentials** section. This is the value Coder expects as the |
| 54 | +**Client ID**. |
| 55 | + |
| 56 | + |
| 57 | + |
| 58 | +### Client secret |
| 59 | + |
| 60 | +You'll need to create the client secret. To do so: |
| 61 | + |
| 62 | +1. Go to **Certificates & secrets**. |
| 63 | +1. Click **New client secret**. |
| 64 | +1. Provide a description for your secret and set an expiration date, and click |
| 65 | + **Add**. (We recommend creating a calendar notification to alert you shortly |
| 66 | + before your secret is set to expire.) |
| 67 | +1. You'll be redirected back to the **Certificates & secrets** page; save the |
| 68 | + **Value** field string for use as your client secret. |
| 69 | + |
| 70 | + |
| 71 | + |
| 72 | +### Issuer |
| 73 | + |
| 74 | +On your app's **Overview** page, click **Endpoints**. Find **OpenID Connect |
| 75 | +metadata document**, and copy the first 2/3s of this value. |
| 76 | + |
| 77 | + |
| 78 | + |
| 79 | +For example, if the full value is: |
| 80 | + |
| 81 | +```text |
| 82 | +https://login.microsoftonline.com/6a8e8517-e411-4f53-a4b9-aba6f1646271/v2.0/.well-known/openid-configuration |
| 83 | +``` |
| 84 | + |
| 85 | +Then remove `/.well-known/openid-configuration`, leaving the following as your |
| 86 | +issuer: |
| 87 | + |
| 88 | +```text |
| 89 | +https://login.microsoftonline.com/6a8e8...6271/v2.0 |
| 90 | +``` |
| 91 | + |
| 92 | +Be sure to keep `v2.0`, though you must omit the `/` from the end. |
| 93 | + |
| 94 | +> If there's an issue during the configuration process, the error message will |
| 95 | +> tell you the value you provided and the value it expected; you can use this |
| 96 | +> information to correct your configuration. |
| 97 | +
|
| 98 | +## Step 3: Configure Coder authentication |
| 99 | + |
| 100 | +Once you've saved your Azure values, you can complete the remaining steps using the |
| 101 | +Coder UI. |
| 102 | + |
| 103 | +1. Log in to Coder, and go to **Manage** > **Admin** > **Authentication**. |
| 104 | +1. In the top-most drop-down box, select **OpenID Connect**. |
| 105 | +1. Provide the requested values for **Client ID**, **Client Secret**, and |
| 106 | + **Issuer**. |
| 107 | + |
| 108 | +When done, click **Save Preferences**. |
| 109 | + |
| 110 | +At this point, Coder validates your configuration before proceeding. If |
| 111 | +successful, you can expect Coder to send OIDC login attempts to Azure. |
0 commit comments