OIC - How to Generate JWT CID Token with SHA256 Hash in Oracle Integration Cloud (OIC)

🔐 How to Generate JWT CID Token with SHA256 Hash in Oracle Integration Cloud (OIC)

🧩 Use Case

As part of secure API integration with HSBC (or any financial institution requiring strict identity/authentication enforcement), the client must send a JWT (JSON Web Token) as a CID (Client Identification Token) in the Authorization header of each API request. This token includes a signed hash (SHA-256) of the payload body to ensure message integrity.

This post walks you through how to:

• Construct the JWT token using base64 encoded header and payload.
• Generate the SHA256 hash of the payload body.
• Sign the token using a private key.
• Assemble and use the CID token in OIC integration.

---

⚙️ Components Used

• OIC JavaScript Action to calculate SHA-256 hash.
• Security Certificates: Private key to sign the JWT.
• REST Adapter: To call target API with proper headers.
• Mapper + Assign: To construct JWT parts and signature.

---

🏗️ JWT Structure

A JWT consists of:

1. Header – defines algorithm & token type.
2. Payload – includes sub, aud, iat, jti, and most importantly, a payload_hash.
3. Signature – created by signing Base64(Header) + "." + Base64(Payload) using private key.

Format:

JWT = BASE64URL(Header) + "." + BASE64URL(Payload) + "." + BASE64URL(Signature)

Sample Signature Input (from screenshots):

ASCII(BASE64URL(Header) + "." + BASE64URL(Payload))

---

🔐 OIC Implementation Steps

1️⃣ Step 1: Generate SHA-256 Hash of Payload

Create a JavaScript action SHA256Generator.js:

function checksum_sha256(inputStr) {
    var sha256_result = oic.checksum.sha256(inputStr, "sha-256");
    return sha256_result;
}

Pass the stringified JSON payload to this function before JWT creation.

Reference:

https://docs.oracle.com/en/cloud/paas/application-integration/integrations-user/import-library-file.html#GUID-D9638CD4-ADCE-4C8A-B5B3-1969086E642E

---

2️⃣ Step 2: Construct JWT Header

Example:

{
  "ver":"1.0",

  "typ": "JWT",

  "alg": "RS256",
  "kid": "CLP"
}

Base64URL encode this JSON string.

---

3️⃣ Step 3: Construct JWT Payload

Example payload:

{
  "sub": "CLP",
  "aud": "EPS",
  "payload_hash_alg": "SHA-256",
  "payload_hash": "<hash from JS function>",
  "iat": 1750411716,
  "jti": "91bee275c-a920-4ef9-ac39-1dbe3f50372d"
}

Use string.replace() in OIC to inject dynamic values like:

• payload_hash – output of JS function
• iat – current epoch time
• jti – UUID (can be generated in integration)

---

4️⃣ Step 4: Sign JWT

Use the Security section of REST connection:

• Upload private key (PKCS#8 format).
• Use a custom signing policy to sign JWT with RS256.

Or use an external custom function to sign:

ASCII(Base64Url(Header) + "." + Base64Url(Payload)) → sign → Base64Url(Signature)

---

5️⃣ Step 5: Construct Final CID Token

Concatenate:

Authorization Header = "JWS " + Header + "." + Payload + "." + Signature

Set this string in the Authorization header of REST Adapter.

---

📋 Required Headers

• Authorization | JWS <CID Token> 
• Accept-Language | en-GB |
• Forwarded-For | <IP Address> 
• X-HSBC-Chnl-CountryCode | HK 
• X-HSBC-Chnl-Group-Member | HBAP
• X-HSBC-Global-Channel-Id | PARTNER
• X-HSBC-Request-Correlation-Id | UUID
• X-HSBC-Client-Id | CLP 
• Content-Type | application/json |

---

✅ Final Output

A complete CID token is structured like:

JWS eyJ2ZX...<Header>.eyJzdW...<Payload>.X1c8Cp...<Signature>

It is passed to the Authorization header like:

Authorization: JWS eyJ2ZX...<Signature>

---

🧪 Testing & Validation

• Use Postman or SoapUI to validate the generated JWT.
• Tools like jwt.io help decode and verify token.
• Ensure OIC has access to private key and correct time sync for iat.

---

📎 Reference

• RFC 7515 - JSON Web Signature (JWS)
• OIC JavaScript Action docs
• HSBC CID token API specification (internal doc: v1.3, Jun 2025)

OIC implementation screenshots:

TBD