Summary

Starting with Coder v2.23.0, OIDC providers (particularly Okta) require theoffline_access scope to be explicitly included inCODER_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 newoffline_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 whenoffline_access scope is missing
   • Requires all users to re-authenticate after configuration changes

3. Provider Behavior:

   • Okta: Requiresoffline_access scope (Okta Docs)
   • Google: Usesaccess_type=offline URL parameter (different approach)
   • Auth0: Usesoffline_access scope
   • OIDC Spec: Standardizes onoffline_access scope

Steps to Reproduce

1. Deploy Coder v2.23.0+ with Okta OIDC
2. ConfigureCODER_OIDC_SCOPES withoutoffline_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

Addoffline_access toCODER_OIDC_SCOPES:

CODER_OIDC_SCOPES="openid,profile,email,offline_access"

Proposed Solutions

1. Documentation Updates (Priority: High)

• UpdateOkta configuration docs to includeoffline_access scope requirement
• Cross-reference withIDP 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 whenoffline_access scope is missing for known providers

3. Default Configuration (Priority: Low - Breaking Change Risk)

• NOT RECOMMENDED: Addingoffline_access to defaultCODER_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.