In this tutorial, you will learn about the various OAuth token lifecycle operations. Specifically, you will learn how to obtain a new access token from a refresh token, revoke tokens, and obtain token details using OAuth introspection.
What is OAuth token lifecycle management?
Web / Mobile application (third-party OAuth applications) that provide access to third-party API services (ie login with your Google credentials) make it easy to share your resources with them. The OAuth provider (ie Google) will store the ‘permission’ granted to the third-party OAuth application so they don’t need to re-ask your permissions again. It will allow you to login to the Web / Mobile application (ie using your google credentials) without being prompted again to perform the OAuth handshake.
Each OAuth token has a validity date and can expire. For mobile applications, they often provide long-lived sessions so you don’t need to login to the application everytime you open it. For these use cases, a refresh token provides a convenient way to obtain a new access token for an expired access token without performing the OAuth handshake again. In other circumstances, you may want to remove your previous consented permissions (ie login with Google) or you may have lost your mobile device and want to remove the permissions to avoid unauthorized access. In these situations, you can revoke your permissions granted to an OAuth application to prevent it from accessing your resources.
These capabilities are critical to providing a first-class digital experience because things can go wrong but the user experience does not have to suffer along the way. In this article, you will learn about the various OAuth token lifecycle capability and how to build them into your application.
Prerequisites
Important:
- If your unfamiliar with running the API Connect Developer toolkit, you can follow the instructions here.
- OAuth revocation is not supported in API Connect deployed on public Bluemix.
Instructions:
The imported API definitions contain pre-configured OAuth configuration. You will use the Postman collection to run requests and learn about the various OAuth token lifecycle operations.
If you want to learn about OAuth configuration, see
hereLet’s first get an access token using the OAuth resource owner grant type. Change the hostname/port number in the Postman requests if they are different in your environment.
- Using the Postman collection, open the OAuth Password request and click Send.
{
"token_type": "bearer",
"access_token": "<sanitized>",
"expires_in": 3600,
"scope": "weather",
"refresh_token": "<sanitized>"
}
- Use the OAuth Token List request to obtain a list of tokens from an OAuth application (
client_id=default). Click Send to view the list of tokens. It will return the previously obtained access token.
[
{
"clientId": "default",
"clientName": "default",
"owner": "cn=spoon,email=spoon@poon.com",
"scope": "weather",
"issuedAt": 1495268682,
"expiredAt": 1497950682,
"refreshTokenIssued": true
}
]
- Use the OAuth App Revocation request to remove all access tokens issued to an OAuth application (
client_id=default). Click Send to revoke all access tokens for the application default.
{
"status": "success"
}
- Invoke the OAuth Token List request now. You won’t get any tokens returned since the tokens are revoked.
[]
- Use the OAuth Refresh Token request to obtain a new access token when an access token is expired without going through the OAuth handshake again. If you still have the OAuth Password response open, copy the refresh token onto your clipboard, otherwise submit the OAuth Password request again to obtain a new access token and copy the refresh token to your clipboard.
- Open the OAuth Refresh Token request and paste the refresh token in your clipboard into the existing
refresh_token field within the Body. This will return both a new access token and refresh token.
{
"token_type": "bearer",
"access_token": "<sanitized>",
"expires_in": 3600,
"scope": "weather",
"refresh_token": "<sanitized>"
}
- In the same OAuth Refresh Token request, click Send again to try and get a new access token from the refresh token. You will get an error because the old refresh token is invalidated when a new access token is returned from a refresh token.
{
"error": "invalid_grant"
}
- The OAuth Introspection request validates the access token and returns the details of the access token. Use the OAuth Password request again to obtain a new access token. In the OAuth Introspection request, copy the access token into the
token field within the Body. Click Send to obtain the details:
{
"active": true,
"token_type": "bearer",
"client_id": "default",
"username": "cn=spoon,email=spoon@poon.com",
"sub": "cn=spoon,email=spoon@poon.com",
"exp": 1495273141,
"expstr": "2017-05-20T09:39:01Z",
"iat": 1495269541,
"nbf": 1495269541,
"nbfstr": "2017-05-20T08:39:01Z",
"scope": "weather",
"miscinfo": "[r:gateway]",
"client_name": "default"
}
- Optionally, revoke the token using the OAuth App Revocation request and then issue the OAuth Introspection call again, you will get an error because the token is not valid.
{
"active": false
}
In this tutorial, you learned about the lifecycle of OAuth tokens. Specifically, you obtained a new access token from a refresh token, revoked an application access token(s), retrieved the list of tokens for an application and obtained the details of an individual access token.
Special thanks to
Shiu-Fun Poon for help in putting together these examples.
#APIDevelopers#ProductCapabilities#oauth