From 92cc64539cf2be42f66c6e3cdc4d4c50f0efba52 Mon Sep 17 00:00:00 2001 From: "Phoenix J. Shepherd" Date: Tue, 7 Oct 2025 19:42:57 +0000 Subject: [PATCH 01/10] Add Microsoft Entra ID OIDC Directions --- docs/admin/users/oidc-auth/microsoft.md | 62 +++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 docs/admin/users/oidc-auth/microsoft.md diff --git a/docs/admin/users/oidc-auth/microsoft.md b/docs/admin/users/oidc-auth/microsoft.md new file mode 100644 index 0000000000000..e48c769ff4f1d --- /dev/null +++ b/docs/admin/users/oidc-auth/microsoft.md @@ -0,0 +1,62 @@ +# 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 client in Google Cloud + +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 organizaitons 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 Google + +Set the following environment variables on your Coder deployment and restart Coder: + +```env +CODER_OIDC_ISSUER_URL= +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. +# 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 Google, see guidance in the [OIDC overview](./index.md#oidc-claims). + +## See also + +- [OIDC overview](./index.md) +- [Configure OIDC refresh tokens](./refresh-tokens.md) From 5a4280d3832c578f20a4cb3da463cddb399df419 Mon Sep 17 00:00:00 2001 From: "Phoenix J. Shepherd" Date: Tue, 7 Oct 2025 19:51:51 +0000 Subject: [PATCH 02/10] Missed a few things, whoops. --- docs/admin/users/oidc-auth/microsoft.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/admin/users/oidc-auth/microsoft.md b/docs/admin/users/oidc-auth/microsoft.md index e48c769ff4f1d..cbce8fa9af1f0 100644 --- a/docs/admin/users/oidc-auth/microsoft.md +++ b/docs/admin/users/oidc-auth/microsoft.md @@ -7,7 +7,7 @@ This guide shows how to configure Coder to authenticate users with Microsoft Ent - A Microsoft Azure Entra ID Tenant - Permission to create Applications in your Azure environment -## Step 1: Create an OAuth client in Google Cloud +## 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 @@ -20,7 +20,7 @@ This guide shows how to configure Coder to authenticate users with Microsoft Ent 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 Google +## Step 2: Configure Coder OIDC for Microsoft Entra ID Set the following environment variables on your Coder deployment and restart Coder: @@ -54,7 +54,7 @@ Learn more in [Configure OIDC refresh tokens](./refresh-tokens.md). - "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 Google, see guidance in the [OIDC overview](./index.md#oidc-claims). +- Claims: to inspect claims returned by Microsoft, see guidance in the [OIDC overview](./index.md#oidc-claims). ## See also From 6fa26dca6c2dae2047a941c2da33dcf32f1535ec Mon Sep 17 00:00:00 2001 From: Jacob Witt Date: Tue, 7 Oct 2025 14:56:30 -0500 Subject: [PATCH 03/10] Update docs/admin/users/oidc-auth/microsoft.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/admin/users/oidc-auth/microsoft.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/users/oidc-auth/microsoft.md b/docs/admin/users/oidc-auth/microsoft.md index cbce8fa9af1f0..8f0cd8483dd7e 100644 --- a/docs/admin/users/oidc-auth/microsoft.md +++ b/docs/admin/users/oidc-auth/microsoft.md @@ -11,7 +11,7 @@ This guide shows how to configure Coder to authenticate users with Microsoft Ent 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 organizaitons will want to use the first one labeled "Accounts in this organizational directory only" +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. From 6c9dc1f8dd7e20dcdff9319742283f2c52e132fa Mon Sep 17 00:00:00 2001 From: Jacob Witt Date: Tue, 7 Oct 2025 14:56:54 -0500 Subject: [PATCH 04/10] Update docs/admin/users/oidc-auth/microsoft.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/admin/users/oidc-auth/microsoft.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/users/oidc-auth/microsoft.md b/docs/admin/users/oidc-auth/microsoft.md index 8f0cd8483dd7e..9e49e38ea1b46 100644 --- a/docs/admin/users/oidc-auth/microsoft.md +++ b/docs/admin/users/oidc-auth/microsoft.md @@ -25,7 +25,7 @@ This guide shows how to configure Coder to authenticate users with Microsoft Ent Set the following environment variables on your Coder deployment and restart Coder: ```env -CODER_OIDC_ISSUER_URL= +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) From 3edc9deca34cae0258cf1ef2322e591e5dd65cb6 Mon Sep 17 00:00:00 2001 From: Jacob Witt Date: Tue, 7 Oct 2025 14:57:03 -0500 Subject: [PATCH 05/10] Update docs/admin/users/oidc-auth/microsoft.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/admin/users/oidc-auth/microsoft.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/users/oidc-auth/microsoft.md b/docs/admin/users/oidc-auth/microsoft.md index 9e49e38ea1b46..0099966329b2f 100644 --- a/docs/admin/users/oidc-auth/microsoft.md +++ b/docs/admin/users/oidc-auth/microsoft.md @@ -26,7 +26,7 @@ Set the following environment variables on your Coder deployment and restart Cod ```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_ID= CODER_OIDC_CLIENT_SECRET= # Restrict to one or more email domains (comma-separated) CODER_OIDC_EMAIL_DOMAIN="example.com" From 4602c69f9f7bc1d0bfb98e3daa2ac816b9d6b32c Mon Sep 17 00:00:00 2001 From: "Phoenix J. Shepherd" Date: Tue, 7 Oct 2025 20:02:11 +0000 Subject: [PATCH 06/10] add microsoft.md to manifest --- docs/manifest.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/manifest.json b/docs/manifest.json index 342326c99a760..ebb75c9f892be 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -427,6 +427,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", From 49a855d60a998fb4c0d1b5c576632694be538d27 Mon Sep 17 00:00:00 2001 From: "Phoenix J. Shepherd" Date: Wed, 8 Oct 2025 16:22:21 +0000 Subject: [PATCH 07/10] docs: provide information on changing access URL in FAQs. --- docs/tutorials/faqs.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/tutorials/faqs.md b/docs/tutorials/faqs.md index a2f350b45a734..b2b47cd57cdc6 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 unfamilar 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. From ed126440634aeae33c8a348e5a71703fc4ef3727 Mon Sep 17 00:00:00 2001 From: "Phoenix J. Shepherd" Date: Wed, 22 Oct 2025 02:02:32 +0000 Subject: [PATCH 08/10] Add suggested changes --- docs/admin/users/oidc-auth/microsoft.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/admin/users/oidc-auth/microsoft.md b/docs/admin/users/oidc-auth/microsoft.md index 0099966329b2f..8acf2191a9d58 100644 --- a/docs/admin/users/oidc-auth/microsoft.md +++ b/docs/admin/users/oidc-auth/microsoft.md @@ -1,6 +1,6 @@ # Microsoft Entra ID authentication (OIDC) -This guide shows how to configure Coder to authenticate users with Microsoft Entra ID using OpenID Connect (OIDC). +This guide shows how to configure Coder to authenticate users with Microsoft Entra ID using OpenID Connect (OIDC) ## Prerequisites @@ -9,14 +9,14 @@ This guide shows how to configure Coder to authenticate users with Microsoft Ent ## 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. +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. +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` @@ -31,13 +31,14 @@ 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. +> The redirect URI must exactly match what you configured in Microsoft Azure Entra ID ## Enable refresh tokens (recommended) @@ -46,15 +47,15 @@ CODER_OIDC_ICON_URL=/icon/microsoft.svg CODER_OIDC_SCOPES=openid,profile,email ``` -After changing settings, users must log out and back in once to obtain refresh tokens. +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). +- "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 From b0d0d077df5517aea5d2088a4a6c7aecc3df7559 Mon Sep 17 00:00:00 2001 From: DevCats Date: Wed, 22 Oct 2025 15:17:48 -0500 Subject: [PATCH 09/10] chore: fix typo --- docs/tutorials/faqs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/faqs.md b/docs/tutorials/faqs.md index b2b47cd57cdc6..73373d1e295d0 100644 --- a/docs/tutorials/faqs.md +++ b/docs/tutorials/faqs.md @@ -562,7 +562,7 @@ 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 unfamilar with the process. +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: From 3ae3382981c0e9e774952e667a80e7f998b82a77 Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Fri, 24 Oct 2025 12:41:37 -0500 Subject: [PATCH 10/10] chore: run lint-docs --- docs/tutorials/faqs.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/faqs.md b/docs/tutorials/faqs.md index 73373d1e295d0..f2a0902eb790f 100644 --- a/docs/tutorials/faqs.md +++ b/docs/tutorials/faqs.md @@ -566,9 +566,9 @@ You may want to change the default domain that's used to access coder, i.e. `you 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. +- 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: