How it works...

Imagine if every time an access token became invalid because of expiration time, the user will have to go through all the process of authenticating against the Authorization Server and granting all the permissions again. Besides the fact of the user experience being compromised, the user might not be present at a specific time. Once the user has granted permission for third-party applications to access resources on its behalf, this third-party application can use the resources even if the user is not logged in. Take a look at the following image that describes a fictitious scenario to better understand how an application can access a user's resources when the user is not present:

As you can see in the preceding image, when the consumer starts processing the payment order against the OAuth 2 Provider, which might be a payment provider by itself, the user is not present at all. The consumer would not be able to ask the user to authenticate and authorize the issue of a new access token. Furthermore, all the processing is happening on the server side.

Given the need for refresh tokens, Spring Security OAuth2 allows you to configure this feature by defining one more authorized grant types as a refresh_token, as follows:

.authorizedGrantTypes("authorization_code", "password", "refresh_token")

And to help you to start testing the refresh token usage, we have also defined a pretty short expiration time for the access token of 120 seconds (2 minutes), as follows:

.accessTokenValiditySeconds(120)

Make sure the application is running and let's start by requesting an access token. You can use the Authorization Code flow, but here I am using the Password grant type for practical reasons. So to retrieve an access token, we can send the following request to the Authorization Server:

curl -X POST --user clientapp:123456 http://localhost:8080/oauth/token -H "accept: application/json" -H "content-type: application/x-www-form-urlencoded" -d "grant_type=password&username=adolfo&password=123&scope=read_profile"

The result now must have one more field which is the refresh_token, and is as shown here:

{
  "access_token":"91541ac7-8d63-4106-9660-c1847fd4b37e",
  "token_type":"bearer",
  "refresh_token":"985436a9-85cc-45ce-90d4-66a840a1a5dd",
  "expires_in":119,
  "scope":"read_profile"
}

Try to access the user's profile using the issued access token to see if everything is working fine and wait for 2 minutes to try a new request. Send the following request after 2 minutes:

curl -X GET http://localhost:8080/api/profile -H "authorization: Bearer 91541ac7-8d63-4106-9660-c1847fd4b37e"

The result should be as follows:

{
  "error":"invalid_token",
  "error_description":"Access token expired: 91541ac7-8d63-4106-9660-c1847fd4b37e"
}

Now it's time to request for a new access token using the previously issued refresh token. Send the following request using the command line:

curl -X POST --user clientapp:123456 http://localhost:8080/oauth/token -H "content-type: application/x-www-form-urlencoded" -d "grant_type=refresh_token&refresh_token=985436a9-85cc-45ce-90d4-66a840a1a5dd&scope=read_profile"

The result must be a brand new access token that can be used to keep accessing the user's resources (which in this case is the user's profile).