JWT Concepts

References

https://blog.angular-university.io/angular-jwt/
RFC7519 - JSON Web Token Best Current Practices.

JWT Authentication Sequence

The diagram above shows a typical authentication sequence flow using JWT tokens between the user’s browser and the App Server.
Here, the assumption is that the App Server is the one performing the user authentication.
In an enterprise architecture, the authentication would be carried out by an external authentication server or identity provider for the browser to get the JWT token, before the application resumes authenticated communication with the App Server.
For details, see the sections below on Client Interaction and Server Interaction.

Why JWTs?

Allows the authentication logic to be handled by a third-party server which could be:
- a commercial product such as Microsoft AD, that is already deployed on the corporate network.
- a central in-house custom developed authentication server.
- a completely external third-party authentication provider such as Auth0.
- the secret private key does not have to be shared with any other systems on the network. Normally, a symmetric key is used, but for enhanced security, asymmetric keys should be used.
- does not require any secret private key to be installed on a server that can be accidentally lost or stolen.
- does not require a direct live link between the authentication server or the application server.
- the application server can be completely stateless as there is no need to keep tokens in-memory between requests. The authentication server can issue the token, send it back and then immediately discard it.

What are JWTs?

Encoded JWT (line breaks for display only)

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIzNTM0NTQzNTQzNTQzNTM0N TMiLCJleHAiOjE1MDQ2OTkyNTZ9.zG-2FvGegujxoLWwIQfNB5IT46D-xC4e8dEDYwi6aRM

The JWT example shown above is decrypted but encoded with Base64Url, so that it can be transmitted across the network properly, even as a URL parameter.
A JWT consists of 3 parts (separated by a period): the Header (eyJ…CJ9), the Payload (eyJ…TZ9) and the Signature (zG-….aRM).
The JWT is an open industry standard (RFC 7519) method for representing claims securely between two parties.
The contents of the above JWT are described below.

Payload

{         # The information or claim by the client
  "sub": "123456789"    # A technical (user) identifier
  "name": "John Doe",
  "email": "john@johndoe.com",
  "admin": true
}

The payload can be any identification information regarding the transaction.
The JWT is not encrypted.

Signature

The signature of a JWT is created by combining the { base64UrlEncoded(header) + “.” + base64UrlEncoded(payload), secret } and performing the HMACSHA512 operation.
The signature of a JWT can only be created by the system that is in possession of both the payload (initially coming from the authentication server) with the header and the shared symmetric key (HS256/512) or secret private key (RS256/512).
Only the Authentication server would have this, when it receives the user login credentials.
The sequence starts as follows:

Client Interaction with Authentication Server

The user submits the username and password to an Authentication server.
The Authentication server validates the username and password and creates a payload containing the identified user and expiration time stamp.
The Authentication server creates the HS256/HS512 signature from the Header and Payload, creates the JWT using the shared secret key and returns this back to the client browser.
The client application then sends this signed JWT with every HTTP request.
In the case of a client browser application, the JWT can be stored in the HTML5 Web Storage as shown below and use it for all HTTP requests with the application server.

function tokenSuccess(err, response) {
    if(err){
        throw err;
    }
    $window.sessionStorage.accessToken = response.body.access_token;
}

Application Server Interaction

The Application server is configured with the shared symmetric secret key (or shared public key) out of band.
It checks the JWT signature by decoding the header with payload to re-create the signature and confirms that it was encrypted by the shared secret key.
The Payload identifies the user of this transaction and the JWT’s expiration.

Benefits

The signed token allows the application server to check if the token is authentic, by using the Authentication server’s public key. By possessing just this public key, it allows the application server to be stateless.
The Authentication server does not have to get involved in every transaction between the client and the Application server.
The password is not sent with every transaction. Nor does it have to be kept by the Application server.

Standard Payload Fields

iss Issuer: identifies the principal that issued the JWT.
sub Subject: subject of the JWT.
aud Audience: the intended recipients for the JWT.
exp Expiry: the expiration time. NumericDate format.
nbf Not Before: the time on which the JWT will start to be accepted for processing. NumericDate format.
iat Issued At: the time on which the JWT was issued. NumbericDate format.
jti JWT ID: case sensitive unique identifier of the token based on issuer.

Another JWT Example

Encoded JWT (line breaks for display only)

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJzZWN1cmUtYXBpI iwiYXVkIjoic2VjdXJlLWFwcCIsInN1YiI6ImFwcHVzZXIiLCJleHAiOjE1OTI wMjI1MDEsInJvbCI6WyJST0xFX0FETUlOIl19.-ai87nrBMv5lZzKWOATV1GuC izLC-uRy7Rtl4pLUelD-AyNh1i-zOfNsRmOojLPAC6MYqm6jNsCVZpieulS4uw

The JWT provided above is encoded in base64Url.

JWT Example Decoded

Header: Algorithm & Token Type

{
  "typ": "JWT",     # Type of Token
  "alg": "HS512"    # Signature or encryption algorithm
}

The header provided above is from the eyJ0…MiJ9 portion of the encoded JWT.

Payload: Data

{
  "iss": "secure-api",    # Issuer (who created and signed this token)
  "aud": "secure-app",    # Audience (who or what the token is intended for)
  "sub": "appuser",       # Subject (whom the token refers to)
  "exp": 1592022501,      # Expiry on Sat, 13 Jun 2020 at 12:28:21
  "rol": [
    "ROLE_ADMIN"          # Customised data to be included in the token
  ]
}

The payload provided above is from the eyJpc…OIl19 portion of the encoded JWT.

Verify Signature

HMAC-SHA512(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  # your 256 bit secret goes here
)

The Signature provided above is from the from the header and payload, i.e. eyJ0…OIl19 portion of the encoded JWT. The encryption algorithm used for the above JWT is HS512.