Passing Enduser Attributes to the Backend Using JWT

JSON Web Token (JWT) is used to represent claims that are transferred between two parties such as the enduser and the backend. A claim is an attribute of the user that is mapped to the underlying user store. It is encoded as a JavaScript Object Notation (JSON) object that is used as the payload of a JSON Web Signature (JWS) structure, or as the plain text of a JSON Web Encryption (JWE) structure. This enables claims to be digitally signed.

A set of claims is called a dialect (e.g. http://wso2.org/claims). The general format of a JWT is {token infor}.{claims list}.{signature}. The app implementation uses information such as logging, content filtering, and authentication/authorization that is stored in this token. The token is Base64-encoded and sent to the app implementation in a HTTP header variable. The JWT is self-contained and is divided into three parts as the header, the payload, and the signature. For more information on JWT, see http://openid.net/specs/draft-jones-json-web-token-07.html#anchor3.

To authenticate endusers, the App Manager passes attributes of the app invoker to the backend app implementation using JWT. In most production deployments, service calls go through the App Manager or a proxy service. If you enable JWT generation in the App Manager, each app request will carry a JWT to the back-end service. When the request goes through the App Manager, the JWT is appended as a transport header to the outgoing message. The back-end service fetches the JWT and retrieves the required information about the user, application, or token.

An example of a JWT is given below.

{
    "typ":"JWT",
    "alg":"NONE"
 }{
    "iss":"wso2.org/products/appm",
    "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":"peter"
 }

The above 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")

Information on how to enable and pass information in the JWT in the App Manager are described below.

Configuring JWT

Before passing enduser attributes, you enable and configure the JWT implementation in the <AppM_HOME>/repository/conf/app-manager.xml file. The relevant elements are described below. If you do not configure these elements, they take their default values.

Element Description Default Value

<EnableTokenGeneration>

Set this value to true, to enable JWT.

If you publish apps before JWT is enabled, you have to republish them.

false

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

<ClaimsRetrieverImplClass/>

By default, the <ClaimsRetrieverImplClass> parameter is commented out in the app-manager.xml file. Enable it to add all user claims in the JWT token:

<ClaimsRetrieverImplClass>org.wso2.carbon.appmgt.impl.token.DefaultClaimsRetriever</ClaimsRetrieverImplClass>

By default, the following are encoded to the JWT:

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

In addition, you can also write your own class by extending the org.wso2.carbon.apimgt.impl.token.ClaimsRetriever interface and implementing the following methods of the interface:

Method Description

void init() throws AppManagementException;

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

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

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 the following as part of the body.

“http://wso2.org/claims/gender”:“user1@wso2.com”,“http://wso2.org/claims/email”:“male”

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.appmgt.impl.token.DefaultClaimsRetriever

<ConsumerDialectURI/>

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

The 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 the JWT. It will include all claims in http://wso2.org/claims to the JWT token.

http://wso2.org/claims

<SignatureAlgorithm/>

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, which is SHA256WITHRSA or NONE.

SHA256WITHRSA

Change the value of the <AddClaimsSelectively> element to true, to send the claims you select in the Step 4 - Advanced Configuration of creating the Web app to the backend using JWT. By default, this is set to false to send all the claims that are associated to the user profile. For more information on claims, see Claim Management. Follow the steps below to view the claims that are associated to a user role by default.

Log in to the AppM management console using the following URL: https://<AppM_HOST>:<AppM_PORT>/carbon/
Click Configure, then click Users and Roles.
Click Users, and then click User Profile of the corresponding user.