mirror of
https://github.com/coder/coder.git
synced 2025-07-12 00:14:10 +00:00
docs: add more specific steps and information about oidc refresh tokens (#18336)
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
GitHub
@ -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**
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
|
||||
|
||||
1. Adjust the GitHub app permissions. You can use more or fewer permissions than
|
||||
are listed here, this example allows users to clone
|
||||
repositories:
|
||||
|
||||
|
||||
|
||||
|
||||
| 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.
|
||||
|
||||
|
||||
|
||||
|
||||
## Multiple External Providers (Premium)
|
||||
|
||||
@ -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)
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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)
|
||||
198
docs/admin/users/oidc-auth/refresh-tokens.md
Normal file
198
docs/admin/users/oidc-auth/refresh-tokens.md
Normal 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.
|
||||
@ -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
|
||||
|
||||
@ -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"
|
||||
},
|
||||
{
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -6,7 +6,7 @@
|
||||
<span style="vertical-align:middle;">Steven Masley</span>
|
||||
</a>
|
||||
</div>
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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`:
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
@ -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)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user