Construct Messages Using JSON Web Tokens

Follow these steps to construct messages using JWTs:

Generate a hash of the message body. See Generate a Hash of the Message Body.

Populate the header values. See Generate the Token Header.

Generate a hash of the claim set. See Generate a Hash of the Claim Set.

Generate a hash of the token header. See Generate a Hash of the Token Header.

Generate a token signature hash. See Generate a Token Signature.

Populate the

signature

header field. See Update Header Fields.

Elements of a JSON Web Token Message

A JWT Message is built with these elements:

Headers

Your message header must include these header fields:

Header Fields
Header Field	Description
v-c-merchant-id	Your `Cybersource` organization ID.
Date	The date of the transaction in the RFC1123 format. (Thu, 18 Jul 2019 00:18:03 GMT)
Content-Type	Also known as the Multipurpose Internet Mail Extension (MIME) type, this identifies the media or file type of the resource. (application/json)
kid	The ID of the key used to digitally sign the JWT. The Key ID (kid) must be registered with the authorizing server.
Host	The transaction endpoint. (`https://api.cybersource.com`)
alg	Algorithm used to sign the token header.

Body

The message body. For more information on setting up the body, see Generate a Hash of the Message Body.

Generate a Hash of the Message Body

Generate a Base64-encoded SHA-256 hash of the message, and place the hash in the header's

digest

field. This hash is used to validate the integrity of the message at the receiving end.

Follow these steps to generate the hash:

Generate the SHA-256 hash of the JSON payload (body of the message).

Encodejava.io.PrintWriter@a68810d the hashed string to Base64.

Add the message body hash to the

digest

payload field.

Add the hash algorithm used to the

digestAlgorithm

payload field.

Example: Digest Header Field

    digest: RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=

Example: DigestAlgorithm Header Field

    digestAlgorithm: SHA-256

Code Example: Creating a Message Hash Using C#

    public static string GenerateDigest() {
     var digest = "";
     var bodyText = "{ your JSON payload }";
     using (var sha256hash = SHA256.Create()) {
         byte[] payloadBytes = sha256hash
             .ComputeHash(Encoding.UTF8.GetBytes(bodyText));
         digest = Convert.ToBase64String(payloadBytes);
         digest = digest;
     }
     return digest;
}

Code Example: Creating a Message Using Java

    public static String GenerateDigest() throws NoSuchAlgorithmException {
     String bodyText = "{ your JSON payload }";
     MessageDigest md = MessageDigest.getInstance("SHA-256");
     md.update(bodyText.getBytes(StandardCharsets.UTF_8));
     byte[] digest = md.digest();
     return Base64.getEncoder().encodeToString(digest);
}

Generate the Token Header

The token header is encrypted with a URL safe base64 algorithm. These three header fields must be included in the header.

Token Headers
Token Header Field	Description
kid	The ID of the key used to digitally sign the JWT.
alg	Algorithm used to sign the token header.
v-c-merchant-id	Merchant ID used in the request transaction. To obtain the merchant ID, see Sign Up for a Sandbox Account.

Token Header

    eyJ2LWMtbWVyY2hhbnQtaWQiOiJtZXJjaGFudElEIiwiYWxnIjoiUlMyNTYiLCJraWQiOiI3MDc4NjMzMjg1MjUwMTc3MDQxNDk5In0

Generating the Token Header with Python

Encode the header data and then remove any padding added during the encryption process.

    import base64

# open file in binary mode
data = b'{"v-c-merchant-id":"merchantID","alg":"RS256","kid":"7078633285250177041499"}'
encoded = base64.urlsafe_b64encode(data)
stripped = encoded.decode('ascii').strip('=')

print(stripped)

Generate a Hash of the Claim Set

Generate a Base64-encoded SHA-256 hash of these header fields:

Headers
Header Field	Description
iat	The date and time of the message origin. Date formatting is defined by RFC 7231, Section 7.1.1.1.
digest	A Base64 encoded hash of the message payload. The digest field is not included in a GET request.
digestAlgorithm	The algorithm used to hash the message payload. The message payload should be hashed using the SHA-256 algorithm. The digestAlgorithm field is not included in a GET request.

Follow these steps to generate the hash:

Generate the SHA-256 hash of the fields in JSON format.

Encode the hashed string to Base64.

Add the message body hash to the

digest

header field.

Creating a Message Hash Using Command Line Tools

Generate the SHA-256 hash using the

shasum

tool.

        echo -n "{"iat":"Thur, 15 June 2017 08:12:31 GMT","digest":"tP7hDajF4f6q0ysBQCHgef5K/PBq8iMASvlEARp8tl=",
					"digestAlgorithm":"SHA-256"}" | shasum -a 256

Base64 Encoding a Message Hash Using Command Line Tools

Generate the SHA-256 hash using the

base64

tool.

        echo -n "5995a4f27b4b9256a94cf54489a9ef691d8dc8a590d322780d3b202cfa2f078f" | base64

Add the message body hash to the

digest

header field

    NTk5NWE0ZjI3YjRiOTI1NmE5NGNmNTQ0ODlhOWVmNjkxZDhkYzhhNTkwZDMyMjc4MGQzYjIwMmNmYTJmMDc4Zg==

Generate a Hash of the Token Header

Generate a Base64-encoded SHA-256 hash of these header fields:

Token Headers
Token Header Field	Description
kid	The ID of the key used to digitally sign the JWT.
alg	Algorithm used to sign the token header.
v-c-merchant-id	Merchant ID used in the request transaction.

Follow these steps to generate the hash:

Generate the SHA-256 hash of the fields in JSON format.

Encode the hashed string to Base64.

Create a Message Hash Using the

shasum

Command Line Tool

        echo -n "{"kid":"cc34c0a0-bd5a-4a3c-a50d-a2a7db7643df",
"alg":"RS256","v-c-merchant-id":"merchant_id"}"
| shasum -a 256

Create a Message Hash Using the

base64

Command Line Tool

        echo -n "a9953cdca19433ae5ec1c4eb0dafd41df6de4d20cd47cbace3c316a1ac6d2008" | base64

Example: Token Header Hash

    NTc3N2RlOTAyZWEwNWU0NWM2YTBkNTI4Mjg0YTJmOTVlZGYxYWJlMzBjNzk5OTg1YzEzMjNiMDkzMzc0MWEwNA==

Generate the Message Body

Encode the message body (payload) using URL safe Base64 encryption. At a minimum, the body should include these fields:

Message Body Fields
Message Body Field	Description
digest	A base64 encoded SHA-256 has of the claim set.
digestAlgorithm	Algorithm used to sign the JWT.
iat	Time the JWT was issued.

Follow these steps to generate the hash:

Generate the SHA-256 hash of the JSON payload (body of the message).

Encode the hashed string to Base64.

Add the message body hash to the

digest

header field.

Add the hash algorithm used to the

digestAlgorithm

header field.

Encrypted Message Body

Line break added for readability.

    digest: eyJkaWdlc3QiOiJSQk52bzFXelo0b1JScTBXOStoa25wVDdUOElmNTM2REVNQmc5aHlxLzRvPSIsImRpZ
2VzdEFsZ29yaXRobSI6IlNIQS0yNTYiLCJpYXQiOiIyMDI0LTA0LTA1VDE2OjI1OjE4LjI1OVoifQ

Encrypting Message Body Using Python

Generate the SHA-256 hash using the

shasum

tool. Line break on line three added for readability.

    import base64

data = b'{"digest":"RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=","digestAlgorithm":"SHA-256",
    "iat":"2024-04-05T16:25:18.259Z"}'
encode = base64.urlsafe_b64encode(data)
stripped = encode.decode('ascii').strip('=')

print(stripped)

Generate a Token Signature

You can now build the JSON token signature. The token signature is made up of the JWT header and claim set hashes in the following format, and encrypted with the private key.

[Token Header].[Claim Set]

Follow these steps to generate the signature:

Concatenate the header and claim set hash strings with a period (.) separating the hashes:

[Token Header].[Claim Set]

Generate an encoded version of the text file using your private key.

Base64 encode the signature output.

Example: Token Signature Hash

    YjgwNGIxOTMxMzQ2NzhlYjdiMDdhMWZmYjZiYzUzNzliMTk5NzFmNjAzNWRmMThlNzk0N2NhY2U0YTEwNzYyYQ

Code Example: Encoding the Signature File Using OpenSSL

Encode the signature file using the

openssl

tool.

      openssl rsautl -encrypt -inkey publickey.key -pubin -in [signature-text-file]
					> [signature-encoded-file]

Code Example: Base64 Encoding the Signature File Using the Command Line

Encode the signature file using the

openssl

tool and remove any padding.

      base64 -i [signature-encoded-file]

Generate a JSON Web Token

You can now build the JWT. The JWT is made up of the token header Base64 encoded hash, the payload Base64 encoded hash, and the JWT signature in the following format:

[Token Header].[Payload].[Signature]

To generate the JWT, concatenate the header, payload, and signature strings with a period (.) separating the hashes:

[[Token Header].[Payload].[Signature]

Example: JSON Web Token

    eyJ2LWMtbWVyY2hhbnQtaWQiOiJtZXJjaGFudElEIiwiYWxnIjoiUlMyNTYiLCJraWQiOiI3M
Dc4NjMzMjg1MjUwMTc3MDQxNDk5In0.eyJkaWdlc3QiOiJSQk52bzFXelo0b1JScTBXOStoa2
5wVDdUOElmNTM2REVNQmc5aHlxLzRvPSIsImRpZ2VzdEFsZ29yaXRobSI6IlNIQS0yNTYiLCJ
pYXQiOiIyMDI0LTA0LTA1VDE2OjI1OjE4LjI1OVoifQ.YjgwNGIxOTMxMzQ2NzhlYjdiMDdhM
WZmYjZiYzUzNzliMTk5NzFmNjAzNWRmMThlNzk0N2NhY2U0YTEwNzYyYQ