Jun 16, 2025 · Jun 11, 2025 · Jun 11, 2025 · Jun 12, 2025 · Jun 12, 2025 · Jun 12, 2025
diff --git a/docs/README.md b/docs/README.md
 - **Increased security**

  - Centralize source code and other data onto private servers or cloud services instead of local developers' machines.
  - Manage users and groups with [SSO](./admin/users/oidc-auth.md) and [Role-based access controlled (RBAC)](./admin/users/groups-roles.md#roles).
  - Manage users and groups with [SSO](./admin/users/oidc-auth/index.md) and [Role-based access controlled (RBAC)](./admin/users/groups-roles.md#roles).

 - **Improved compatibility**

diff --git a/docs/admin/external-auth.md → docs/admin/external-auth/index.md b/docs/admin/external-auth.md → docs/admin/external-auth/index.md
diff --git a/docs/admin/infrastructure/architecture.md b/docs/admin/infrastructure/architecture.md
 provider. The Coder control plane and workspaces will need network connectivity
 to the git provider.

 - [GitHub Enterprise](../external-auth.md#github-enterprise)
 - [GitLab](../external-auth.md#gitlab-self-managed)
 - [BitBucket](../external-auth.md#bitbucket-server)
 - [Other Providers](../external-auth.md#self-managed-git-providers)
 - [GitHub Enterprise](../external-auth/index.md#github-enterprise)
 - [GitLab](../external-auth/index.md#gitlab-self-managed)
 - [BitBucket](../external-auth/index.md#bitbucket-server)
 - [Other Providers](../external-auth/index.md#self-managed-git-providers)

 ### Artifact Manager (Optional)

diff --git a/docs/admin/integrations/jfrog-artifactory.md b/docs/admin/integrations/jfrog-artifactory.md
 ### JFrog-OAuth

 This module is usable by JFrog self-hosted (on-premises) Artifactory as it
 requires configuring a custom integration. This integration benefits from Coder's [external-auth](../../admin/external-auth.md) feature allows each user to authenticate with Artifactory using an OAuth flow and issues user-scoped tokens to each user.
 requires configuring a custom integration. This integration benefits from Coder's [external-auth](../external-auth/index.md) feature allows each user to authenticate with Artifactory using an OAuth flow and issues user-scoped tokens to each user.

 To set this up, follow these steps:

   `https://JFROG_URL/ui/admin/configuration/integrations/app-integrations/new` and select the
   Application Type as the integration you created in step 1 or `Custom Integration` if you are using SaaS instance i.e. example.jfrog.io.

 1. Add a new [external authentication](../../admin/external-auth.md) to Coder by setting these
 1. Add a new [external authentication](../external-auth/index.md) to Coder by setting these
   environment variables in a manner consistent with your Coder deployment. Replace `JFROG_URL` with your JFrog Artifactory base URL:

   ```env
diff --git a/docs/admin/integrations/vault.md b/docs/admin/integrations/vault.md

 The [`vault-github`](https://registry.coder.com/modules/vault-github) module is a Terraform module that allows you to
 authenticate with Vault using a GitHub token. This module uses the existing
 GitHub [external authentication](../external-auth.md) to get the token and authenticate with Vault.
 GitHub [external authentication](../external-auth/index.md) to get the token and authenticate with Vault.

 To use this module, add the following code to your Terraform configuration.

diff --git a/docs/admin/setup/appearance.md b/docs/admin/setup/appearance.md

 ## OIDC Login Button Customization

 [Use environment variables to customize](../users/oidc-auth.md#oidc-login-customization)
 [Use environment variables to customize](../users/oidc-auth/index.md#oidc-login-customization)
 the text and icon on the OIDC button on the Sign In page.

 ## Support Links
diff --git a/docs/admin/setup/index.md b/docs/admin/setup/index.md
 External authentication can also be used to integrate with external services
 like JFrog Artifactory and others.

 Please refer to the [external authentication](../external-auth.md) section for
 Please refer to the [external authentication](../external-auth/index.md) section for
 more information.

 ## Up Next
diff --git a/docs/admin/templates/extending-templates/icons.md b/docs/admin/templates/extending-templates/icons.md
  }
  ```

 - [**Authentication Providers**](https://coder.com/docs/admin/external-auth):
 - [**Authentication Providers**](../../external-auth/index.md):

  - Use icons for external authentication providers to make them recognizable.
    You can set an icon for each provider by setting the
diff --git a/docs/admin/templates/open-in-coder.md b/docs/admin/templates/open-in-coder.md

 ### 1. Set up git authentication

 See [External Authentication](../external-auth.md) to set upgit authentication
 See [External Authentication](../external-auth/index.md) to set upGit authentication
 in your Coder deployment.

 ### 2. Modify your template to auto-clone repos
diff --git a/docs/admin/users/idp-sync.md b/docs/admin/users/idp-sync.md

   ```env
    # Depending on your identity provider configuration, you may need to explicitly request a "roles" scope
   CODER_OIDC_SCOPES=openid,profile,email,roles
   CODER_OIDC_SCOPES=openid,profile,email,offline_access,roles

   # The following fields are required for role sync:
   CODER_OIDC_USER_ROLE_FIELD=roles

 ## Provider-Specific Guides

 Below are some details specific to individual OIDC providers.
 <div class="tabs">

 ### Active Directory Federation Services (ADFS)


 ### Keycloak

 <!-- copied in refresh-tokens.md. make changes there too. -->

 The `access_type` parameter has two possible values: `online` and `offline`.
 By default, the value is set to `offline`.


 ### Google

 <!-- copied in refresh-tokens.md. make changes there too. -->

 To ensure Coder receives a refresh token when users authenticate with Google
 directly, set the `prompt` to `consent` in the auth URL parameters. Without
 this, users will be logged out after 1 hour.
 ```shell
 CODER_OIDC_AUTH_URL_PARAMS='{"access_type": "offline", "prompt": "consent"}'
 ```

 </div>
diff --git a/docs/admin/users/index.md b/docs/admin/users/index.md

 ##Configuring SSO

 -[OpenID Connect](./oidc-auth.md) (e.g. Okta, KeyCloak, PingFederate, Azure AD)
 -[OpenID Connect](./oidc-auth/index.md) (e.g. Okta, KeyCloak, PingFederate, Azure AD)
 -[GitHub](./github-auth.md) (or GitHub Enterprise)

 ##Groups
diff --git a/docs/admin/users/oidc-auth.md → docs/admin/users/oidc-auth/index.md b/docs/admin/users/oidc-auth.md → docs/admin/users/oidc-auth/index.md
diff --git a/docs/admin/users/oidc-auth/refresh-tokens.md b/docs/admin/users/oidc-auth/refresh-tokens.md
 # Configure OIDC refresh tokens

 OIDC refresh tokens allow your Coder deployment to maintain user sessions beyond the initial access token expiration.
 Without properly configured refresh tokens, users will be automatically logged out when their access token expires.
 This is typically after one hour, but varies by provider, and can disrupt the user's workflow.

 > [!IMPORTANT]
 > Misconfigured refresh tokens can lead to frequent user authentication prompts.
 >
 > After the admin enables refresh tokens, all existing users must log out and back in again to obtain a refresh token.

 <div class="tabs">

 ### Azure AD

 Go to the Azure Portal > **Azure Active Directory** > **App registrations** > Your Coder app and make the following changes:

 1. In the **Authentication** tab:

   - **Platform configuration** > Web
   - Ensure **Allow public client flows** is `No` (Coder is confidential)
   - **Implicit grant / hybrid flows** can stay unchecked

 1. In the **API permissions** tab:

   - Add the built-in permission `offline_access` under **Microsoft Graph** > **Delegated permissions**
   - Keep `openid`, `profile`, and `email`

 1. In the **Certificates & secrets** tab:

   - Verify a Client secret (or certificate) is valid.
     Coder uses it to redeem refresh tokens.

 1. In your [Coder configuration](../../../reference/cli/server.md#--oidc-auth-url-params), request the same scopes:

   ```env
   CODER_OIDC_SCOPES=openid,profile,email,offline_access
   ```

 1. Restart Coder and have users log out and back again for the changes to take effect.

   Alternatively, you can force a sign-out for all users with the
   [sign-out request process](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc#send-a-sign-out-request).

 1. Azure issues rolling refresh tokens with a default absolute expiration of 90 days and inactivity expiration of 24 hours.

   You can adjust these settings under **Authentication methods** > **Token lifetime** (or use Conditional-Access policies in Entra ID).

 > [!NOTE]
 > You don't need to configure the 'Expose an API' section for refresh tokens to work.

 Learn more in the [Microsoft Entra documentation](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc#enable-id-tokens).

 ### Google

 To ensure Coder receives a refresh token when users authenticate with Google directly, set the `prompt` to `consent`
 in the auth URL parameters (`CODER_OIDC_AUTH_URL_PARAMS`).
 Without this, users will be logged out when their access token expires.

 In your [Coder configuration](../../../reference/cli/server.md#--oidc-auth-url-params):

 ```env
 CODER_OIDC_SCOPES=openid,profile,email
 CODER_OIDC_AUTH_URL_PARAMS='{"access_type": "offline", "prompt": "consent"}'
 ```

 ### Keycloak

 The `access_type` parameter has two possible values: `online` and `offline`.
 By default, the value is set to `offline`.

 This means that when a user authenticates using OIDC, the application requests offline access to the user's resources,
 including the ability to refresh access tokens without requiring the user to reauthenticate.

 Add the `offline_access` scope to enable refresh tokens in your
 [Coder configuration](../../../reference/cli/server.md#--oidc-auth-url-params):

 ```env
 CODER_OIDC_SCOPES=openid,profile,email,offline_access
 CODER_OIDC_AUTH_URL_PARAMS='{"access_type":"offline"}'
 ```

 ### PingFederate

 1. In PingFederate go to **Applications** > **OAuth Clients** > Your Coder client.

 1. On the **Client** tab:

   - **Grant Types**: Enable `refresh_token`
   - **Allowed Scopes**: Add `offline_access` and keep `openid`, `profile`, and `email`

 1. Optionally, in **Token Settings**

   - **Refresh Token Lifetime**: set a value that matches your security policy. Ping's default is 30 days.
   - **Idle Timeout**: ensure it's more than or equal to the lifetime of the access token so that refreshes don't fail prematurely.

 1. Save your changes in PingFederate.

 1. In your [Coder configuration](../../../reference/cli/server.md#--oidc-scopes), add the `offline_access` scope:

   ```env
   CODER_OIDC_SCOPES=openid,profile,email,offline_access
   ```

 1. Restart your Coder deployment to apply these changes.

 Users must log out and log in once to store their new refresh tokens.
 After that, sessions should last until the Ping Federate refresh token expires.

 Learn more in the [PingFederate documentation](https://docs.pingidentity.com/pingfederate/12.2/administrators_reference_guide/pf_configuring_oauth_clients.html).

 </div>

 ## Confirm refresh token configuration

 To verify refresh tokens are working correctly:

 1. Check that your OIDC configuration includes the required refresh token parameters:

     - `offline_access` scope for most providers
     - `"access_type": "offline"` for Google

 1. Verify provider-specific token configuration:

   <div class="tabs">

   ### Azure AD

   Use [jwt.ms](https://jwt.ms) to inspect the `id_token` and ensure the `rt_hash` claim is present.
   This shows that a refresh token was issued.

   ### Google

   If users are still being logged out periodically, check your client configuration in Google Cloud Console.

   ### Keycloak

   Review Keycloak sessions for the presence of refresh tokens

   ### Ping Federate

   - Verify the client sent `offline_access` in the `grantedScopes` portion of the ID token
   - Confirm `refresh_token` appears in the `grant_types` list returned by `/pf-admin-api/v1/oauth/clients/{id}`

   </div>

 1. Verify users can stay logged in beyond the identity provider's access token expiration period (typically 1 hour).

 1. Monitor Coder logs for `failed to renew OIDC token: token has expired` messages.
   There should not be any.

 If all verification steps pass successfully, your refresh token configuration is working properly.

 ## Troubleshooting OIDC Refresh Tokens

 ### Users are logged out too frequently

 **Symptoms**:

 - Users experience session timeouts and must re-authenticate
 - Session timeouts typically occur after the access token expiration period (varies by provider, commonly 1 hour)

 **Causes**:

 - Missing `offline_access` scope in `CODER_OIDC_SCOPES`
 - Provider not configured to issue refresh tokens
 - User has not logged in since refresh token configuration was added

 **Solution**:

 - Add `offline_access` to your `CODER_OIDC_SCOPES` configuration
 - Configure your identity provider according to the provider-specific instructions above
 - Have users log out and log in again to obtain refresh tokens.
  Look for entries containing `failed to renew OIDC token` which might indicate specific provider issues.

 Users might get logged out again before the new configuration takes effect completely.

 ### Refresh tokens don't work after configuration change

 **Symptoms**:

 - Session timeouts continue despite refresh token configuration and users re-authenticating
 - Some users experience frequent logouts

 **Cause**:

 - Existing user sessions don't have refresh tokens stored
 - Configuration may be incomplete

 **Solution**:

 - Users must log out and log in again to get refresh tokens stored in the database
 - Verify you've correctly configured your provider as described in the configuration steps above
 - Check Coder logs for specific error messages related to token refresh
diff --git a/docs/ai-coder/best-practices.md b/docs/ai-coder/best-practices.md
  development without manual intervention (e.g. repos are cloned, dependencies
  are built, secrets are added/mocked, etc.).

  > Note: [External authentication](../admin/external-auth.md) can be helpful
  > Note: [External authentication](../admin/external-auth/index.md) can be helpful
  > to authenticate with third-party services such as GitHub or JFrog.

 - Give your agent the proper tools via MCP to interact with your codebase and
diff --git a/docs/manifest.json b/docs/manifest.json
 {
 "title": "OIDC Authentication",
 "description": "Configure OpenID Connect authentication with identity providers like Okta or Active Directory",
 "path": "./admin/users/oidc-auth.md"
 "path": "./admin/users/oidc-auth/index.md",
 "children": [
 {
 "title": "Configure OIDC refresh tokens",
 "description": "How to configure OIDC refresh tokens",
 "path": "./admin/users/oidc-auth/refresh-tokens.md"
 }
 ]
 },
 {
 "title": "GitHub Authentication",
 {
 "title": "External Authentication",
 "description": "Learn how to configure external authentication",
 "path": "./admin/external-auth.md",
 "path": "./admin/external-auth/index.md",
 "icon_path": "./images/icons/plug.svg"
 },
 {
diff --git a/docs/tutorials/best-practices/security-best-practices.md b/docs/tutorials/best-practices/security-best-practices.md

 ### User authentication

 Configure [OIDC authentication](../../admin/users/oidc-auth.md) against your
 Configure [OIDC authentication](../../admin/users/oidc-auth/index.md) against your
 organization’s Identity Provider (IdP), such as Okta, to allow single-sign on.

 1. Enable and require two-factor authentication in your identity provider.
diff --git a/docs/tutorials/cloning-git-repositories.md b/docs/tutorials/cloning-git-repositories.md
 as an authentication method. If you don't know how to do that, we have written
 documentation to help you:

 - [GitHub](../admin/external-auth.md#github)
 - [GitLab self-managed](../admin/external-auth.md#gitlab-self-managed)
 - [Self-managed git providers](../admin/external-auth.md#self-managed-git-providers)
 - [GitHub](../admin/external-auth/index.md#github)
 - [GitLab self-managed](../admin/external-auth/index.md#gitlab-self-managed)
 - [Self-managed git providers](../admin/external-auth/index.md#self-managed-git-providers)

 With the authentication in place, it is time to set up the template to use the
 [Git Clone module](https://registry.coder.com/modules/git-clone) from the
Original file line number	Diff line number	Diff line change
Expand Up		@@ -49,7 +49,7 @@ Remote development offers several benefits for users and administrators, includi
		- Increased security

		- Centralize source code and other data onto private servers or cloud services instead of local developers' machines.
		- Manage users and groups with [SSO](./admin/users/oidc-auth.md) and [Role-based access controlled (RBAC)](./admin/users/groups-roles.md#roles).
		- Manage users and groups with [SSO](./admin/users/oidc-auth/index.md) and [Role-based access controlled (RBAC)](./admin/users/groups-roles.md#roles).

		- Improved compatibility

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -108,10 +108,10 @@ Users will likely need to pull source code and other artifacts from a git
		provider. The Coder control plane and workspaces will need network connectivity
		to the git provider.

		- [GitHub Enterprise](../external-auth.md#github-enterprise)
		- [GitLab](../external-auth.md#gitlab-self-managed)
		- [BitBucket](../external-auth.md#bitbucket-server)
		- [Other Providers](../external-auth.md#self-managed-git-providers)
		- [GitHub Enterprise](../external-auth/index.md#github-enterprise)
		- [GitLab](../external-auth/index.md#gitlab-self-managed)
		- [BitBucket](../external-auth/index.md#bitbucket-server)
		- [Other Providers](../external-auth/index.md#self-managed-git-providers)

		### Artifact Manager (Optional)

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -26,7 +26,7 @@ two type of modules that automate the JFrog Artifactory and Coder integration.
		### JFrog-OAuth

		This module is usable by JFrog self-hosted (on-premises) Artifactory as it
		requires configuring a custom integration. This integration benefits from Coder's [external-auth](../../admin/external-auth.md) feature allows each user to authenticate with Artifactory using an OAuth flow and issues user-scoped tokens to each user.
		requires configuring a custom integration. This integration benefits from Coder's [external-auth](../external-auth/index.md) feature allows each user to authenticate with Artifactory using an OAuth flow and issues user-scoped tokens to each user.

		To set this up, follow these steps:

Expand All		@@ -53,7 +53,7 @@ To set this up, follow these steps:
		`https://JFROG_URL/ui/admin/configuration/integrations/app-integrations/new` and select the
		Application Type as the integration you created in step 1 or `Custom Integration` if you are using SaaS instance i.e. example.jfrog.io.

		1. Add a new [external authentication](../../admin/external-auth.md) to Coder by setting these
		1. Add a new [external authentication](../external-auth/index.md) to Coder by setting these
		environment variables in a manner consistent with your Coder deployment. Replace `JFROG_URL` with your JFrog Artifactory base URL:

		```env
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -19,7 +19,7 @@ will show you how to use these modules to integrate HashiCorp Vault with Coder.

		The [`vault-github`](https://registry.coder.com/modules/vault-github) module is a Terraform module that allows you to
		authenticate with Vault using a GitHub token. This module uses the existing
		GitHub [external authentication](../external-auth.md) to get the token and authenticate with Vault.
		GitHub [external authentication](../external-auth/index.md) to get the token and authenticate with Vault.

		To use this module, add the following code to your Terraform configuration.

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -41,7 +41,7 @@ users of which network their Coder deployment is on.

		## OIDC Login Button Customization

		[Use environment variables to customize](../users/oidc-auth.md#oidc-login-customization)
		[Use environment variables to customize](../users/oidc-auth/index.md#oidc-login-customization)
		the text and icon on the OIDC button on the Sign In page.

		## Support Links
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -148,7 +148,7 @@ integrations with Git providers, such as GitHub, GitLab, and Bitbucket.
		External authentication can also be used to integrate with external services
		like JFrog Artifactory and others.

		Please refer to the [external authentication](../external-auth.md) section for
		Please refer to the [external authentication](../external-auth/index.md) section for
		more information.

		## Up Next
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -32,7 +32,7 @@ come bundled with your Coder deployment.
		}
		```

		- [Authentication Providers](https://coder.com/docs/admin/external-auth):
		- [Authentication Providers](../../external-auth/index.md):

		- Use icons for external authentication providers to make them recognizable.
		You can set an icon for each provider by setting the
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -15,7 +15,7 @@ approach for "Open in Coder" flows.

		### 1. Set up git authentication

		See [External Authentication](../external-auth.md) to set upgit authentication
		See [External Authentication](../external-auth/index.md) to set upGit authentication
		in your Coder deployment.

		### 2. Modify your template to auto-clone repos
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -304,7 +304,7 @@ Visit the Coder UI to confirm these changes:

		```env
		# Depending on your identity provider configuration, you may need to explicitly request a "roles" scope
		CODER_OIDC_SCOPES=openid,profile,email,roles
		CODER_OIDC_SCOPES=openid,profile,email,offline_access,roles

		# The following fields are required for role sync:
		CODER_OIDC_USER_ROLE_FIELD=roles
Expand DownExpand Up		@@ -517,7 +517,7 @@ Steps to troubleshoot.

		## Provider-Specific Guides

		Below are some details specific to individual OIDC providers.
		<div class="tabs">

		### Active Directory Federation Services (ADFS)

Expand DownExpand Up		@@ -579,6 +579,8 @@ Below are some details specific to individual OIDC providers.

		### Keycloak

		<!-- copied in refresh-tokens.md. make changes there too. -->

		The `access_type` parameter has two possible values: `online` and `offline`.
		By default, the value is set to `offline`.

Expand All		@@ -598,6 +600,8 @@ refresh tokens for offline access to the user's resources.

		### Google

		<!-- copied in refresh-tokens.md. make changes there too. -->

		To ensure Coder receives a refresh token when users authenticate with Google
		directly, set the `prompt` to `consent` in the auth URL parameters. Without
		this, users will be logged out after 1 hour.
Expand All		@@ -607,3 +611,5 @@ In your Coder configuration:
		```shell
		CODER_OIDC_AUTH_URL_PARAMS='{"access_type": "offline", "prompt": "consent"}'
		```

		</div>
Original file line number	Diff line number	Diff line change
Expand Up		@@ -7,7 +7,7 @@ enforces MFA correctly.

		##Configuring SSO

		-[OpenID Connect](./oidc-auth.md) (e.g. Okta, KeyCloak, PingFederate, Azure AD)
		-[OpenID Connect](./oidc-auth/index.md) (e.g. Okta, KeyCloak, PingFederate, Azure AD)
		-[GitHub](./github-auth.md) (or GitHub Enterprise)

		##Groups
Expand Down