JSON Web Tokens in ColdFusion

What is a JWT?

JWT, or JSON Web Token, is an open standard allowing clients and servers to exchange security-related data. Every JWT has a set of encoded JSON objects, including claims. To ensure that the claims cannot be changed after the token is issued, JWTs are signed using a cryptographic technique.

Consider a very basic microservices-based application with a limited number of services for the application's various capabilities. Without JWT, the authentication server becomes a bottleneck for all requests that must be handled. To verify the credentials of the current request, each microservice must contact the authentication server.

Using JWT, you can reduce the burden on the authentication server. After authentication, the auth server publishes a token. Every request is submitted with this token, which is maintained by the client or microservice. Without the requirement for a network operation, the server/microservice/party that receives the request can independently validate the token. This might be extremely important when an architecture grows to include thousands of microservices. JWTs decrease latency by reducing the number of network calls.

Parts of a JWT

A JWT is a string made up of three parts, separated by dots (.), and serialized using base64. In the most common serialization format, compact serialization, the JWT looks something like this: xxxxx.yyyyy.zzzzz.

After decoding, you will get two JSON strings:

• The header and the payload.
• The signature.

Header

The JWT header metadata about the type of token and the cryptographic algorithms that are used to secure its contents.

{

      "alg": "HS256",

      "typ": "JWT"

 }

The header consists of the following fields:

• alg - Algorithm
• jku - JWK Set URL
• jwk - JSON Web Key
• kid - Key ID(indicates which key was used to secure the JWS)
• x5u - X509 certificate(chain) URL
• x5c - X509 certificate
• x5t - X509 cert SHA-1 thumbprint
• x5t#256 - X509 cert SHA-256 thumbprint
• typ - Type of the token
• cty - Content Type
• crit - Critical Header

Payload

The JWT payload contains the identity of a user and the allowable permissions.

{

      "sub": "007",

      "name": "James Bond",

      "admin": true

}

The following claims are supported in a JWT payload:

• iss
• sub
• aud
• exp
• nbf
• iat
• jti

Signed JWT (JSON Web Signature - JWS)

A JWS has three parts:

• BASE64URL(UTF8(JWS Protected Header)) || '.' ||
• BASE64URL(JWS Payload) || '.' ||
• BASE64URL(JWS Signature)

The supported signature algorithms are:

• HS256
• HS384
• HS512
• RS256
• RS384
• RS512
• ES256
• ES384
• ES512
• PS256
• PS384
• PS512

Encrypted JWT(JSON Web Encryption - JWE)

JWE has five parts:

• BASE64URL(UTF8(JWE Protected Header)) || '.' ||
• BASE64URL(JWE Encrypted Key) || '.' ||
• BASE64URL(JWE Initialization Vector) || '.' ||
• BASE64URL(JWE Ciphertext) || '.' ||
• BASE64URL(JWE Authentication Tag)

Supported content encryption algorithms

• A128CBC-HS256
• A192CBC-HS384
• A256CBC-HS512
• A128GCM
• A192GCM
• A256GCM

Key Encryption algorithms:

• RSA-OAEP
  
• RSA-OAEP-256
• ECDH-ES
• ECDH-ES+A128KW
• ECDH-ES+A192KW
• ECDH-ES+A256KW
• A128KW
• A192KW
• A256KW
• A128GCMKW
• A192GCMKW
• A256GCMKW
• PBES2-HS256+A128KW
• PBES2-HS384+A192KW
• PBES2-HS512+A256KW

JSON Web Signature (JWS) and JSON Web Encryption (JWE)

ColdFusion also supports JWS and JWE.

Supported JWT methods

• createSignedJWT
• createEncryptedJWT
• verifySignedJWT
• verifyEncryptedJWT

Document revision history

• Removed the algorithm RSA1_5 in ColdFusion (2023 release) Update 7.