Passing Enduser attributes to the Backend Using JWT

JSON Web Token (JWT) is used to represent claims that are transferred between two parties. A claim is an attribute of the user that is mapped to the underlying user store. A set of claims is called a dialect (e.g., http://wso2.org/claims). JWT is standardised, light-weight, easy to parse and consume and can be signed. The general format of the JWT is {token infor}.{claims list}.{signature}. For more information on JWT, look here.

The API Manager uses JWT to pass attributes of the API invoker to the backend API implementation. The API implementation can use information such as logging, content filtering and authentication/authorization that are stored in this token. The token is Base64-encoded and sent to the API implementation in a HTTP header variable.

An example of the JWT passed in the API Manager is given below:

{
    "typ":"JWT",
    "alg":"NONE"
 }{
    "iss":"wso2.org/products/am",
    "exp":1345183492181,
    "http://wso2.org/claims/subscriber":"admin",
    "http://wso2.org/claims/applicationname":"app2",
    "http://wso2.org/claims/apicontext":"/placeFinder",
    "http://wso2.org/claims/version":"1.0.0",
    "http://wso2.org/claims/tier":"Silver",
    "http://wso2.org/claims/enduser":"sumedha"
 }

As shown in the above example, the token contains,

Token expiration time ("exp")
Subscriber to the API, usually the app developer ("http://wso2.org/claims/subscriber")
Application through which API invocation is done ("http://wso2.org/claims/applicationname")
Context of the API ("http://wso2.org/claims/apicontext")
API version ("http://wso2.org/claims/version")
Tier/price band for the subscription ("http://wso2.org/claims/tier")
Enduser of the app who's action invoked the API ("http://wso2.org/claims/enduser")

Configuring JWT

Given below is how to configure JWT generation in the API Manager.

Open <APIM_HOME>/repository/conf/api-manager.xml file and enable JWT as follows.
```
<EnableTokenGeneration>true</EnableTokenGeneration>
```
If you publish APIs before JWT is enabled, you have to republish them to include JWT.

Configure the rest of the elements in the same XML file as described in the table below. If you do not configure them, the default values will be applied.

Element Description Default Value

<SecurityContextHeader/> The name of the HTTP header to which the JWT is attached. X-JWT-Assertion

By default, the following are encoded to the JWT:

subscriber name
application name
API context
API version
authorised resource owner name

To override this behaviour, write your own class by extending the interface org.wso2.carbon.apimgt.impl.token.ClaimsRetriever. The methods in this interface are described below:

Method Description

void init() throws APIManagementException;

Used to perform initialisation tasks. Is executed once, right before the very first request.

SortedMap<String,String> getClaims(String endUserName) throws APIManagementException;

Returns a sorted map of claims. The key of the map indicates the user attribute name and the value indicates the corresponding user attribute value. The order in which these keys and values are encoded depends on the ordering defined by the sorted map.

String getDialectURI(String endUserName);

The dialect URI to which the attribute names returned by the getClaims() method are appended to. For example,
if the getClaims method returns {email:user1@wso2.com, gender:male} and the getDialectURI() returns http://wso2.org/claims, the JWT will contain “http://wso2.org/claims/gender”:“user1@wso2.com”,“http://wso2.org/claims/email”:“male” as part of the body.

The default implementation (org.wso2.carbon.apimgt.impl.token.DefaultClaimsRetriever) returns the user's attributes defined under the dialect URI http://wso2.org/claims and the JWT will also be encoded with the same dialect URI. The order of encoding the user's attributes is the natural order of the attributes. If no value is specified, no additional claims will be encoded, except the 6 default attributes.

org.wso2.carbon.apimgt.impl.token.DefaultClaimsRetriever

The dialect URI under which the user's claims are be looked for. Only works with the default value of <ClaimsRetrieverImplClass> element defined above.

JWT token contains all claims define in the <ConsumerDialectURI> element. The default value of this element is http://wso2.org/claims. To get a list of users to be included in the JWT, simply uncomment this element after enabling JWT. It will include all claims in http://wso2.org/claims to the JWT token.

http://wso2.org/claims

The signing algorithm used to sign the JWT. The general format of the JWT is {token infor}.{claims list}.{signature}. When NONE is specified as the algorithm, signing is turned off and the JWT looks as {token infor}.{claims list}, with two strings delimited by a period and a period at the end.

This element can have only two values - the default value (SHA256WITHRSA) or NONE.

SHA256WITHRSA