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)
   • 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:

CODER_OIDC_SCOPES="openid,profile,email,offline_access"

Proposed Solutions

1. Documentation Updates (Priority: High)

• Update Okta configuration docs to include offline_access scope 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_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
• Related issue: #9580

Priority

High - Affects user experience significantly for Okta deployments and potentially other enterprise OIDC providers.