JWT Bearer Grant

The JSON Web Token (JWT) is simply an JSON string containing claim values. The JWT Bearer grant handler evaluates and validates the claims in the JWT token, and issues an access token at the Authorization Server end.

WSO2 API Manager, as an OAuth 2.0 Authorization Server with its Key Manager features, can accept JWT Assertions from OAuth 2.0 clients as a means of resource owner authentication and authorization. Additionally, it can exchange the JWT token with OAuth 2.0 access tokens in order to access protected resources on behalf of the resource owner.

The following diagram illustrates the flow when using a JWT grant type.

A client can exchange a JWT token to a OAuth 2.0 access token using this grant type. After you create an application in the API Store, you need to generate the keys for the application. When the keys are generated, a Service Provider is created for the respective application on WSO2 API Manager (WSO2 API-M). WSO2 API Manager uses the Service Provider (SP) entity to obtain information with regard to the application, which is in the API Store. You need to create a Identity Provider (IdP), which corresponds to the Service Provider, on the WSO2 API-M Server. The IdP is responsible for creating and signing the JWT assertion, so that the server can identify the issuer of the JWT and obtain the public certificate of the IdP in order to validate the JWT. 

When a request is made to the token endpoint with the JWT grant type, JWT assertion, client key, and client  secret, the WSO2 API-M Server will read the grant type and trigger the JWT Bearer Grant Handler. Then this handler checks for the issuer of the JWT token and retrieves the IdP configuration. It then obtains the public certificate of the IdP, which is stored in the IdP configuration, and validates the JWT. Once the JWT is validated, it will create an OAuth2.0 access token for the application holding the provided client key and client secret.  

The following sub-sections explain

Configuring the prerequisites to use the JWT Bearer grant

Follow the instructions below to configure the prerequisites, namely the Identity Provider and the Service Provider, required in order to use the JWT Bearer grant with WSO2 API Manager.

1. Sign in to the WSO2 API Store (https://localhost:9443/store).
2. Create a new application if an application is not available already.
3. Generate the production and/or sandbox keys for the application.
4. Sign in to the WSO2 API Manager Management Console (https://localhost:9443/carbon). 
5. Navigate to the Identity Providers section under the Main tab of the management console and click Add.
6. Provide the following values to configure the IdP:
   • Identity Provider Name: Enter the JWT issuer name as the identity provider name. This is used to generate the JWT assertion.

   • Identity Provider Public Certificate: The certificate used to sign the JWT assertion. 

     Identity provider Public Certificate

     The Identity Provider Public Certificate is the public certificate belonging to the identity provider. You need to update this certificate in order to authenticate the response from the identity provider. This can be any certificate. If the identity provider is another API Manager or Identity Server, this can be a wso2. crt file.

     Follow the steps below to create the identity provider certificate from the wso2carbon.jks file:

     1. Open your Command Line interface, go to the <APIM_HOME>/repository/resources/security directory, and run the following command to generate the wso2.crt file.

        keytool -export -alias wso2carbon -file wso2.crt -keystore wso2carbon.jks -storepass wso2carbon

        You can find the generated wso2.crt file in the <APIM_HOME>/repository/resources/security  directory.

     2. Click Choose File, navigate to the location of the wso2.crt file, select the file and upload it.
        For more information on how public keys work and how to sign these keys using a certification authority, see Using Asymmetric Encryption in the WSO2 Administration Guide.

   • Alias: If the Identity Provider identifies this token endpoint by an alias (e.g., https://localhost:9443/oauth2/token), enter the name of the alias. 
For more information, see Adding and Configuring an Identity Provider in the WSO2 Identity Server documentation.
     
7. Navigate to the Main menu to access the Identity menu. Click List under Service Providers.
8. Check if there is a Service Provider listed for the application, which you used to generate the keys in step 3.  The Service Provider name will have the following format.
   <application owner>_<application name>_<generated key type>
   

Using the JWT grant

After you have configured the prerequistes required to use the JWT Bearer grant, you can use the following cURL command to retrieve a access token and refresh token using a JWT.

curl -i -X POST -u <clientid>:<clientsecret> -k -d 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<JWT>' -H 'Content-Type: application/x-www-form-urlencoded' https://localhost:9443/oauth2/token

• -u - This flag should specify the “<Client Id>:<Client Secret>” value.
• assertion - The assertion parameter value is the base64 encoded JWT that is signed. The value of the assertion parameter MUST contain a single JWT. For more information, see JWT Assertion.

Access Token Endpoint: https://localhost:9443/oauth2/token?tenantDomain=wso2.com

Sample

Request

curl -i -X POST -H 'Content-Type: application/x-www-form-urlencoded' -u bBhEoE2wIpU1zB8HA3GfvZz8xxAa:RKgXUC3pTRQg9xPpNwyuTPGtnSQa -k -d 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NTgxNjY5ODUsInN1YiI6ImFkbWluIiwibmJmIjoxNDU4MTA2OTg1LCJhdWQiOlsiaHR0cHM6XC9cL2xvY2FsaG9zdDo5NDQzXC9vYXV0aDJcL3Rva2VuIiwid3NvMi1JUyJdLCJpc3MiOiJqd3RJRFAiLCJqdGkiOiJUb2tlbjU2NzU2IiwiaWF0IjoxNDU4MTA2OTg1fQ.ZcxdoTVEsWoil80ne42QzmsfelMWyjRZJEjUK1c2vMZJjjtrZnsWExyCA5tN6iXYFAXC_7rkFuuNSgOlBi51MNLPZw3WcgGI52j6apGEW92V2tib9zRRWOeLQLAdo8ae8KzLp7kuKZ2XunfQ2WYU9TvvLDm_vp5ruuYz3ZZrJOc' https://localhost:9443/oauth2/token

Response

The following is the response that you receive from the token endpoint based on the sample request. The response contains the access token, refresh token, expiry time, and the token type. 

{"token_type":"Bearer","expires_in":3600,"refresh_token":"b1b4b78e2b0ef4956acb90f2e38a8833","access_token":"615ebcc943be052cf6dc27c6ec578816"} 

JWT Assertion

JWT contains three parts that are separated by dots ".", namely the header, payload, and signature. The header identifies the algorithm used to generate the signature.

For example, see the following code block.

{
	"alg":"RS256"
}

The payload contains the claims mentioned below:

• iss (issuer) - The JWT must contain an iss (issuer) claim that contains a unique identifier that identifies the Identity Provider that issued the JWT.
• sub (subject) - The JWT must contain a sub (subject) claim that identifies the entity that the Identity Provider or the entity that issued the JWT vouches for.
• aud (audience) - The JWT must contain an aud (audience) claim which containing a value that identifies the authorization server as an intended audience. You should register this value as a token endpoint alias in the Identity Provider.
• exp (expiration time) - The JWT must contain an exp (expiration) claim that limits the time window during which you can use the JWT.
• nbf (not before) - The JWT may contain a nbf (not before time) claim that determines a specific time after which the JWT can be used.
• iat (JSON issued at) - The JWT may contain an iat (issued at) claim that identifies the time at which the JWT is issued.
• jti (JSON web token ID) - The JWT may contain an jti (JWT ID) claim that provides a unique identifier for the token.
• Other custom claims - JWT may contain claims other than the above mentioned ones. This is the extension point of the JWT specification.

For example, see the following code block.

{  
   "sub":"admin",
   "aud":[  
      "https://localhost:9443/oauth2/token"
   ],
   "nbf":1507546100,
   "iss":"jwtIDP",
   "exp":1507606100,
   "iat":1507546100,
   "jti":"Token56756"
}

Generating a JWT assertion

1. Generate the signature.
   1. Encode the header and the payload separately using a base64 URL.

   2. Concatenate the encoded header and payload with a period and sign it to generate the signature.

      Signature = sign(encodeBase64(header) + '.' + encodeBase64(payload))

2. Encode the signature using a base64 URL.

3. Generate the JWT assertion by concatenating the values of the base64 URL encoded header, payload, and signature using a dot "." as the separator.

   assertion =  encodeBase64(header) + '.' + encodeBase64(payload) + '.' + encodeBase64(signature)

   The result is as follows:

   Sample JWT assertion

   eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImF1ZCI6WyJodHRwczpcL1wvbG9jYWxob3N0Ojk0NDNcL29hdXRoMlwvdG9rZW4iXSwibmJmIjoxNTA3NTQ2MTAwLCJpc3MiOiJqd3RJRFAiLCJleHAiOjE1MDc2MDYxMDAsImlhdCI6MTUwNzU0NjEwMCwianRpIjoiVG9rZW41Njc1NiJ9.iGMhjibB0W2QFQlM27gnHp6z47Eybv8cAHk2o2i-xqo2S4uJ_1VppFI4CCJXTj4qzV9vmkJ5HKNAayiTa6wOMXGL4XnwYwpOAoKXvboznlEDNRpw3htW34nLvyUu6PjHbdvAPVjh8kPRwf7esRr2p-luecGvC21mjWdhyGzM4hE