This documentation is for WSO2 Identity Server 5.5.0 . View documentation for the latest release.

All docs This doc
Skip to end of metadata
Go to start of metadata

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.

  1. 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.
  2. 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.

Therefore, by default, a UUID is issued as an access token in WSO2 Identity Server, which is of the first type above. However, 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.

Access token hashing in WSO2 IS

From WSO2 IS 5.5.0 onwards, access tokens are hashed and stored in the ACCESS_TOKEN_HASH column of the IDN_OAUTH2_ACCESS_TOKEN table by default. This is particularly useful if the value of your JWT is too long and exceeds the size of the ACCESS_TOKEN column. 

  • For default access tokens (that are not JWTs), the plain access token is hashed using the SHA-256 algorithm and the hashed access token value is then stored in the ACCESS_TOKEN_HASH column. In this case, the ACCESS_TOKEN column stores the plain access token.  
  • For JWT self contained access tokens, the JTI value of the JWT is hashed using the SHA-256 algorithm and the hashed access token value is then stored in the ACCESS_TOKEN_HASH column. In this case, the ACCESS_TOKEN column stores the JTI value. 

Enable OAuth token encryption

Tip: You can also set up OAuth access token encryption to store an encrypted value in the access token columns. 

 Click here for more information

OAuth2 token encryption protects OAuth2 access tokens, refresh tokens, consumer secrets, and authorization codes. To enable OAuth token encryption, configure the  TokenPersistenceProcessor as shown below in the <IS_HOME>/repository/conf/identity/identity.xml file:


Once you configure the TokenPersistenceProcessor in the identity.xml file, and restart WSO2 Identity Server, RSA encryption with RSA/ECB/OAEPwithSHA1andMGF1Padding cipher transformation will be enabled by default.


WSO2 Identity Server hashes access tokens,refresh tokens, authorization codes, and client secrets. By default it uses SHA-256 algorithm for hashing. To use a different hashing algorithm, enable the following configuration within the <OAuth> root tag in the <IS_HOME>/repository/conf/identity/identity.xml file and configure it accordingly.


WSO2 Identity Server supports hashing algorithms supported by MessageDigest. For more information about supported hashing algorithms, see MessageDigest Algorithms.

WSO2 IS also supports storing the whole JWT in the ACCESS_TOKEN column instead of the JTI value, for backward compatibility purposes. To do this, uncomment the following configuration block in the <IS_HOME>/repository/conf/identity.xml file and ensure that the <PersistAccessTokenAlias> property is set to false. 


Configuring WSO2 Identity Server to issue self-contained access tokens

WSO2 Identity Server needs to be configured to issue above explained self-contained JWT access tokens as below.

  1. Open the <IS_HOME>/repository/conf/identity/identity.xml file and uncomment the following entry under <OAuth> element.

  2. Restart the server.
  3. Configure an OAuth service provider.
  4. 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.

    cURL command
    curl -u <CLIENT_ID>:<CLIENT_SECRET> -k -d "grant_type=password&username=<USERNAME>&password=<PASSWORD>" -H "Content-Type:application/x-www-form-urlencoded" https://<IS_HOST>:<IS_HTTPS_PORT>/oauth2/token
    • Navigate to your service provider, expand Inbound Authenitcaion Configurations and expand OAuth/OpenID Connect Configuration.
      • Copy the OAuth Client Key as the value for <CLIENT_ID>.
      • Copy the OAuth Client Secret as the value for <CLIENT_SECRET>.
    • Enter the username and password of the user you want to get the token as the value for <USERNAME> and <PASSWORD> respectively.
    • By default, <IS_HOST> is localhost. However, if you are using a public IP, the respective IP address or domain needs to be specified.
    • By default, <IS_HTTPS_PORT> has been set to 9443. However, if the port offset has been incremented by n, the default port value needs to be incremented by n.


    curl -u liXJsel4bJ76arbg3DXC3rU4w60a:wQEYq83njU29ZFbpQWdZsUlXcnga -k -d "grant_type=password&username=testuser2&password=testuser2 -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.


    The access token you receive is a signed JSON Web Token (JWT). Use a JWT decoder to decode the access token and you are able to see the payload of the token that includes the following JWT claims:

    Claim NameTypeClaim Value
    issstringThe 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.
    audstring arrayThe token audience list. The client identifier of the OAuth clients that the JWT is intended for, is sent herewith.
    azpstringThe 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.
    iatintegerThe token issue time. 
    expintegerThe token expiration time.
    jtistringUnique identifier for the JWT token.

    In addition, a user claims can be obtained by an authorized user over this JWT as per OpenID Connect claim configurations, by configuring requested user claims in the OAuth service provider. After configuring the service provider you can run the cURL command given below by providing the required details.

    curl -u <CLIENT_ID>:<CLIENT_SECRET> -k -d "grant_type=password&username=<USERNAME>&password=<PASSWORD>&scope=openid" -H "Content-Type:application/x-www-form-urlencoded" https://<IS_HOST>:<IS_HTTPS_PORT>/oauth2/token
Where to go next

Now that you understand how to configure WSO2 Identity Server to issue self-contained access tokens, See Handling Custom Claims with the JWT Bearer Grant Type for details on how you can use WSO2 Identity Server to handle custom claims in a self contained access token with the JWT bearer grant type.

  • No labels