In my previous blog post , I provided basic steps for getting started with OAuth  using WSO2 Identity Server. In this post, I’m explaining how to use OAuth refresh tokens for renewing the access tokens issued by the Identity Server.
For getting started, follow my previous blog post and get the Service Provider configuration registered with the OAuth application for obtaining the client ID and client secret values. Make sure in the OAuth configuration, you select the checkbox ‘Refresh Token.
According to OAuth 2.0 specification, the “Authorization Code” grant type and “Resource Owner Password Credentials” grant type should optionally provide a refresh token in the OAuth access token response.
Following my previous blog post, try out either the Authorization Code or Resource Owner Password Credentials grant type and obtain the OAuth access token response. You should receive a JSON response as following.
Now that we have the access token, we can invoke the User Information Endpoint and get the default user claims as following.
curl -k -X POST -H "Authorization: Bearer <access_token_value>" https://localhost:9443/oauth2/userinfo?schema=openid
Once the access token is expired, if you try out the same above request, you would get the following
"error_description":"Access token validation failed",
However, for trying out renewing the access token, we don’t need to wait until the token is expired. You can make the following request to the token endpoint of Identity Server. (Here, the Authorization header value given as XXX is the base64 encoded value of client_id:client_secret). For the refresh_token parameter, we need to provide the value received in the token response we received previously. Here I am not sending the scope parameter because I am requesting the new access token with the same scopes it was issued previously. However, if we need to obtain the new access token with a subset of scopes which the previous token was authorized for, then we need to include the scope as a parameter with the required scopes.
curl -k -X POST -H "Authorization: Basic XXX" -H “Content-Type: application/x-www-form-urlencoded” --data "grant_type=refresh_token&refresh_token=XXXX" https://localhost:9443/oauth2/token
As the response to the above request, we would receive the same OAuth 2.0 access token response which includes a new access token and a new refresh token.
When you renew an access token, Identity Server will automatically set the previously issued access token to be inactive (not usable) regardless of its expiry. This happens only if the token scope is same for the new token as well. If the token scope is different (a subset), then Identity Server will not mark the previous token as inactive, instead of that it will issue a new token where both the old and new tokens would be valid until their expiry.
These OAuth access tokens are stored in the IDN_OAUTH2_ACCESS_TOKEN table in the database.
The validity periods of the OAuth access tokens and refresh tokens are defined in the IS_HOME/repository/conf/identity/identity.xml file. Following are the properties which are useful for you.
<!-- Default validity period for application access tokens in seconds -->
<!-- Default validity period for user access tokens in seconds -->
<!-- Validity period for refresh token -->
Platform Security Team