Token API. JWT Grant.

Token API.
JWT Grant

1. Introduction
2. Configuring the JWT grant
3. Using the JWT grant
4. Interaction Diagram

1. Introduction

The JSON Web Token (JWT) bearer grant is simply a JSON string containing claim values that will be evaluated and validated by the JWT Grant Handlers at the Authorization Server end, before issuing an access token. WSO2 API Manager or WSO2 Identity Server, as an OAuth 2.0 Authorization Server with its Key Manager features, can accept JWT Assertions from OAuth 2.0 clients as 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.

•  Authorization grant types:

Kerberos OAuth2 Grant
Refresh Token Grant
Authorization Code Grant
NTLM Grant
Password Grant
SAML Extension Grant
Client Credentials Grant
Implicit Grant
JWT Grant

On this blog I am going to do a PoC for JWT Grant.

2. Configuring the JWT grant

This configuration can be done in the APIManager or in the Identoty Server. I am going to do it on the Identity Server because the API Manager, on my PoC, uses the Key Manager of the IS.

1) Log in to WSO2 IS.

2) Add a new Service Providers.
It is going to get JWT tokens on behalf of the users.

3) Fill in the Service Provider Name and provide a brief Description of the service provider.
Service Provider Name: jwt-tester

4) Expand the OAuth/OpenID Connect Configuration and click Configure.

5) The OAuth Client Key and OAuth Client Secret will now be visible.

Take note of the OAuth Client key because it is going to be used by the IdP.

6) Go to Identity Providers section and click Add.
The image displays one configuration I have created in a previous blog.

7) Provide the following values to configure the IDP:
Identity Provider Name: Enter an issuer name as the identity provider name. This is used to generate the JWT assertion. This value is the same that has been configured into
<wso2is-km-5.6.0>\repository\conf\identity\identity.xml file in the Identity Server.

/Server/OAuth/IDTokenIssuerID: apim-idp

Identity Provider Public Certificate: The certificate used to sign the JWT assertion. This is necessary to authenticate the response from the identity provider. On my PoC it is needed to import public certificated of the IS into the API Manager if the IS server is not running in localhost, because by default WSO2 includes certificates for localhost in all its products.

Alias: It is the OAuth Client key of the Service Provider.

3. Using the JWT grant

1) Request for JWT token.
This request is going to be done using a password grant_type.
For instance:
curl -u ClientID_sp:ClientSecret_sp
     -k -d “grant_type=password&username=testuser&password=testuser”
     -H “Content-Type:application/x-www-form-urlencoded”           
     https://localhost:9444/oauth2/token

This is the same request/respose by SOAPUI to get a JWT token:
It uses ClientID_sp:ClientSecret_sp of the Service Provider.

Response:
HTTP/1.1 200 OK
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-store
Date: Thu, 05 Dec 2019 10:26:31 GMT
Pragma: no-cache
Content-Type: application/json
Content-Length: 956
Server: WSO2 Carbon Server

{"access_token":"eyJ4NXQiOiJOVEF4Wm1N...qbCyWBdR_ZQ-hdk7tFA",
  "refresh_token":"08f71bbb-0c35-3e86-9e9e-6667ef5b2d09",
  "scope":"default","token_type":"Bearer","expires_in":3600}

2) Request for access_token.
And this is the request that uses JWT token to get an access token:
It uses ConsumerKey:ConsumerSecret of the Application in WSO2 Store.

Response:
HTTP/1.1 200 OK
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-store
Date: Thu, 05 Dec 2019 10:31:16 GMT
Pragma: no-cache
Content-Type: application/json
Content-Length: 168
Server: WSO2 Carbon Server

{"access_token":"1ad1208b-8785-337a-b397-969f3f2bfdc8",
 "refresh_token":"335a8b78-a9e8-371a-bc49-c84651485a40",
 "scope":"default","token_type":"Bearer","expires_in":3600}

Notes:

• Tenant Domain

If the service provider and identity provider are in a tenant, you have to add the tenant domain as a query parameter to the access token endpoint. If the tenant domain is wso2.com, the access token endpoint will be as follows.

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

• JWT Bearer Grant

JWT contains three parts that are separated by dots ".":
header, payload, and a signature.

This is the JWT token decoded:

The payload contains the claims mentioned below:

Name	Description
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. This value should be registered as 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 the JWT can be used.
nbf (not before)	The JWT may contain a nbf (not before time) claim that forces a JWT to be used only after a specified time.
iat (issued at)	The JWT may contain an iat (issued at) claim that identifies the time at which the JWT was issued.
jti (json web token ID)	The JWT may contain 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.

4. Interaction Diagram

This sequence diagram displays the interaction between components to request for a JWT token and to use it.