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.

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

2. Verify provider-specific token configuration:

3. Verify users can stay logged in beyond the identity provider's access token expiration period (typically 1 hour).

4. 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.