coder · EdwardAngert · Jun 16, 2025 · Jun 11, 2025 · Jun 11, 2025 · Jun 12, 2025
diff --git a/docs/README.md b/docs/README.md
@@ -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**
 

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
@@ -65,7 +65,7 @@ Reference the documentation for your chosen provider for more information on how
 
 ### Workspace CLI
 
-Use [`external-auth`](../reference/cli/external-auth.md) in the Coder CLI to access a token within the workspace:
+Use [`external-auth`](../../reference/cli/external-auth.md) in the Coder CLI to access a token within the workspace:
 
 ```shell
 coder external-auth access-token <USER_DEFINED_ID>
@@ -255,7 +255,7 @@ Note that the redirect URI must include the value of `CODER_EXTERNAL_AUTH_0_ID`
 
 ### JFrog Artifactory
 
-Visit the [JFrog Artifactory](../admin/integrations/jfrog-artifactory.md) guide for instructions on how to set up for JFrog Artifactory.
+Visit the [JFrog Artifactory](../../admin/integrations/jfrog-artifactory.md) guide for instructions on how to set up for JFrog Artifactory.
 
 ## Self-managed Git providers
 
@@ -293,13 +293,13 @@ CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"
    - Enable fine-grained access to specific repositories or a subset of
      permissions for security.
 
-   ![Register GitHub App](../images/admin/github-app-register.png)
+   ![Register GitHub App](../../images/admin/github-app-register.png)
 
 1. Adjust the GitHub app permissions. You can use more or fewer permissions than
    are listed here, this example allows users to clone
    repositories:
 
-   ![Adjust GitHub App Permissions](../images/admin/github-app-permissions.png)
+   ![Adjust GitHub App Permissions](../../images/admin/github-app-permissions.png)
 
    | Name          | Permission   | Description                                            |
    |---------------|--------------|--------------------------------------------------------|
@@ -312,7 +312,7 @@ CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"
 1. Install the App for your organization. You may select a subset of
    repositories to grant access to.
 
-   ![Install GitHub App](../images/admin/github-app-install.png)
+   ![Install GitHub App](../../images/admin/github-app-install.png)
 
 ## Multiple External Providers (Premium)
 

diff --git a/docs/admin/infrastructure/architecture.md b/docs/admin/infrastructure/architecture.md
@@ -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)
 

diff --git a/docs/admin/integrations/jfrog-artifactory.md b/docs/admin/integrations/jfrog-artifactory.md
@@ -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:
 
@@ -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

diff --git a/docs/admin/integrations/vault.md b/docs/admin/integrations/vault.md
@@ -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.
 

diff --git a/docs/admin/setup/appearance.md b/docs/admin/setup/appearance.md
@@ -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

diff --git a/docs/admin/setup/index.md b/docs/admin/setup/index.md
@@ -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

diff --git a/docs/admin/templates/extending-templates/icons.md b/docs/admin/templates/extending-templates/icons.md
@@ -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

diff --git a/docs/admin/templates/open-in-coder.md b/docs/admin/templates/open-in-coder.md
@@ -15,7 +15,7 @@ approach for "Open in Coder" flows.
 
 ### 1. Set up git authentication
 
-See [External Authentication](../external-auth.md) to set up git authentication
+See [External Authentication](../external-auth/index.md) to set up Git 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
@@ -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
@@ -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)
 
@@ -577,33 +577,8 @@ Below are some details specific to individual OIDC providers.
      groups claim field.
      Use [this answer from Stack Overflow](https://stackoverflow.com/a/55570286) for an example.
 
-### 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.
-
-To enable the `offline_access` scope which allows for the refresh token
-functionality, you need to add it to the list of requested scopes during the
-authentication flow.
-Including the `offline_access` scope in the requested scopes ensures that the
-user is granted the necessary permissions to obtain refresh tokens.
-
-By combining the `{"access_type":"offline"}` parameter in the OIDC Auth URL with
-the `offline_access` scope, you can achieve the desired behavior of obtaining
-refresh tokens for offline access to the user's resources.
+## Next Steps
 
-### Google
-
-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.
-
-In your Coder configuration:
-
-```shell
-CODER_OIDC_AUTH_URL_PARAMS='{"access_type": "offline", "prompt": "consent"}'
-```
+- [Configure OIDC Refresh Tokens](./oidc-auth/refresh-tokens.md)
+- [Organizations](./organizations.md)
+- [Groups & Roles](./groups-roles.md)
diff --git a/docs/admin/users/index.md b/docs/admin/users/index.md
@@ -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

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
@@ -90,7 +90,40 @@ CODER_OIDC_ICON_URL=https://gitea.io/images/gitea.png
 ```
 
 To change the icon and text above the OpenID Connect button, see application
-name and logo url in [appearance](../setup/appearance.md) settings.
+name and logo url in [appearance](../../setup/appearance.md) settings.
+
+## Configure Refresh Tokens
+
+By default, OIDC access tokens typically expire after a short period.
+This is typically after one hour, but varies by provider.
+
+Without refresh tokens, users will be automatically logged out when their access token expires.
+
+Follow [Configure OIDC Refresh Tokens](./refresh-tokens.md) for provider-specific steps.
+
+The general steps to configure persistent user sessions are:
+
+1. Configure your Coder OIDC settings:
+
+   For most providers, add the `offline_access` scope:
+
+   ```env
+   CODER_OIDC_SCOPES=openid,profile,email,offline_access
+   ```
+
+   For Google, add auth URL parameters (`CODER_OIDC_AUTH_URL_PARAMS`) too:
+
+   ```env
+   CODER_OIDC_SCOPES=openid,profile,email
+   CODER_OIDC_AUTH_URL_PARAMS='{"access_type": "offline", "prompt": "consent"}'
+   ```
+
+1. Configure your identity provider to issue refresh tokens.
+
+1. After configuration, have users log out and back in once to obtain refresh tokens
+
+> [!IMPORTANT]
+> Misconfigured refresh tokens can lead to frequent user authentication prompts.
 
 ## Disable Built-in Authentication
 
@@ -109,8 +142,8 @@ CODER_DISABLE_PASSWORD_AUTH=true
 
 Coder supports user provisioning and deprovisioning via SCIM 2.0 with header
 authentication. Upon deactivation, users are
-[suspended](./index.md#suspend-a-user) and are not deleted.
-[Configure](../setup/index.md) your SCIM application with an auth key and supply
+[suspended](../index.md#suspend-a-user) and are not deleted.
+[Configure](../../setup/index.md) your SCIM application with an auth key and supply
 it the Coder server.
 
 ```env
@@ -127,7 +160,8 @@ CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
 CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
 ```
 
-### Next steps
+## Next steps
 
-- [Group Sync](./idp-sync.md)
-- [Groups & Roles](./groups-roles.md)
+- [Group Sync](../idp-sync.md)
+- [Groups & Roles](../groups-roles.md)
+- [Configure OIDC Refresh Tokens](./refresh-tokens.md)