Developer Resources

Refresh the Token

If a refresh token was requested along with the access token, then the refresh token can be used to request a new access token without having to ask the user to re-authenticate. If the refresh token is still valid, then a new access token and refresh token will be returned to the client.

If the refresh token has been invalidated for any reason, then the client must require the user to re-authenticate to retrieve a new access token. The reasons for refresh tokens becoming invalid are:

  • Refresh token has expired;

  • Refresh token has been administratively revoked (separation / security reasons);

  • User has explicitly revoked the refresh token

To refresh a token, the access token must have been requested with a grant type that supports refresh tokens (authorization code or resource owner password credentials). A request will then be made to the token endpoint with the grant_type parameter set to "refresh_token".

A new access token can be requested with a scope of equal or lesser value than the original access token request. Refreshing an access token with additional scopes will return an error. If the scope parameter is omitted, then access token will be valid for the original request scope.

Sample Client Configuration

For the refresh token example below, the client configuration for the authorization code grant type from above will be used to refresh the token:

Admin Label OAuth2 Parameter Example Value

Scope Settings

scope

edit

Client ID

client_id

ac_client

Client Authentication

client_secret

2Federate

Allowed Grant Types

response_type grant_type

  • response_type of "code" (code)

  • grant_type of "authorization_code" (code)

  • grant_type of "refresh_token" (refresh)

Refreshing the Token

The following request is made by the client:

POST https://localhost:9031/as/token.oauth2 HTTP/1.1

Content-Type: application/x-www-form-urlencoded

Authorization: Basic YWNfY2xpZW50OjJGZWRlcmF0ZQ==

grant_type=refresh_token&refresh_token=123...789
A token can only be refreshed with the same or a lesser scope than the original token issued. If the token is being refreshed with the same scope as the original request, the scope parameter can be omitted. If a greater scope is required, the client must re-authenticate the user.

A successful response to this message will result in a 200 OK HTTP response and the following JSON structure in the body of the response:

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

{
  "access_token":"aaa...ccc",
  "token_type":"Bearer",
  "expires_in":14400,
  "refresh_token":"456...321"
}
Depending on the PingFederate configuration, the client could be configured to roll the refresh token returned from a refresh token request. i.e. a new refresh token is returned and the original refresh token is invalidated.