mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +08: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
co-authored by
EdwardAngert
EdwardAngert
parent
095007766b
commit
5c16079aff
@@ -0,0 +1,167 @@
|
||||
# OpenID Connect
|
||||
|
||||
The following steps through how to integrate any OpenID Connect provider (Okta,
|
||||
Active Directory, etc.) to Coder.
|
||||
|
||||
## Step 1: Set Redirect URI with your OIDC provider
|
||||
|
||||
Your OIDC provider will ask you for the following parameter:
|
||||
|
||||
- **Redirect URI**: Set to `https://coder.domain.com/api/v2/users/oidc/callback`
|
||||
|
||||
## Step 2: Configure Coder with the OpenID Connect credentials
|
||||
|
||||
Set the following environment variables on your Coder deployment and restart Coder:
|
||||
|
||||
```env
|
||||
CODER_OIDC_ISSUER_URL="https://issuer.corp.com"
|
||||
CODER_OIDC_EMAIL_DOMAIN="your-domain-1,your-domain-2"
|
||||
CODER_OIDC_CLIENT_ID="533...des"
|
||||
CODER_OIDC_CLIENT_SECRET="G0CSP...7qSM"
|
||||
```
|
||||
|
||||
## OIDC Claims
|
||||
|
||||
When a user logs in for the first time via OIDC, Coder will merge both the
|
||||
claims from the ID token and the claims obtained from hitting the upstream
|
||||
provider's `userinfo` endpoint, and use the resulting data as a basis for
|
||||
creating a new user or looking up an existing user.
|
||||
|
||||
To troubleshoot claims, set `CODER_VERBOSE=true` and follow the logs while
|
||||
signing in via OIDC as a new user. Coder will log the claim fields returned by
|
||||
the upstream identity provider in a message containing the string
|
||||
`got oidc claims`, as well as the user info returned.
|
||||
|
||||
> [!NOTE]
|
||||
> If you need to ensure that Coder only uses information from the ID
|
||||
> token and does not hit the UserInfo endpoint, you can set the configuration
|
||||
> option `CODER_OIDC_IGNORE_USERINFO=true`.
|
||||
|
||||
### Email Addresses
|
||||
|
||||
By default, Coder will look for the OIDC claim named `email` and use that value
|
||||
for the newly created user's email address.
|
||||
|
||||
If your upstream identity provider users a different claim, you can set
|
||||
`CODER_OIDC_EMAIL_FIELD` to the desired claim.
|
||||
|
||||
> [!NOTE]
|
||||
> If this field is not present, Coder will attempt to use the claim
|
||||
> field configured for `username` as an email address. If this field is not a
|
||||
> valid email address, OIDC logins will fail.
|
||||
|
||||
### Email Address Verification
|
||||
|
||||
Coder requires all OIDC email addresses to be verified by default. If the
|
||||
`email_verified` claim is present in the token response from the identity
|
||||
provider, Coder will validate that its value is `true`. If needed, you can
|
||||
disable this behavior with the following setting:
|
||||
|
||||
```env
|
||||
CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> This will cause Coder to implicitly treat all OIDC emails as
|
||||
> "verified", regardless of what the upstream identity provider says.
|
||||
|
||||
### Usernames
|
||||
|
||||
When a new user logs in via OIDC, Coder will by default use the value of the
|
||||
claim field named `preferred_username` as the the username.
|
||||
|
||||
If your upstream identity provider uses a different claim, you can set
|
||||
`CODER_OIDC_USERNAME_FIELD` to the desired claim.
|
||||
|
||||
> [!NOTE]
|
||||
> If this claim is empty, the email address will be stripped of the
|
||||
> domain, and become the username (e.g. `example@coder.com` becomes `example`).
|
||||
> To avoid conflicts, Coder may also append a random word to the resulting
|
||||
> username.
|
||||
|
||||
## OIDC Login Customization
|
||||
|
||||
If you'd like to change the OpenID Connect button text and/or icon, you can
|
||||
configure them like so:
|
||||
|
||||
```env
|
||||
CODER_OIDC_SIGN_IN_TEXT="Sign in with Gitea"
|
||||
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.
|
||||
|
||||
## 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
|
||||
|
||||
To remove email and password login, set the following environment variable on
|
||||
your Coder deployment:
|
||||
|
||||
```env
|
||||
CODER_DISABLE_PASSWORD_AUTH=true
|
||||
```
|
||||
|
||||
## SCIM
|
||||
|
||||
> [!NOTE]
|
||||
> SCIM is a Premium feature.
|
||||
> [Learn more](https://coder.com/pricing#compare-plans).
|
||||
|
||||
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
|
||||
it the Coder server.
|
||||
|
||||
```env
|
||||
CODER_SCIM_AUTH_HEADER="your-api-key"
|
||||
```
|
||||
|
||||
## TLS
|
||||
|
||||
If your OpenID Connect provider requires client TLS certificates for
|
||||
authentication, you can configure them like so:
|
||||
|
||||
```env
|
||||
CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
|
||||
CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
|
||||
```
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Group Sync](../idp-sync.md)
|
||||
- [Groups & Roles](../groups-roles.md)
|
||||
- [Configure OIDC Refresh Tokens](./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.
|
||||
|
||||
<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.
|
||||
Reference in New Issue
Block a user