Self Contained Access Tokens with WSO2 Identity Server

Hasintha Indrajee
3 min readNov 24, 2016

OAuth is an open standard for authorization, commonly used as a way for Internet users to authorize websites or applications to access their information on other websites but without giving them the passwords. WSO2 identity server provides the ability to use multiple protocols which built on top of oauth. Ex — openid connect.

An access token is an opaque string that identifies a user, app, or Page and can be used by the app to make graph API calls. When you call an API, it will validate the access token and allow appropriate access. This validation is done using either token introspection or calling some other endpoint (may be soap) to validate the token. Also if you need to get user attributes from this token you need to do the same endpoint call.

Why do we need self contained access token ?

When we use self contained access tokens we don’t need to do any calls to validate the token. Token itself contains all the information which are required to validate the token and at the same time it carries user information.

So that there is no requirement for calling an external party to validate the token. Whoever has the pubic certificate of the token issuer can validate the token if it is issued for him.

What would a self contained access token look like ?

Well one of the ways is to use a JWT as the self contained access token. It will carry all the required user attributes and also other information which are required to validate the token. Following is the content of a self contained access token. With following content there will be the signature of the issuer on this token.

“sub” : “alice”,
“scp” : [ “openid”, “email”, “app:write” ],
“iss” : “",
“iat” : 1360050795,
“exp” : 1360053600,

The token it self has the issued time and expiry time. Also by validating the signature of the JWT you can validate the token.

WSO2 Identity server 5.2.0 on wards support Self contained Access tokens out of the box. If you want to get it working with 5.1.0 you can install a patch and get this scenario working.

Even Though this is supported as an extension point in 5.2.0 out of the box you need to write an extension build these tokens. Here what I have done is writing an extension to build a custom token. You can find the code of this extension from [1].

You need to build the sample and add it to IS_HOME/repository/components/dropins.

Once you copy the jar to dropins you need to add the following configuration in identity xml which is placed under $IS_HOME/repository/conf/identity/ folder inside tag OAuth.


Also you need to alter a length of a column as well. This is because by default we expect an access token to be a small string. But in self contained access tokens, access token is a large string which cannot be stored in the default column.

To do that you can go to the database and then alter the size of the column ACCESS_TOKEN of the table IDN_OAUTH2_ACCESS_TOKEN to the maximum value provided by your database provider.

Some more samples.

we have developed a sample to generate JWT tokens with ms4j. You can find that sample under msf4j samples[2][3]. If you are build it as it is you will need to use Java 8 to build since msf4j is developed on Java 8. So you will need to run Identity Server on Java 8 as well. After building the project[2] please copy the jar inside target directory to $IS_HOME/repository/components/dropins/ directory. And then please add the following configuration to Identity.xml which is placed under $IS_HOME/repository/conf/identity/ folder inside tag OAuth.


Just remember. This is an alternate to what I have said above. If you want to use java 7 you need to go with the first option.