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 thesignatureheader 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 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 thedigestpayload field.
-
Add the hash algorithm used to thedigestAlgorithmpayload 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 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:
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 thedigestheader 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
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 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 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 thedigestheader field.
-
Add the hash algorithm used to thedigestAlgorithmheader 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