opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add more specific steps and information about oidc refresh tokens (#18336)

Browse Source 
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>
This commit is contained in:
Edward Angert
2025-06-16 13:18:55 -04:00
committed by GitHub
co-authored by EdwardAngert
parent 095007766b
commit 5c16079aff
19 changed files with 362 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin/external-auth.md → docs/admin/external-auth/index.md
+5 -5
View File
@@ -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)
docs/admin/infrastructure/architecture.md
+4 -4
View File
@@ -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)
docs/admin/integrations/jfrog-artifactory.md
+2 -2
View File
@@ -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
docs/admin/integrations/vault.md
+1 -1
View File
@@ -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.
docs/admin/setup/appearance.md
+1 -1
View File
@@ -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
docs/admin/setup/index.md
+1 -1
View File
@@ -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
docs/admin/templates/extending-templates/icons.md
+1 -1
View File
@@ -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
docs/admin/templates/open-in-coder.md
+1 -1
View File
@@ -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
docs/admin/users/idp-sync.md
+6 -31
View File
@@ -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
## 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)
docs/admin/users/index.md
+1 -1
View File
@@ -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
docs/admin/users/oidc-auth.md → docs/admin/users/oidc-auth/index.md
+40 -6
View File
@@ -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)
docs/admin/users/oidc-auth/refresh-tokens.md
+198
View File
@@ -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.
<div class="tabs">
<!-- markdownlint-disable MD001 -->
### 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).
</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 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.