Applies the Vale findings spike review's `ensure`, `should`, and `since` decisions, following `word-choice.md#choose-words-that-have-one-meaning`. ## `ensure`, `ensures`, `ensuring`: every row marked valid - 148 lines in 70 files. - Most became `make sure`, `makes sure`, or `making sure`. - When the subject isn't a person, I used a verb that reads better, such as `guarantees`, `keeps`, `prevents`, `maintains`, or `provides`. - `admin/monitoring/health-check.md:227`: "Make sure that" is now "Make sure", so the step stays within `Coder.StepLength`. - Left as-is: `admin/setup/configuration-reference.md:1339`, which is generated from `codersdk`. ## `should` and `since`: only rows with a verdict or a note - `.style/README.md`: "what should be routed elsewhere" is now "what to route elsewhere". - `.style/content-guidelines.md`: - "Avoid mixing those modes within a single page." - "Every page must be accurate" - "Check docs claims against the actual implementation" - "must include the documentation" - "Support owns the content they produce." - "because they don't change" - `.style/styles/Coder/README.md`: "must link to the matching section". - `admin/external-auth.md`: - "The redirect URI for Gitea is ..." - "Use custom authentication and token URLs ...", which is now active voice. - `envbuilder-releases-known-issues.md`: "so it's experimental and prone to breaking changes". Rows marked unsure with no note were left alone: `content-guidelines.md` lines 49, 330, and 405, and `envbuilder/index.md:24`. The changed files have no new findings from other rules. --- AI-generated by Superblink on behalf of @nickvigilante. --------- Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
3.2 KiB
title
| title |
|---|
| Microsoft Entra ID authentication (OIDC) |
This guide shows how to configure Coder to authenticate users with Microsoft Entra ID using OpenID Connect (OIDC)
Prerequisites
- A Microsoft Azure Entra ID Tenant
- Permission to create Applications in your Azure environment
Step 1: Create an OAuth App Registration in Microsoft Azure
-
Open Microsoft Azure Portal (https://portal.azure.com) → Microsoft Entra ID → App Registrations → New Registration
-
Name: Name your application appropriately
-
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"
-
Select "Register"
-
On the next screen, select: "Certificates and Secrets"
-
Select "New Client Secret" and under description, enter an appropriate description.
-
Set an expiry and hit "Add".
-
Once it's created, copy the value and save it somewhere secure for the next step
-
Select the tab labeled "Token Configuration", then select "Add optional claim".
-
Select the "ID" radio button, and finally check "upn" and hit "add" at the bottom
-
Select the button labeled Add groups claim.
-
Check Security groups.
-
Select Save.
-
Select the tab labeled "Authentication" and select "Add a platform".
-
Select "Web" and for the redirect Uniform Resource Identifier (URI) enter your Coder callback URL.
-
Then select "Configure" at the bottom:
https://coder.example.com/api/v2/users/oidc/callback
Step 2: Configure Coder OIDC for Microsoft Entra ID
Set the following environment variables on your Coder deployment and restart Coder:
CODER_OIDC_ISSUER_URL=https://login.microsoftonline.com/{tenant-id}/v2.0 # Replace {tenant-id} with your Azure tenant ID
CODER_OIDC_CLIENT_ID=<client id, located in "Overview">
CODER_OIDC_CLIENT_SECRET=<client secret, saved from step 8>
# Restrict to one or more email domains (comma-separated)
CODER_OIDC_EMAIL_DOMAIN="example.com"
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.
CODER_OIDC_GROUP_FIELD="groups" # This is for group sync / IdP Sync, a premium feature.
# Optional: customize the login button
CODER_OIDC_SIGN_IN_TEXT="Sign in with Microsoft Entra ID"
CODER_OIDC_ICON_URL=/icon/microsoft.svg
Note
The redirect URI must exactly match what you configured in Microsoft Azure Entra ID
Enable refresh tokens (recommended)
# Keep standard scopes
CODER_OIDC_SCOPES=openid,profile,email,offline_access
After changing settings, users must log out and back in once to obtain refresh tokens
Learn more in Configure OIDC refresh tokens.
Troubleshooting
- "invalid redirect_uri": make sure the redirect URI in Azure Entra ID matches
https://<your-coder-host>/api/v2/users/oidc/callback - Domain restriction: if users from unexpected domains can log in, verify
CODER_OIDC_EMAIL_DOMAIN - Claims: to inspect claims returned by Microsoft, see guidance in the OIDC overview