Files
coder/docs/admin/users/oidc-auth/microsoft.md
T
coder[bot] 155861f04e docs: replace ensure, should, and since per the Vale spike review (#31879)
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>
2026-11-06 22:26:01 +00:00

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

  1. Open Microsoft Azure Portal (https://portal.azure.com) → Microsoft Entra ID → App Registrations → New Registration

  2. Name: Name your application appropriately

  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"

  4. Select "Register"

  5. On the next screen, select: "Certificates and Secrets"

  6. Select "New Client Secret" and under description, enter an appropriate description.

  7. Set an expiry and hit "Add".

  8. Once it's created, copy the value and save it somewhere secure for the next step

  9. Select the tab labeled "Token Configuration", then select "Add optional claim".

  10. Select the "ID" radio button, and finally check "upn" and hit "add" at the bottom

  11. Select the button labeled Add groups claim.

  12. Check Security groups.

  13. Select Save.

  14. Select the tab labeled "Authentication" and select "Add a platform".

  15. Select "Web" and for the redirect Uniform Resource Identifier (URI) enter your Coder callback URL.

  16. 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

# 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

See also