Description
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_SCOPESenvironment variable
Problem Description
-
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_accessscope requirement. -
Impact:
- Users experience hourly logouts due to access token expiry (Okta default: 1 hour)
- No refresh tokens are stored in the database when
offline_accessscope is missing - Requires all users to re-authenticate after configuration changes
-
Provider Behavior:
- Okta: Requires
offline_accessscope (Okta Docs) - Google: Uses
access_type=offlineURL parameter (different approach) - Auth0: Uses
offline_accessscope - OIDC Spec: Standardizes on
offline_accessscope
- Okta: Requires
Steps to Reproduce
- Deploy Coder v2.23.0+ with Okta OIDC
- Configure
CODER_OIDC_SCOPESwithoutoffline_access - Login and wait for access token expiry (typically 1 hour)
- 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:
CODER_OIDC_SCOPES="openid,profile,email,offline_access"Proposed Solutions
1. Documentation Updates (Priority: High)
- Update Okta configuration docs to include
offline_accessscope requirement - Cross-reference with IDP Sync documentation
- 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_accessscope is missing for known providers
3. Default Configuration (Priority: Low - Breaking Change Risk)
- NOT RECOMMENDED: Adding
offline_accessto defaultCODER_OIDC_SCOPEScould break existing deployments - Some providers may reject unknown scopes
Code References
- Token refresh logic:
coderd/httpmw/oauth2.go - Related issue: #9580
Priority
High - Affects user experience significantly for Okta deployments and potentially other enterprise OIDC providers.