OIDC Refresh Token Implementation#

The OIDC provider's refresh token flow is intentionally minimal: it delegates entirely to the standard golang.org/x/oauth2 library to exchange the stored refresh token for new tokens, adding no provider-specific parameters. This contrasts with providers like Google and Azure, which construct manual HTTP POST requests with explicit client_id, client_secret, and grant_type fields.

Entry Point#

RefreshSession is the public interface method (satisfying Provider.RefreshSession). It guards against nil or empty-RefreshToken sessions, then delegates to the unexported redeemRefreshToken.

Core Redemption: redeemRefreshToken#

redeemRefreshToken does the following:

1. Builds an oauth2.Config using only ClientID, ClientSecret, and the RedeemURL token endpoint — no scopes, redirect URL, or extra parameters are added 1.

2. Constructs a pre-expired oauth2.Token with the session's RefreshToken set and Expiry forced into the past (time.Now().Add(-time.Hour)). This ensures the oauth2 library's TokenSource always treats the token as expired and performs a refresh 2.

3. Calls c.TokenSource(ctx, t).Token() — the standard oauth2 library handles the token endpoint request, including encoding grant_type=refresh_token and client credentials 3.

4. Creates a new session via createSession(ctx, token, true), passing refresh=true to signal that a missing ID token is acceptable 4.

5. Selectively updates the existing session — claim fields (IDToken, Email, User, Groups, PreferredUsername) are only overwritten when a new ID token is present; AccessToken, RefreshToken, CreatedAt, ExpiresOn, and Refreshed are always updated 5.

Why the ID Token is Optional on Refresh#

Per OIDC Core §12, the ID token is optional in a refresh token response. The code explicitly handles this case at createSession: if ErrMissingIDToken occurs and refresh=true, it proceeds without one. Consequently, the existing session's identity claims are preserved 6.

The ValidateSession method also accounts for this: when s.Refreshed is true, it skips ID token verification and instead optionally validates the access token against the ValidateURL 7.

Comparison with Other Providers#

Providers built on top of OIDCProvider (CIDAAS, KeycloakOIDC, ADFS) reuse this implementation rather than reimplementing refresh logic.

Key Files#