From 5c16079affa5eae4387e8a55986584a4a07558b6 Mon Sep 17 00:00:00 2001 From: Edward Angert Date: Mon, 16 Jun 2025 13:18:55 -0400 Subject: [PATCH] docs: add more specific steps and information about oidc refresh tokens (#18336) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit closes https://github.com/coder/coder/issues/18307 relates to https://github.com/coder/coder/pull/18318 preview: - [refresh-tokens](https://coder.com/docs/@18307-refresh-tokens/admin/users/oidc-auth/refresh-tokens) - [configuring-okta](https://coder.com/docs/@18307-refresh-tokens/tutorials/configuring-okta) ~(not sure why @Emyrk 's photo is so huge there though)~ ✔️ - [x] removed from [idp-sync](https://coder.com/docs/@18307-refresh-tokens/admin/users/idp-sync) to do: - move keycloak - add ping federate and azure - edit text (possibly placeholders for now - I want to see how it all relates and edit it again. right now, there's a note about the same thing in every section in way that's not super helpful/necessary) - ~convert some paragraphs to OL~ calling this out of scope for now --------- Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> --- docs/README.md | 2 +- .../index.md} | 10 +- docs/admin/infrastructure/architecture.md | 8 +- docs/admin/integrations/jfrog-artifactory.md | 4 +- docs/admin/integrations/vault.md | 2 +- docs/admin/setup/appearance.md | 2 +- docs/admin/setup/index.md | 2 +- .../templates/extending-templates/icons.md | 2 +- docs/admin/templates/open-in-coder.md | 2 +- docs/admin/users/idp-sync.md | 37 +--- docs/admin/users/index.md | 2 +- .../{oidc-auth.md => oidc-auth/index.md} | 46 +++- docs/admin/users/oidc-auth/refresh-tokens.md | 198 ++++++++++++++++++ docs/ai-coder/best-practices.md | 2 +- docs/manifest.json | 11 +- .../best-practices/security-best-practices.md | 2 +- docs/tutorials/cloning-git-repositories.md | 6 +- docs/tutorials/configuring-okta.md | 137 +++++++----- docs/tutorials/template-from-scratch.md | 4 +- 19 files changed, 362 insertions(+), 117 deletions(-) rename docs/admin/{external-auth.md => external-auth/index.md} (96%) rename docs/admin/users/{oidc-auth.md => oidc-auth/index.md} (73%) create mode 100644 docs/admin/users/oidc-auth/refresh-tokens.md diff --git a/docs/README.md b/docs/README.md index b5a07021d3..4848a8a153 100644 --- 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 b/docs/admin/external-auth/index.md similarity index 96% rename from docs/admin/external-auth.md rename to docs/admin/external-auth/index.md index 0540a5fa92..5d3ade987e 100644 --- a/docs/admin/external-auth.md +++ b/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 @@ -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 index dbac881bdd..079d69699a 100644 --- 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 index 13b1880940..702bce2599 100644 --- 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 index 74229bd6d8..012932a557 100644 --- 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 index cc0097ddea..38c85a5439 100644 --- 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 index 1a34920e73..f72ca5b2f8 100644 --- 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 index f7e5064199..2b4e2f92ec 100644 --- 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 index 216b062232..a15838c739 100644 --- 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 index 47ee36bad6..b59431c5f0 100644 --- 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. +
### 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 +## Next Steps -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. - -### 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 b7d98b9197..e86d40a5a1 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 1647286554..dd674d2160 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 0000000000..53a1147882 --- /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 b9243dc3d2..124cc7c221 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 7866f2a993..2aa9cb0ead 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 c6f6cbe13a..2c9ffbbb11 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 f67b8a97ca..b166ef8dd1 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 349c1321b0..01cfacfb34 100644 --- a/docs/tutorials/configuring-okta.md +++ b/docs/tutorials/configuring-okta.md @@ -6,7 +6,7 @@ Steven Masley
-December 13, 2023 +Updated: June, 2025 --- @@ -15,7 +15,7 @@ Sign On (SSO) on Coder. To configure custom claims in Okta to support syncing roles and groups with Coder, you must first have setup an Okta application with -[OIDC working with Coder](../admin/users/oidc-auth.md). +[OIDC working with Coder](../admin/users/oidc-auth/index.md). From here, we will add additional claims for Coder to use for syncing groups and roles. @@ -28,38 +28,39 @@ If the Coder roles & Coder groups can be inferred from Okta has a simple way to send over the groups as a `claim` in the `id_token` payload. -In Okta, go to the application “Sign On” settings page. +In Okta, go to the application **Sign On** settings page. -Applications > Select Application > General > Sign On +**Applications** > **Select Application** > **General** > **Sign On** -In the “OpenID Connect ID Token” section, turn on “Groups Claim Type” and set -the “Claim name” to `groups`. Optionally configure a filter for which groups to -be sent. +In the **OpenID Connect ID Token** section, turn on **Groups Claim Type** and set +the **Claim name** to `groups`. +Optionally, configure a filter for which groups to be sent. > [!IMPORTANT] -> If the user does not belong to any groups, the claim will not be sent. Make -> sure the user authenticating for testing is in at least one group. Defer to -> [troubleshooting](../admin/users/index.md) with issues. +> If the user does not belong to any groups, the claim will not be sent. +> Make sure the user authenticating for testing is in at least one group. ![Okta OpenID Connect ID Token](../images/guides/okta/oidc_id_token.png) -Configure Coder to use these claims for group sync. These claims are present in -the `id_token`. See all configuration options for group sync in the -[docs](https://coder.com/docs/admin/auth#group-sync-enterprise). +Configure Coder to use these claims for group sync. +These claims are present in the `id_token`. +For more group sync configuration options, consult the [IDP sync documentation](../admin/users/idp-sync.md#group-sync). ```bash -# Add the 'groups' scope. -CODER_OIDC_SCOPES=openid,profile,email,groups +# Add the 'groups' scope and include the 'offline_access' scope for refresh tokens +CODER_OIDC_SCOPES=openid,profile,email,offline_access,groups # This name needs to match the "Claim name" in the configuration above. CODER_OIDC_GROUP_FIELD=groups ``` +> [!NOTE] +> The `offline_access` scope is required in Coder v2.23.0+ to prevent hourly session timeouts. + These groups can also be used to configure role syncing based on group -membership. +membership: ```bash -# Requires the "groups" scope -CODER_OIDC_SCOPES=openid,profile,email,groups +CODER_OIDC_SCOPES=openid,profile,email,offline_access,groups # This name needs to match the "Claim name" in the configuration above. CODER_OIDC_USER_ROLE_FIELD=groups # Example configuration to map a group to some roles @@ -69,32 +70,32 @@ CODER_OIDC_USER_ROLE_MAPPING='{"admin-group":["template-admin","user-admin"]}' ## (Easy) Mapping Okta profile attributes If roles or groups cannot be completely inferred from Okta group memberships, -another option is to source them from a user’s attributes. The user attribute -list can be found in “Directory > Profile Editor > User (default)”. +another option is to source them from a user's attributes. +The user attribute list can be found in **Directory** > **Profile Editor** > **User (default)**. -Coder can query an Okta profile for the application from the `/userinfo` OIDC -endpoint. To pass attributes to Coder, create the attribute in your application, +Coder can query an Okta profile for the application from the `/userinfo` OIDC endpoint. +To pass attributes to Coder, create the attribute in your application, then add a mapping from the Okta profile to the application. -“Directory > Profile Editor > {Your Application} > Add Attribute” +**Directory** > **Profile Editor** > {Your Application} > **Add Attribute** -Create the attribute for the roles, groups, or both. **Make sure the attribute -is of type `string array`.** +Create the attribute for the roles, groups, or both. Make sure the attribute +is of type `string array`: ![Okta Add Attribute view](../images/guides/okta/add_attribute.png) -On the “Okta User to {Your Application}” tab, map a `roles` or `groups` -attribute you have configured to the application. +On the **Okta User to {Your Application}** tab, map a `roles` or `groups` +attribute you have configured to the application: ![Okta Add Claim view](../images/guides/okta/add_claim.png) -Configure using these new attributes in Coder. +Configure using these new attributes in Coder: ```bash # This must be set to false. Coder uses this endpoint to grab the attributes. CODER_OIDC_IGNORE_USERINFO=false -# No custom scopes are required. -CODER_OIDC_SCOPES=openid,profile,email +# Include offline_access for refresh tokens +CODER_OIDC_SCOPES=openid,profile,email,offline_access # Configure the group/role field using the attribute name in the application. CODER_OIDC_USER_ROLE_FIELD=approles # See our docs for mapping okta roles to coder roles. @@ -104,56 +105,86 @@ CODER_OIDC_USER_ROLE_MAPPING='{"admin-group":["template-admin","user-admin"]}' # CODER_OIDC_GROUP_FIELD=... ``` +> [!NOTE] +> The `offline_access` scope is required in Coder v2.23.0+ to prevent hourly session timeouts. + ## (Advanced) Custom scopes to retrieve custom claims Okta does not support setting custom scopes and claims in the default -authorization server used by your application. If you require this -functionality, you must create (or modify) an authorization server. +authorization server used by your application. +If you require this functionality, you must create (or modify) an authorization server. -To see your custom authorization servers go to “Security > API”. Note the -`default` authorization server **is not the authorization server your app is -using.** You can configure this default authorization server, or create a new -one specifically for your application. +To see your custom authorization servers go to **Security** > **API**. +Note the `default` authorization server is not the authorization server your app is using. +You can configure this default authorization server, or create a new one specifically for your application. -Authorization servers also give more refined controls over things such as -token/session lifetimes. +Authorization servers also give more refined controls over things such as token/session lifetimes. ![Okta API view](../images/guides/okta/api_view.png) -To get custom claims working, we should map them to a custom scope. Click the -authorization server you wish to use (likely just using the default). +To get custom claims working, map them to a custom scope. +Click the authorization server you wish to use (likely just using the default). -Go to “Scopes”, and “Add Scope”. Feel free to create one for roles, groups, or -both. +Go to **Scopes**, and **Add Scope**. +Feel free to create one for roles, groups, or both: ![Okta Add Scope view](../images/guides/okta/add_scope.png) -Now create the claim to go with the said scope. Go to “Claims”, then “Add -Claim”. Make sure to select **ID Token** for the token type. The **Value** -expression is up to you based on where you are sourcing the role information. -Lastly, configure it to only be a claim with the requested scope. This is so if -other applications exist, we do not send them information they do not care -about. +Create the claim to go with the said scope. +Go to **Claims**, then **Add Claim**. +Make sure to select **ID Token** for the token type. +The **Value** expression is up to you based on where you are sourcing the role information. +Configure it to only be a claim with the requested scope. +This is so if other applications exist, we do not send them information they do not care about: ![Okta Add Claim with Roles view](../images/guides/okta/add_claim_with_roles.png) -Now we have a custom scope + claim configured under an authorization server, we -need to configure coder to use this. +Now we have a custom scope and claim configured under an authorization server. +Configure Coder to use this: ```bash # Grab this value from the Authorization Server > Settings > Issuer # DO NOT USE the application issuer URL. Make sure to use the newly configured # authorization server. CODER_OIDC_ISSUER_URL=https://dev-12222860.okta.com/oauth2/default -# Add the new scope you just configured -CODER_OIDC_SCOPES=openid,profile,email,roles +# Add the new scope you just configured and offline_access for refresh tokens +CODER_OIDC_SCOPES=openid,profile,email,roles,offline_access # Use the claim you just configured CODER_OIDC_USER_ROLE_FIELD=roles # See our docs for mapping okta roles to coder roles. CODER_OIDC_USER_ROLE_MAPPING='{"admin-group":["template-admin","user-admin"]}' ``` -You can use the “Token Preview” page to verify it has been correctly configured +> [!NOTE] +> The `offline_access` scope is required in Coder v2.23.0+ to prevent hourly session timeouts. + +You can use the "Token Preview" page to verify it has been correctly configured and verify the `roles` is in the payload. ![Okta Token Preview](../images/guides/okta/token_preview.png) + +## Troubleshooting + +### Users Are Logged Out Every Hour + +**Symptoms**: Users experience session timeouts approximately every hour and must re-authenticate +**Cause**: Missing `offline_access` scope in `CODER_OIDC_SCOPES` +**Solution**: + +1. Add `offline_access` to your `CODER_OIDC_SCOPES` configuration +1. Restart your Coder deployment +1. All existing users must logout and login once to receive refresh tokens + +### Refresh Tokens Not Working After Configuration Change + +**Symptoms**: Hourly timeouts, even after adding `offline_access` +**Cause**: Existing user sessions don't have refresh tokens stored +**Solution**: Users must logout and login again to get refresh tokens stored in the database + +### Verify Refresh Token Configuration + +To confirm that refresh tokens are working correctly: + +1. Check that `offline_access` is included in your `CODER_OIDC_SCOPES` +1. Verify users can stay logged in beyond Okta's access token lifetime (typically one hour) +1. Monitor Coder logs for any OIDC refresh errors during token renewal diff --git a/docs/tutorials/template-from-scratch.md b/docs/tutorials/template-from-scratch.md index 33e02dabda..22c4c53920 100644 --- a/docs/tutorials/template-from-scratch.md +++ b/docs/tutorials/template-from-scratch.md @@ -171,7 +171,7 @@ resource "coder_agent" "main" { Because Docker is running locally in the Coder server, there is no need to authenticate `coder_agent`. But if your `coder_agent` is running on a remote host, your template will need -[authentication credentials](../admin/external-auth.md). +[authentication credentials](../admin/external-auth/index.md). This template's agent also runs a startup script, sets environment variables, and provides metadata. @@ -181,7 +181,7 @@ and provides metadata. - Installs [code-server](https://coder.com/docs/code-server), a browser-based [VS Code](https://code.visualstudio.com/) app that runs in the workspace. - We'll give users access to code-server through `coder_app`, later. + We'll give users access to code-server through `coder_app` later. - [`env` block](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#env)