Access tokens are credentials used to access protected resources. Typically, an access token is a string representing an authorization issued to the client. The string is usually opaque to the client.
The OAuth 2.0 specification does not mandate any particular implementation for access tokens but it mentions two possible strategies.
- The access token is an identifier that is hard to guess. For example, a randomly generated string of sufficient length, that the server handling the protected resource can use to lookup the associated authorization information.
- The access token self-contains the authorization information in a manner that can be verified. For example, by encoding authorization information along with a signature into the token.
So by default, a UUID is issued as an access token in WSO2 Identity Server, which is of the first type above. But, it also can be configured to issue a self-contained access token, which is of the second type above.
Why do we need self-contained access tokens?
When short string identifiers are used as access tokens, a network request to the Authorization server is required to retrieve the authorization information associated with each access token. But with self-contained access tokens there is no need for a network call to retrieve the authorization information, as it’s self-contained. Thus, access token processing may be significantly quicker and more efficient. However, when it comes to token revocation self-contained access tokens lag, whereas access tokens with string identifiers can be revoked with almost immediate effect. The common practice is to have a short expiration time with self-contained access tokens, but that may result in more refresh token requests at the Authorization server.
Configuring WSO2 Identity Server to issue self-contained access tokens
The WSO2 Identity Server can be configured to issue self-contained access tokens that represent a signed JSON Web Token (JWT) with the following format.
<base64 encoded header>.<base64 encoded payload>.<signature>
eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvbG9jYWxob3N0Ojk0NDNcL29hdXRoMlwvdG9rZW4iLCJhdWQiOlsiZGQ5VTNRRndORjJQUWZ2bEh6VGNTU3VOQzJ3YSJdLCJleHAiOjE1MTA4MTg5ODYsImlhdCI6MTUxMDgxNTM4NiwiYXpwIjoiZGQ5VTNRRndORjJQUWZ2bEh6VGNTU3VOQzJ3YSIsImp0aSI6ImU4NTM4ODM3LWM3NTctNDZlZC04M2YyLWRmYjU0YTliNDA5MCJ9.bi8N3Giqlk2Oo6bLQweZmMq0Slsst5kwIGJfaqzs5yDOj4OYShZ4yMqt3YAoCYJAT71lcTvRv6ykEQ6AORveG0K_OjWx4VsYnvgY_xwtUQpudxGJ-aEgJocbTvc5zbZ2a71LfWtH1aN_OcjbA6RH4RdKCMyZTR5lFfy5wxDzHLXusM2PMiVVJcXxNzJf3WNdPoKA3ntsMlZk1KjPzbApoPa_BkbU3_Bh9MJthQkvOa-aNJe6h4EDSi483EVahV4o6afSUbIDaWDdOzdeBPF7YO1NNsAioLzRbR75isScX28z1hyKaNwa3RJICjgQmsMCtmPyFER4WNdsLF8FOPsCuw
The payload of the token will include following JWT claims:
| Claim Name | Type | Claim Value |
|---|---|---|
| iss | string | The issuer of the JWT. The 'Identity Provider Entity Id' value of the OAuth2/OpenID Connect Inbound Authentication configuration of the Resident Identity Provider is returned here. |
| aud | string array | The token audience list. The client identifier of the OAuth clients that the JWT is intended for, is sent herewith. |
| azp | string | The autorized party for which the token is issued to. The client identifier of the OAuth client that the token is issued for, is sent herewith. |
| iat | integer | The token issue time. |
| exp | integer | The token expiration time. |
| jti | string | Unique identifier for the JWT token. |
In addition, for a user authorized, user claims can be obtained over this JWT as per OpenID Connect claim configurations, by configuring requested user claims in the OAuth service provider.
WSO2 Identity Server needs to be configured to issue above explained self-contained JWT access tokens as below.
Open the
<IS_HOME>/repository/conf/identity/identity.xmlfile and uncomment the following entry under<OAuth>element.<IdentityOAuthTokenGenerator>org.wso2.carbon.identity.oauth2.token.JWTTokenIssuer</IdentityOAuthTokenGenerator>
- Restart the server.
- Configure an OAuth service provider.
Initiate an access token request to the WSO2 Identity Server, over a known grant type. For example, the following cURL command illustrates the syntax of an access token request that can be initiated over the Resource Owner Password Credential grant type.
Requestcurl -u <client id>:<client secret> -k -d "grant_type=password&username=<username>&password=<password>" -H "Content-Type:application/x-www-form-urlencoded" https://localhost:9443/oauth2/token
In response, the self-contained JWT access token will be returned as shown below.
Response{"access_token":"eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImF1ZCI6WyJkZDlVM1FGd05GMlBRZnZsSHpUY1NTdU5DMndhIl0sImF6cCI6ImRkOVUzUUZ3TkYyUFFmdmxIelRjU1N1TkMyd2EiLCJpc3MiOiJodHRwczpcL1wvbG9jYWxob3N0Ojk0NDNcL29hdXRoMlwvdG9rZW4iLCJleHAiOjE1MTA4MjQ5MzUsImlhdCI6MTUxMDgyMTMzNSwianRpIjoiNDA1YjRkNGUtODUwMS00ZTFhLWExMzgtZWQ4NDU1Y2QxZDQ3In0.FCk3Wo8DnFEHb02JCd9BWAHQ48BBt3n2YLQV6TpLMpFvTRNCZJAA-aEH4LrE7oVejvGd7YWGDy2Vzb7x-Bpg7yMYxozUerCkMy_F4Iw_xctgEJ3WF_TTJFhISGNoWl-FXspM5d9EQvMvk0JxAovhE0HfXv5GCosGy-0oT7ShQrwZLBIwE9d0ceUcmly42dvDZSsqHDIz-PjrFzvpXwbZqq_sRFnh6MHlmmug7t1UCs85caoLhfSweaT0z7ED8P2Tsg_HgmnaaeDapszG6LckeBglqYwbRHy6X6LAcJfAkkwAlqrU0Vu4azsuE8BsLPKMYzu9ZeCoHdLHYdtz-I0yKQ","refresh_token":"5974cdcc-865e-3144-82c5-4f147ddcb519","token_type":"Bearer","expires_in":589}