🧬 Introduction

The Refresh Token Grant provides a way for client applications to obtain a new Access Token without requiring the user to re-authenticate. This can help improve the user experience by avoiding unnecessary login prompts and reducing the load on the Authorization Server by reducing the frequency of authentication requests. Refresh Tokens typically have a longer lifetime than Access Tokens, and the user or the Authorization Server can revoke them at any time.

〰️ Refresh Token Grant Flow

First, you have to generate a Refresh Token with Authorization Code Flow or Password Grant. Then, you can use the Access Token you have generated with either of the flows until it expires. When the Access Token is expired, you can send the Refresh Token to the Authorization Server, and ask for a fresh Access Token.

🧪 Testing Client Refresh Token Grant Flow with WSO2 IS

First, we need to create a Service Provider(SP) in the WSO2 IS. To create a new SP we can use the DCR we have discussed in a previous article.

curl -k -X POST -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d '{"client_name": "playground_2","grant_types": ["authorization_code","refresh_token"], "redirect_uris": ["http://localhost:8080/playground2/oauth2client"],"ext_param_client_id":"provided_client_id0001","ext_param_client_secret":"provided_client_secret0001" }' "https://localhost:9443/api/identity/oauth2/dcr/v1.1/register"

Next, download the Apache Tomcat binary zip file and extract it to a location where you can access it easily on your machine. After that, download the playground2 sample application from WSO2 IS sample releases.

Then put the playground2.war file in the <TOMCAT_HOME>/webapps directory and open a terminal in the <TOMCAT_HOME>/bin directory. Then, run the following commands to extract the playground2.war file.

• If permissions are not set

  ↳ chmod +x catalina.sh

• Start the Tomcat server

  ↳ ./catalina.sh start

After starting the Tomcat server, you will notice there is a directory created in <TOMCAT_HOME>/webapps named playground2. Stop the Tomcat server by typing ./catalina.sh stop and go to <TOMCAT_HOME>/webapps/playground2/WEB-INF/classes and open playground2.properties file. Then provide the Client ID and Client Secret for the playground2 app(When we created the Service Provider(SP) using DCR we gave provided_client_id0001 as the Client ID and provided_client_secret0001 as the Client Secret). After that, start the Tomcat server again by typing ./catalina.sh start in the terminal.

If you want to see the logs of the Tomcat server, open another terminal tab and go to <TOMCAT_HOME>/logs and type, tail -1000f catalina.out

Since our SP is configured properly, we can use the Authorization Code Grant Flow to get an Authorization Code first. Type, the following URL in the browser and press enter to get the Authorization Code.

• URL format

  ↳ https://<IS_HOST>:<IS_PORT>/oauth2/authorize?response_type=code&client_id=<CLIENT_ID>&scope=<SCOPES>&redirect_uri=<REDIRECT_URI>

• URL example

  ↳ https://localhost:9443/oauth2/authorize?response_type=code&client_id=provided_client_id0001&scope=openid&redirect_uri=http://localhost:8080/playground2/oauth2client

After getting the Authorization Code, run the following cURL command to get the Refresh Token along with an Access Token.

• cURL format

  ↳ curl -v -X POST --basic -u <CLIENT-ID>:<CLIENT_SECRET> -H "Content-Type:application/x-www-form-urlencoded;charset=UTF-8" -k -d "grant_type=authorization_code&code=<AUTHORIZATION_CODE>&redirect_uri=<REDIRECT_URI>" https://localhost:9443/oauth2/token

• cURL example

  ↳ curl -v -X POST --basic -u provided_client_id0001:provided_client_secret0001 -H "Content-Type:application/x-www-form-urlencoded;charset=UTF-8" -k -d "grant_type=authorization_code&code=954a2f49-5f0a-33b5-b0c4-d9f4ff0a2c45&redirect_uri=http://localhost:8080/playground2/oauth2client" https://localhost:9443/oauth2/token

After getting the Refresh Token, you can request a new Access Token by executing the following cURL command.

• cURL format

  ↳ curl -k -d "grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>" -H "Authorization: Basic Base64Encoded(<CLIENT_ID>:<CLIENT_SECRET>)" -H "Content-Type: application/x-www-form-urlencoded" <TOKEN_ENDPONT>

• cURL example

  ↳ curl -k -d "grant_type=refresh_token&refresh_token=a2742e57-50a2-3618-b2ef-f68e7754313c" -H "Authorization: Basic cHJvdmlkZWRfY2xpZW50X2lkMDAwMTpwcm92aWRlZF9jbGllbnRfc2VjcmV0MDAwMQ==" -H "Content-Type: application/x-www-form-urlencoded" https://localhost:9443/oauth2/token

Since you are getting the initial Access Token with an ID Token you can access the /oauth2/userinfo endpoint to get user-info. Also, you can use the ID Token to get user claim values as well.

So this is it about the Refresh Token Grant. In the next article, we will look at how you can use the JWT Bearer Grant with WSO2 IS.

📚 References

• https://is.docs.wso2.com/en/latest/references/grant-types/#refresh-token-grant