Access Tokens and Refresh Tokens

Access Tokens and Refresh Tokens

The access_token that mod_auth_openidc receives from the OP will be used by the module itself against the user_info endpoint of the OP (if configured) to resolve extra claims about the user. Besides that an application may be interested in the access_token to use it against other OAuth 2.0 protected APIs, typically when additional scopes have been requested in addition to the OpenID Connect scopes (using OIDCScope).

For that purpose mod_auth_openidc passes the access_token that it receives from the OP to applications in a header named OIDC_access_token. If there's a hint from the OP about the access_token's expiry time (expires_in) then an additional header named OIDC_access_token_expires will be set with an absolute Unix timestamp that indicates when the access_token expires.

If a refresh_token is returned by the OP, the module stores the refresh_token in the user session. When the application wants to refresh the access_token, it may call the module on the following hook:

<redirect_uri>?refresh=<return_to>&access_token=<access_token>

When called on this hook mod_auth_openidc will refresh the access_token using the stored refresh_token as described in the OpenID Connect specification in section 12. Using Refresh Tokens.

The redirect_uri URL value corresponds to the value set in the OIDCRedirectUri configuration primitive. The return_to value of the refresh parameter is the URL that the module will redirect the browser to after refreshing the access_token. The old/current access_token needs to be passed in the access_token parameter for XSRF protection.

When the access_token is successfully refreshed, the OIDC_access_token and OIDC_access_token_expires headers will have been set with the new values obtained from the OP. When refreshing the access_token fails, a parameter named error_code will be passed back to the return_to URL as in:

<return_to>?error_code=<value>

The following error_code values have been defined:

error_code value                Description

no_access_token                 no access_token parameter was passed
no_access_token_exists          no access_token exists in the session
no_access_token_match           the access_token provided did not match the one stored in the session
no_refresh_token_exists         no refresh_token exists in the session
session_corruption              the session is corrupt, i.e internal error
refresh_failed                  refreshing the access_token with the provider failed

When an error_code parameter is returned to the return_to URL it means that the access_token has not been refreshed and the caller should take appropriate action, i.e. it can no longer assume that the old access_token is valid.

Access Token Revocation and Cache Invalidation

(since 2.0.1rc2) If an access token has been revoked (somewhere else) on the Authorization Server, the Resource Server may still have it in its cache as a valid token. You can invalidate the cache entry for the access token by calling:

<redirect_uri>?remove_at_cache=<access_token>

so that on the next call the token needs to be introspected and that action will fail because the token is not valid anymore.