JWT flow

A JSON Web Token (JWT) is a JSON-based security token encoding that enables identity and security information to be shared across security domains.

OAuth 2.0 JWT Flow

In the OAuth 2.0 JWT flow, the client application is assumed to be a confidential client that can store the client application's private key. The X.509 certificate that matches the client's private key must be registered in the Client Application Registry. The API Gateway uses this certificate to verify the signature of the JWT claim.

For more details on the OAuth 2.0 JWT flow, go to:
http://self-issued.info/docs/draft-ietf-oauth-jwt-bearer-00.html

Create a JWT bearer token

To create a JWT bearer token, perform the following steps:

  1. Construct a JWT header in the following format:
  2. {"alg":"RS256"}
  3. Base64url encode the JWT header, which results in the following:
  4. eyJhbGciOiJSUzI1NiJ9
  5. Create a JWT claims set, which conforms to the following rules:
    • The issuer (iss ) must be the OAuth client_id  or the remote access application for which the developer registered their certificate.
    • The audience (aud ) must match the value configured in the JWT filter. By default, this value is as follows:
    • http://apigateway/api/oauth/token
    • The validity (exp ) must be the expiration time of the assertion, within five minutes, expressed as the number of seconds from 1970-01-01T0:0:0Z measured in UTC.
    • The time the assertion was issued (iat ) measured in seconds after 00:00:00 UTC, January 1, 1970.
    • The JWT must be signed (using RSA SHA256).
    • The JWT must conform with the general format rules specified here:
      http://tools.ietf.org/html/draft-jones-json-web-token
    • For example:
    • {
          "iss":"SampleConfidentialApp",
          "aud":"http://apigateway/api/oauth/token",
          "exp":"1340452126",
          "iat":"1340451826"
      }
  6. Base64url encode the JWT claims set, resulting in:
  7. eyJpc3MiOiJTYW1wbGVDb25maWRlbnRpYWxBcHAiLCJhdWQiOiJodHRwOi8vYXBpc2VydmV
     yL2FwaS9vYXV0aC90b2tlbiIsImV4cCI6IjEzNDA0NTIxMjYiLCJpYXQiOiIxMzQwNDUxODI2In0=
  8. Create a new string from the encoded JWT header from step 2, and the encoded JWT claims set from step 4, and append them as follows:
  9. Base64URLEncode(JWT Header) + . + Base64URLEncode(JWT Claims Set)
  10. This results in a string as follows:
  11. eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiAiU2FtcGxlQ29uZmlkZW50aWFsQXBwIiwgImF1ZCI6ICJodHRw
     Oi8vYXBpc2VydmVyL2FwaS9vYXV0aC90b2tlbiIsICJleHAiOiAiMTM0MTM1NDYwNSIsICJpYXQiOiAi
     MTM0MTM1NDMwNSJ9
  12. Sign the resulting string in step 5 using SHA256 with RSA. The signature must then be Base64url encoded. The signature is then concatenated with a . character to the end of the Base64url representation of the input string. The result is the following JWT (line breaks added for clarity):
  13. {Base64url encoded header}.
    {Base64url encoded claim set}.
  14. This results in a string as follows:
  15. eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiAiU2FtcGxlQ29uZmlkZW50aWFsQXBwIiwgImF1ZCI6ICJodHR
     wOi8vYXBpc2VydmVyL2FwaS9vYXV0aC90b2tlbiIsICJleHAiOiAiMTM0MTM1NDYwNSIsICJpYXQiOiA
     iMTM0MTM1NDMwNSJ9.ilWR8O8OlbQtT5zBaGIQjveOZFIWGTkdVC6LofJ8dN0akvvD0m7IvUZtPp4dx3
     KdEDj4YcsyCEAPhfopUlZO3LE-iNPlbxB5dsmizbFIc2oGZr7Zo4IlDf92OJHq9DGqwQosJ-s9GcIRQk
     -IUPF4lVy1Q7PidPWKR9ohm3c2gt8

Request an access token

The JWT bearer token should be sent in an HTTP POST to the token endpoint with the following parameters:

Parameter Description

grant_type

Required. Must be set to
urn:ietf:params:oauth:grant-type:jwt-bearer.

assertion

Required. Must be set to the JWT bearer token, base64url-encoded.

format

Optional. Expected return format. The default is json. Possible values are:

  • urlencoded
  • json
  • xml

The following is an example POST request:

POST /api/oauth/token HTTP/1.1
Content-Length:424
Content-Type:application/x-www-form-urlencoded; charset=UTF-8
Host:192.168.0.48:8080
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
 &assertion=eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiAiU2FtcGxlQ29uZmlkZW50a
 WFsQXBwIiwgImF1ZCI6ICJodHRwOi8vYXBpc2VydmVyL2FwaS9vYXV0aC90b2tlbiIsI
 CJleHAiOiAiMTM0MTM1NDYwNSIsICJpYXQiOiAiMTM0MTM1NDMwNSJ9.ilWR8O8OlbQt
 T5zBaGIQjveOZFIWGTkdVC6LofJ8dN0akvvD0m7IvUZtPp4dx3KdEDj4YcsyCEAPhfop
 UlZO3LE-iNPlbxB5dsmizbFIc2oGZr7Zo4IlDf92OJHq9DGqwQosJ-s9GcIRQk-IUPF
 4lVy1Q7PidPWKR9ohm3c2gt8

Handle the response

The API Gateway returns an access token if the JWT claim and access token request are properly formed, and the JWT has been signed by the private key matching the registered certificate for the client application in the Client Application Registry.

For example, a valid response is as follows:

HTTP/1.1 200 OK
Cache-Control:no-store
Content-Type:application/json
Pragma:no-cache
{
    "access_token":“O91G451HZ0V83opz6udiSEjchPynd2Ss9......",
    "token_type":"Bearer",
    "expires_in":"3600",
}

Run the sample client

The following Jython sample creates and sends a JWT bearer token to the authorization server:

INSTALL_DIR/samples/scripts/oauth/jwt.py

To run the sample, open a shell prompt at INSTALL_DIR/samples/scripts, and execute the following command:

> run oauth/jwt.py

Related Links