JWT authentication

JSON Web Token (JWT) is a compact claims representation format that is intended for space constrained environments such as HTTP Authorization headers and URI query parameters. A claim is represented as a name-value pair that contains a Claim Name and a Claim Value.

The claims in a JWT are encoded as a 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. JWT claims can be digitally signed or integrity protected with a Message Authentication Code (MAC) and they can also be encrypted.

JWT Overview

JWT represents a set of claims as a JSON object that is encoded in a JWS or JWE structure. This JSON object is the JWT Claims Set. The JSON object consists of zero or more name-value pairs (or members), where the names are strings and the values are arbitrary JSON values. These members are the claims that are represented by the JWT. The member names within the JWT Claims Set are referred to as Claim Names. The corresponding values are referred to as Claim Values.

A JWT is represented as a sequence of URL-safe parts separated by period (’.’) characters. Each part contains a base64url-encoded value. The number of parts in the JWT is dependent upon the representation of the resulting JWS using the JWS Compact Serialization or JWE using the JWE Compact Serialization.

Types of JWT

JWT is primarily of following two types:

JSON Web Signature (JWS) – The content of this type of JWT is digitally signed to ensure that the contents of the JWT are not tampered in transit between the sender and the receiver. The content or claims of the JWS might be readable by other parties as well. Hence, a JWS can be used to verify the integrity of the content or claim but it should not be used to transfer sensitive data like passwords. JWS is typically used over HTTPS or SSL because it does not inherently prevent the data from being read.
JSON Web Encryption (JWE) – The content of this type of JWT is digitally encrypted. This means it can be used to verify the integrity and protect the content. It can be used over plain HTTP as it is inherently encrypting the content.

Note: Sterling Order Management System supports only JWS.

JWT Example

The format of a typical JWS is <Base 64 URL encoded Header json>.<Base 64 URK encoded Payload json>.<Base 64 URL encoded signature>

The following signature is obtained by signing the contents of the Base 64 URL encoded header and payload with a cryptographic key by using the RS256 algorithm.

Header 
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "a1"
}

Payload
{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true,
  "iat": 1516239022,
  "exp": 1531762065
}

The following illustration is the sample JWS representation of JWT signed with RS256 private key.

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImExIn0
.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMiwiZXhwIjoxNTMxNzYyMDY1fQ
.z4qfO0leZK2mYp_w-jFNidTx-Ri0PRMHLsOAG1Den7ZR4QntIJhU17U0afgoe5VzISXS6jW61ga3XEk39ey1G7a_-ARIVZLYN11fHDhsPuzN7PPkbT
5uWpHEUhVWRR8dxHqXmNiDaWjNhTnzHCBpfrRHj5pR_dzubbuE_uPuvDk

As illustrated in the sample, the JWS has the following parts and is separated by the "." character.

Header = eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImExIn0
Payload = G4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMiwiZXhwIjoxNTMxNzYyMDY1fQ
Signature = z4qfO0leZK2mYp_w-jFNidTx-Ri0PRMHLsOAG1Den7ZR4QntIJhU17U0afgoe5VzISXS6jW61ga3XEk39ey1G7a_-ARIVZLYN11fHDhsPuzN7PPkbT5uWpHEUhVWRR8dxHqXmNiDaWjNhTnzHCBpfrRHj5pR_dzubbuE_uPuvDk