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.
| Code Block |
|---|
{
"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"
} |
...
- 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
| false | |||||||||||||
<SecurityContextHeader/> | The name of the HTTP header to which the JWT is attached. | X-JWT-Assertion | |||||||||||||
<ClaimsRetrieverImplClass/> | By default, the
By default, the following are encoded to the JWT:
In addition, you can also write your own class by extending the
| 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 The JWT token contains all claims define in the
| http://wso2.org/claims | |||||||||||||
<SignatureAlgorithm/> | The signing algorithm used to sign the JWT. The general format of the JWT is | SHA256WITHRSA |
...
| Note |
|---|
Similar to passing end user attributes to the backend using JWT, you can pass authentication information to the backend of AppM by returning a SAML response. To enable returning the SAML response to backend, set the value of the |