## Summary Starting with Coder v2.23.0, OIDC providers (particularly Okta) require the `offline_access` scope to be explicitly included in `CODER_OIDC_SCOPES` to receive refresh tokens. Without this scope, users experience frequent session timeouts (typically every hour) as sessions expire when access tokens expire, with no refresh capability. ## Environment - **Coder Version**: 2.23.0+ - **Affected OIDC Providers**: Okta (confirmed), potentially others - **Configuration**: `CODER_OIDC_SCOPES` environment variable ## Problem Description 1. **Root Cause**: Changes in v2.23.0 aligned token refresh behavior with access/refresh token expiry, but documentation and default configurations weren't updated to reflect the new `offline_access` scope requirement. 2. **Impact**: - Users experience hourly logouts due to access token expiry (Okta default: 1 hour) - No refresh tokens are stored in the database when `offline_access` scope is missing - Requires all users to re-authenticate after configuration changes 3. **Provider Behavior**: - **Okta**: Requires `offline_access` scope ([Okta Docs](https://developer.okta.com/docs/guides/refresh-tokens/main/#get-a-refresh-token)) - **Google**: Uses `access_type=offline` URL parameter (different approach) - **Auth0**: Uses `offline_access` scope - **OIDC Spec**: Standardizes on `offline_access` scope ## Steps to Reproduce 1. Deploy Coder v2.23.0+ with Okta OIDC 2. Configure `CODER_OIDC_SCOPES` without `offline_access` 3. Login and wait for access token expiry (typically 1 hour) 4. Observe forced logout without refresh capability ## Expected Behavior - Users should remain logged in beyond access token expiry through refresh token mechanism - Clear documentation should exist for OIDC scope requirements - Configuration should be transparent about refresh token implications ## Current Workaround Add `offline_access` to `CODER_OIDC_SCOPES`: ```bash CODER_OIDC_SCOPES="openid,profile,email,offline_access" ``` ## Proposed Solutions ### 1. Documentation Updates (Priority: High) - Update [Okta configuration docs](https://coder.com/docs/tutorials/configuring-okta) to include `offline_access` scope requirement - Cross-reference with [IDP Sync documentation](https://coder.com/docs/admin/users/idp-sync#keycloak) - Add release notes explaining the v2.23.0 changes and scope requirements - Document provider-specific refresh token requirements ### 2. Runtime Detection (Priority: Medium) - Add warning/banner in UI when refresh tokens aren't being received - Log warnings when `offline_access` scope is missing for known providers ### 3. Default Configuration (Priority: Low - Breaking Change Risk) - **NOT RECOMMENDED**: Adding `offline_access` to default `CODER_OIDC_SCOPES` could break existing deployments - Some providers may reject unknown scopes ## Code References - Token refresh logic: [`coderd/httpmw/oauth2.go`](https://github.com/coder/coder/blob/83a694beacd238cd4016add13d8c3350800e1370/coderd/httpmw/oauth2.go#L45-L48) - Related issue: [#9580](https://github.com/coder/coder/issues/9580) ## Priority **High** - Affects user experience significantly for Okta deployments and potentially other enterprise OIDC providers.