### 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 index b7d98b919734c..e86d40a5a1b1f 100644 --- 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 b/docs/admin/users/oidc-auth/index.md similarity index 73% rename from docs/admin/users/oidc-auth.md rename to docs/admin/users/oidc-auth/index.md index 1647286554ecf..dd674d21606f5 100644 --- a/docs/admin/users/oidc-auth.md +++ b/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) diff --git a/docs/admin/users/oidc-auth/refresh-tokens.md b/docs/admin/users/oidc-auth/refresh-tokens.md new file mode 100644 index 0000000000000..53a114788240e --- /dev/null +++ b/docs/admin/users/oidc-auth/refresh-tokens.md @@ -0,0 +1,198 @@ +# 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. + +

+ + + +### 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). + +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). + +

+ +## 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: + +

+ + ### 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}`. + +

+ +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 required refresh token configuration: + - `offline_access` scope for most providers + - `"access_type": "offline"` for Google +- Provider not correctly configured to issue refresh tokens. +- User has not logged in since refresh token configuration was added. + +**Solution**: + +- For most providers, add `offline_access` to your `CODER_OIDC_SCOPES` configuration. + - `"access_type": "offline"` for Google +- 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. + +### 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. + +Users might get logged out again before the new configuration takes effect completely. diff --git a/docs/ai-coder/best-practices.md b/docs/ai-coder/best-practices.md index b9243dc3d2943..124cc7c221ee8 100644 --- a/docs/ai-coder/best-practices.md +++ b/docs/ai-coder/best-practices.md @@ -33,7 +33,7 @@ for development. With AI Agents, this is no exception. 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 index 7866f2a993aed..2aa9cb0ead9ce 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -402,7 +402,14 @@ { "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", @@ -646,7 +653,7 @@ { "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 index c6f6cbe13a5c8..2c9ffbbb111c8 100644 --- a/docs/tutorials/best-practices/security-best-practices.md +++ b/docs/tutorials/best-practices/security-best-practices.md @@ -25,7 +25,7 @@ credentials are stolen. ### 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 index f67b8a97ca64f..b166ef8dd1552 100644 --- a/docs/tutorials/cloning-git-repositories.md +++ b/docs/tutorials/cloning-git-repositories.md @@ -20,9 +20,9 @@ authorization. This can be achieved by using the Git provider, such as GitHub, 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 diff --git a/docs/tutorials/configuring-okta.md b/docs/tutorials/configuring-okta.md index 349c1321b0693..01cfacfb34c80 100644 --- a/docs/tutorials/configuring-okta.md +++ b/docs/tutorials/configuring-okta.md @@ -6,7 +6,7 @@ Steven Masley

Release v0.32.0

What's Changed

New Contributors

v2.12.1

What's Changed

v2.4.0

What's Changed

New Contributors

Changelog

46.0.5 - (2025-04-09)

⚙️ Miscellaneous Tasks

⬆️ Upgrades

46.0.4 - (2025-04-03)

🐛 Bug Fixes

📚 Documentation

⬆️ Upgrades

46.0.3 - (2025-03-23)

🔄 Update

📚 Documentation

v3.29.0

CodeQL Action Changelog

3.29.0 - 11 Jun 2025

CodeQL Action Changelog

[UNRELEASED]

3.29.0 - 11 Jun 2025

3.28.19 - 03 Jun 2025

3.28.18 - 16 May 2025

3.28.17 - 02 May 2025

3.28.16 - 23 Apr 2025

3.28.15 - 07 Apr 2025

3.28.14 - 07 Apr 2025

3.28.13 - 24 Mar 2025

3.28.12 - 19 Mar 2025

Release v1.3.5

v2.12.1

What's Changed

v2.4.0

What's Changed

New Contributors

v2.6.2

What's Changed

Changelog

46.0.5 - (2025-04-09)

⚙️ Miscellaneous Tasks

⬆️ Upgrades

46.0.4 - (2025-04-03)

🐛 Bug Fixes

📚 Documentation

⬆️ Upgrades

46.0.3 - (2025-03-23)

🔄 Update

📚 Documentation

v3.29.0

CodeQL Action Changelog

3.29.0 - 11 Jun 2025

CodeQL Action Changelog

[UNRELEASED]

3.29.0 - 11 Jun 2025

3.28.19 - 03 Jun 2025

3.28.18 - 16 May 2025

3.28.17 - 02 May 2025

3.28.16 - 23 Apr 2025

3.28.15 - 07 Apr 2025

3.28.14 - 07 Apr 2025

3.28.13 - 24 Mar 2025

3.28.12 - 19 Mar 2025

Release v1.3.5