diff --git a/docs/admin/users/oidc-auth/microsoft.md b/docs/admin/users/oidc-auth/microsoft.md new file mode 100644 index 0000000000000..8acf2191a9d58 --- /dev/null +++ b/docs/admin/users/oidc-auth/microsoft.md @@ -0,0 +1,63 @@ +# 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. Click on "Register" +5. On the next screen, select: "Certificates and Secrets" +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 +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 +8. Then, click on the button labeled "Add groups claim" and check "Security groups" and click "Save" at the bottom +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: + - `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: + +```env +CODER_OIDC_ISSUER_URL=https://login.microsoftonline.com/{tenant-id}/v2.0 # Replace {tenant-id} with your Azure tenant ID +CODER_OIDC_CLIENT_ID= +CODER_OIDC_CLIENT_SECRET= +# 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) + +```env +# Keep standard scopes +CODER_OIDC_SCOPES=openid,profile,email +``` + +After changing settings, users must log out and back in once to obtain refresh tokens + +Learn more in [Configure OIDC refresh tokens](./refresh-tokens.md). + +## Troubleshooting + +- "invalid redirect_uri": ensure the redirect URI in Azure Entra ID matches `https:///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](./index.md#oidc-claims) + +## See also + +- [OIDC overview](./index.md) +- [Configure OIDC refresh tokens](./refresh-tokens.md) diff --git a/docs/manifest.json b/docs/manifest.json index 8f624cb7f220c..2b67534d948a8 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -437,6 +437,11 @@ "description": "Configure Google as an OIDC provider", "path": "./admin/users/oidc-auth/google.md" }, + { + "title": "Microsoft", + "description": "Configure Microsoft Entra ID as an OIDC provider", + "path": "./admin/users/oidc-auth/microsoft.md" + }, { "title": "Configure OIDC refresh tokens", "description": "How to configure OIDC refresh tokens", diff --git a/docs/tutorials/faqs.md b/docs/tutorials/faqs.md index a2f350b45a734..f2a0902eb790f 100644 --- a/docs/tutorials/faqs.md +++ b/docs/tutorials/faqs.md @@ -559,3 +559,27 @@ confidential resources to their local machines. For more advanced security needs, consider adopting an endpoint security solution. + +## How do I change the access URL for my Coder server? + +You may want to change the default domain that's used to access coder, i.e. `yourcompany.coder.com` and find yourself unfamiliar with the process. + +To change the access URL associated with your server, you can edit any of the following variables: + +- CLI using the `--access-url` flag +- YAML using the `accessURL` option +- or ENV using the `CODER_ACCESS_URL` environmental variable. + +For example, if you're using an environment file to configure your server, you'll want to edit the file located at `/etc/coder.d/coder.env` and edit the following: + +`CODER_ACCESS_URL=https://yourcompany.coder.com` to your new desired URL. + +Then save your changes, and reload daemon-ctl using the following command: + +`systemctl daemon-reload` + +and restart the service using: + +`systemctl restart coder` + +After coder restarts, your changes should be applied and should reflect in the admin settings.