The administrator/developer can perform the following to manage the tokens:
The access token has shorter lifetime. The refresh tokens have longer life time. Hence, to use access token for a longer duration you can use the refresh token. When the original access token is expired or going to expire, you can send a request with the refresh token to get a fresh access token. The refresh token is useful in a scenario where an application does not require frequent usage of authentication from user.
Identity Server issues refresh token for authorization code grant and resource owner grant.
NOTE:You can request for refresh token if the administrator has enabled the use of refresh token and if you have registered the application with token type as refresh token. For more information about registering the application, see Section 2.2, Registering the OAuth Client Application.
The refresh token request should be sent to the Token Endpoint. The client application makes an HTTPS POST request to the /token endpoint for getting a fresh access token by using the refresh token.
curl --request POST \ --url https://<idphost:port>/nidp/oauth/nam/token \ --header 'content-type: application/x-www-form-urlencoded' \ --data 'grant_type=refresh_token&client_id=4e4ae330-1215-4fc8-9aa7-79df8325451c&client_secret=Rxl5pvgL80DBzbIcLPVnH17FehZA8L&refresh_token=eyJraWQiOiI0MjgzNzQyNDYxMjE5OTM1.....'
|
Request Parameter |
Description |
|---|---|
|
grant_type |
Value should be "refresh_token'" |
|
client_id |
Client ID of the registered client |
|
client_secret |
Client Secret of the registered client. It is optional for native application, for web application secret is mandatory. |
|
refresh_token |
refresh_token that is obtained during authorization code, resource owner credentials flow |
For information about other request parameters, see Section 4.4, Token Endpoint.
{"access_token": "eyJraWQiOiI0MjgzNzQyNDYxMjE5OTM1ODU5OTYyODYwNzYyODAzMzEyNjI1MjUzMDQyMTk0NDMiLCJ0.....","token_type" : "bearer","expires_in" : 3599, "scope" : "profile email"}
|
Response Parameter |
Description |
|---|---|
|
token_type |
The type of the token. Authorization server currently supports only Bearer type |
|
access_token |
Fresh access token that can be used to invoke resource server APIs |
|
refresh_token |
Optionally re-issues a refresh token if configured in client application |
|
expires_in |
The remaining lifetime of the access token. |
|
scope |
The granted scopes to the client. |
NOTE:If validation errors are occurred, HTTP Status 400 returned with the JSON response contains "error" and "error_description".
Prerequisite: Inform the Access Manager administrator to enable token revocation in the OAuth global settings of Identity Server.
The client application can revoke the refresh token in the following scenarios:
The end-user logs out
The application is uninstalled
To notify the Identity Server that a previously obtained refresh token is no longer required.
The refresh token received in earlier flows can be revoked by sending an HTTPS Post request to the revocation endpoint, /revoke of Identity Server.
NOTE:Only the refresh tokens that are in JWT format can be revoked. Therefore, You can revoke only the refresh tokens that are issued from Access Manager 4.4 or later versions.
curl --request POST \ --url https://<idphost:port>/nidp/oauth/nam/revoke\ --header 'content-type: application/x-www-form-urlencoded' \ --data 'client_id=bb775b12-bbd4-423b-83d9-647aeb98608d&client_secret=bBbE-4mNO_kWWAnEeOL1CLTyuPhNLhHkTThArEckyr&token=eyJraWQiOiI0MjgzNzQyNDYxMjE5OTM1ODU5OTYyOD'
|
Request Parameter |
Description |
|---|---|
|
client_id |
Client ID of the registered client |
|
client_secret |
Client Secret of the registered client. It is optional for native application, for web application secret is mandatory. |
|
token |
refresh_token that is obtained during authorization grant, resource owner credentials flow |
The Identity Server responds with HTTP status code 200 OK if the token has been revoked successfully or if the client submitted an invalid token.
The error code unsupported_token_type is returned by the Identity Server when the given token is not a refresh token.
If the Identity Server responds with HTTP status code 503, the client must assume the token still exists and may retry revoking the refresh token after a reasonable delay.
You can ask the Access Manager administrator to revoke refresh tokens that are issued to a device. This feature is helpful in following scenarios:
If the device is stolen or user lost the device
Token is given to user for multiple devices and one device is compromised.
User revokes by revoking the consent.
When consent is removed, user is required to grant permission again to use the token.
The token can be manually associated with a device by providing additional parameter "device_id" while requesting for access token. Such manually associated tokens can be revoked using the revocation endpoint.
The client application makes HTTPS POST request to /revoke endpoint with device_id as path parameter.
curl --request POST \ --url https://<idphost:port>/nidp/oauth/nam/revoke/<device_id>\ --header 'content-type: application/x-www-form-urlencoded' \ --data 'userstore_name=namsignboxuserstore&user_dn=cn%3Dharry%2Co%3Dnovell'
|
Parameter |
Required |
Description |
|---|---|---|
|
userstore_name |
Yes |
Specify the name of the user store |
|
user_dn |
Yes |
Specify the user's dn to whom the token issued. |
HTTP/1.1 200 OKCache-Control: no-cache, no-store, no-transformContent-Length: 0Date: Tue, 03 Mar 2015 18:12:55 GMT{"status": "Successfully revoked token(s) issued to this device."}
NOTE:If validation errors are occurred, HTTP Status 4xx returned with the JSON response contains "error" and "error_description".
The tokens are validated based on the configuration of the resource server that is managed through Access Manager Administration Console. To validate access tokens, you require to understand the encryption method used for encrypting the access tokens.
By default token encryption is done by using Access Manager keys. To encrypt access token using resource server keys share the encryption keys details in JWKS format (JSON Web Key Set) or JWKS URI to Access Manager Administrator for creating custom resource server using either REST API or Administration Console.
Refresh tokens are always encrypted by using Access Manager Encryption keys.
To validate access tokens and refresh token that are signed and encrypted by using Access Manager encrypted keys, send a request to TokenIntrospect endpoint, /introspect.
The request should contain the token in the Authorization header as follows:
Authorization: Bearer access_token
curl --request POST \ --url https://<idphost:port>/nidp/oauth/v1/nam/introspect \ --header 'content-type: application/x-www-form-urlencoded;Authorization: Bearer eyJraWQiOiI0MjgzNzQyNDYxMjE5OTM1ODU5OTYyODYwNzYyODAzMzEyNjI1MjUzMDQyMTk0NDMiLCJ0.... \' --data 'token=eyJhbGciOiJBMT........._.xvpQmbtb-hzR6TAs3dOm7A
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 296
Date: Thu, 19 Mar 2015 15:47:25 GMT
{
"active": true,"exp": 1536731362,"nbf": 1536727762,"iat": 1536727762,"scope": [],"token_type": "bearer","jti": "9b7d2252-cb1d-4e41-9155-97fe2f3dc85a","iss": "https://<Identity Server hostname>/nidp/oauth/nam","aud": "21ae0625-f319-4b24-bf52-b2fc7e2a866a","client_id": "21ae0625-f319-4b24-bf52-b2fc7e2a866a"
}
|
Parameter |
Description |
|---|---|
|
active |
A boolean value indicating whether the mentioned token in the introspection request is currently active. |
|
client_id |
The client identifier for the OAuth 2.0 client that requested this token. |
|
exp |
The timestamp in seconds indicating when the token will expire. |
NOTE:If validation errors are occurred, HTTP Status 400 returned with the JSON response contains "error" and "error_description".
When the access token is encrypted using the resource server keys, the resource server can validate the token without contacting Access Manager's token verification endpoint.
A resource server can validate using the following sample code written in JAVA:
//Step1: decrypt the JWT Token (JWE Standard)
String jwtAccessToken =
"eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4R0NNIiwidHlwIjoiSldUIiwia2lkIjoibmFtLTEifQ.ZjE0jRb5oh3suQZHFmaB-m....";
JsonWebEncryption jwe = new JsonWebEncryption();
jwe.setCompactSerialization(jwtAccessToken);
JsonWebKeySet jsonWebKeySet = new JsonWebKeySet(jwks);
List<JsonWebKey> jsonWebKeys = jsonWebKeySet.getJsonWebKeys();
JsonWebKey jsonWebkey = jsonWebKeys.stream().filter( p ->p.getKeyId().equalsIgnoreCase(jwe.getKeyIdHeaderValue())).findFirst().orElse(jsonWebKeys.get(0));
if(jsonWebkey instanceof RsaJsonWebKey){RsaJsonWebKey rsa = (RsaJsonWebKey) jsonWebkey;
jwe.setKey(rsa.getPrivateKey());
}
else
{
jwe.setKey(jsonWebkey.getKey());
}String decryptedToken = jwe.getPlaintextString();
//Step 2: Verify the JWT Signature (JWS Standard)JsonWebKeySet jsonWebKeySet = new JsonWebKeySet(jwks);JsonWebKey jsonWebkey = jsonWebKeySet.getJsonWebKeys().get(0);JsonWebSignature jws = new JsonWebSignature();
jws.setKey(jsonWebkey.getKey());
jws.setCompactSerialization(decryptedToken);
if(true == jws.verifySignature()){System.out.println("Signature is valid.");String payload = jws.getPayload();
//}
For detailed sample code and tool for validating the JWT access token, refer JWT Validation tool and Readme under Additional Resources of Access Manager documentation page.
When the token is not encrypted, the resource server can validate the token signature. In the Java code, you can use the step 2 of the sample that is mentioned in the preceding section.