JWT Message

The sample usecases in Authentication Basics and Multiple Resource Identities showcased how Resource Instances communicate with each other by using the the Source Identifier inside a Login Token.

An alternative way for Resources to communicate with each other is to use encrypted JSON Web Tokens (JWT). In order to create a encrypted JWT you will need to use HexaEight JWT Library

The main advantages of using JWT for exchanging secure messages are

  • Eliminate the need to exchange Login Token for Source Identification
  • Signed JWT cannot be tampered, as such the name of the source can be exposed in the JWT header
  • Ability to use a Random Password to sign the JWT and inturn use HexaEight Encryption to store the password inside the JWT.
  • Ability to secure the actual message body using HexaEight encryption.

A sample encrypted JWT can be inspected here for better clarity

The JWT consists of the following headers

  • alg: HS256 This is the actual algoritm that was used to sign the JWT. HS256 (HMAC with SHA-256) is a symmetric keyed hashing algorithm that uses one secret key. Symmetric means two parties share the secret key. The key is used for both generating the signature and validating it.

  • kid The kid (key ID) Header Parameter is a hint indicating which key was used to secure the JWT. However in the case of HexaEight JWT, the kid contains the actual secret key that was used to sign the JWT, but protected using HexaEight Encryption.

  • issuer The issuer tells us the source which created this JWT message thus eliminating the need to transmit the Login Token Source Identifier as part of the message.

  • type The type field indicates that the JWT follows Javascript Object Signing and Encryption (JOSE) and JSON Web Token (JWT) standards for Signing and encryption.

  • channelSecurityContext The channelSecurityContext field is used to highlight that the JWT was recived over a secure channel protected using HexaEight Encryption

  • iat The Issued AT header contains the unix timestamp when the JWT was created

  • exp The Expiry header contains the unix timestamp when the JWT can no longer be consumed

  • payload The payload contains the encrypted data that is intended for the destination.

JWT Creation Example

The following process outlines the method to create an encrypted JWT when Resource A wants to send an encrypted JWT message to Resource B

%%{init: { 'theme': 'forest' } }%% erDiagram HexaEightPlatform ||--|| ResourceA : Fetch-Machine-Token-of-ResourceB ResourceA ||--|| ResourceB : Sends-Encrypted-JWT ResourceA { Generate Random-Password-(SecretKey) Generates-KID By-Encrypting-SecretKey-Using-Machine-Token-of-Resource-B Encrypts-PAYLOAD By-Using-Machine-Token-of-Resource-B Populates JWT-Headers-like-ALG-KID-ISSUER-IAT-EXP Creates-JWT By-Adding-the-JWT-headers-And-Encrypted-Payload Signs-JWT By-Using-Generated-Random-Password }

Similarly Resource B uses the below procedure to decrypt the message received from Resource-A

%%{init: { 'theme': 'forest' } }%% erDiagram ResourceB ||--|| JWT-Message-Inspection : Inspects-JWT-Header JWT-Message-Inspection { Check-EXP-Header Ensures-JWT-message-has-not-expired-and-still-valid Fetch-ISSUER-Header To-Fetch-Machine-Token } HexaEightPlatform ||--|| ResourceB : Fetch-Machine-Token-of-ResourceA ResourceB ||--|| JWT-Message-Decryption : Decrypts-JWT JWT-Message-Decryption { Decrypts-KID Using-Resource-A-Machine-Token-And-Obtains-Secret-Key Validates-JWT By-Computing-Signature-using-HS256-Algorithm-using-Secret-Key Decrypts-PAYLOAD By-Using-Machine-Token-of-Resource-B }

HexaEight JWT Library provides the below two important functions to create HexaEight JWT

  • CreateEncryptedJWTTokenDirect : Fetches Machine Token of Destination and Creates Encrypted JWT

  • CreateEncryptedJWTTokenUsingSharedKey : Pass a Machine Token(Asymmetric Shared Key) to Create Encrypted JWT

as well as these two functions to decrypt the JWT

  • ValidateTokenDirect : Fetches Machine Token of Source using the JWT ISSUER header and decrypts the JWT payload

  • ValidateTokenUsingSharedKey : Pass a Machine Token(Asymmetric Shared Key) to decrypt the JWT payload.

Summary

HexaEight JWT Library can be used to securely transmit message between resources.

  • Source Resource uses the KID header to encrypt a random secret key that is used to sign the message
  • Destination Resource uses the KID header to decrypt the secret key by fetching a machine token of the source resource which is indicated in the ISSUER header
  • HexaEight JWT Library provides easy methods that can be used to create JWT messages