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] (http://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens).

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.