|
| 1 | +#Microsoft Entra ID authentication (OIDC) |
| 2 | + |
| 3 | +This guide shows how to configure Coder to authenticate users with Microsoft Entra ID using OpenID Connect (OIDC) |
| 4 | + |
| 5 | +##Prerequisites |
| 6 | + |
| 7 | +- A Microsoft Azure Entra ID Tenant |
| 8 | +- Permission to create Applications in your Azure environment |
| 9 | + |
| 10 | +##Step 1: Create an OAuth App Registration in Microsoft Azure |
| 11 | + |
| 12 | +1. Open Microsoft Azure Portal (https://portal.azure.com) → Microsoft Entra ID → App Registrations → New Registration |
| 13 | +2. Name: Name your application appropriately |
| 14 | +3. Supported Account Types: Choose the appropriate radio button according to your needs. Most organizations will want to use the first one labeled "Accounts in this organizational directory only" |
| 15 | +4. Click on "Register" |
| 16 | +5. On the next screen, select: "Certificates and Secrets" |
| 17 | +6. Click on "New Client Secret" and under description, enter an appropriate description. Then set an expiry and hit "Add" once it's created, copy the value and save it somewhere secure for the next step |
| 18 | +7. Next, click on the tab labeled "Token Configuration", then click "Add optional claim" and select the "ID" radio button, and finally check "upn" and hit "add" at the bottom |
| 19 | +8. Then, click on the button labeled "Add groups claim" and check "Security groups" and click "Save" at the bottom |
| 20 | +9. Now, click on the tab labeled "Authentication" and click on "Add a platform", select "Web" and for the redirect URI enter your Coder callback URL, and then hit "Configure" at the bottom: |
| 21 | +-`https://coder.example.com/api/v2/users/oidc/callback` |
| 22 | + |
| 23 | +##Step 2: Configure Coder OIDC for Microsoft Entra ID |
| 24 | + |
| 25 | +Set the following environment variables on your Coder deployment and restart Coder: |
| 26 | + |
| 27 | +```env |
| 28 | +CODER_OIDC_ISSUER_URL=https://login.microsoftonline.com/{tenant-id}/v2.0 # Replace {tenant-id} with your Azure tenant ID |
| 29 | +CODER_OIDC_CLIENT_ID=<client id, located in "Overview"> |
| 30 | +CODER_OIDC_CLIENT_SECRET=<client secret, saved from step 6> |
| 31 | +# Restrict to one or more email domains (comma-separated) |
| 32 | +CODER_OIDC_EMAIL_DOMAIN="example.com" |
| 33 | +CODER_OIDC_EMAIL_FIELD="upn" # This is set because EntraID typically uses .onmicrosoft.com domains by default, this should pull the user's username@domain email. |
| 34 | +CODER_OIDC_GROUP_FIELD="groups" # This is for group sync / IdP Sync, a premium feature. |
| 35 | +# Optional: customize the login button |
| 36 | +CODER_OIDC_SIGN_IN_TEXT="Sign in with Microsoft Entra ID" |
| 37 | +CODER_OIDC_ICON_URL=/icon/microsoft.svg |
| 38 | +``` |
| 39 | + |
| 40 | +>[!NOTE] |
| 41 | +>The redirect URI must exactly match what you configured in Microsoft Azure Entra ID |
| 42 | +
|
| 43 | +##Enable refresh tokens (recommended) |
| 44 | + |
| 45 | +```env |
| 46 | +# Keep standard scopes |
| 47 | +CODER_OIDC_SCOPES=openid,profile,email |
| 48 | +``` |
| 49 | + |
| 50 | +After changing settings, users must log out and back in once to obtain refresh tokens |
| 51 | + |
| 52 | +Learn more in[Configure OIDC refresh tokens](./refresh-tokens.md). |
| 53 | + |
| 54 | +##Troubleshooting |
| 55 | + |
| 56 | +- "invalid redirect_uri": ensure the redirect URI in Azure Entra ID matches`https://<your-coder-host>/api/v2/users/oidc/callback` |
| 57 | +- Domain restriction: if users from unexpected domains can log in, verify`CODER_OIDC_EMAIL_DOMAIN` |
| 58 | +- Claims: to inspect claims returned by Microsoft, see guidance in the[OIDC overview](./index.md#oidc-claims) |
| 59 | + |
| 60 | +##See also |
| 61 | + |
| 62 | +-[OIDC overview](./index.md) |
| 63 | +-[Configure OIDC refresh tokens](./refresh-tokens.md) |