JWT bearer tokens and mutual TLS in Workday Orchestrate: credential store setup for both

Both live in the tenant's credential store, not in the app

Orchestrate handles certificate-based security through credential stores in the Workday tenant, so private keys never sit in the orchestration's source. For mutual TLS, you upload a keystore (and optionally a truststore) with the Create Integration CredStore task and select it as a Mutual Auth configuration on Send HTTP Request. For a JWT bearer OAuth grant, the Create External Client CredStore task has an OAuth 2.0 Jwt Bearer auth scheme that signs the assertion with an X.509 private key pair held in the tenant.

They solve different problems and a provider can require both: mutual TLS proves the client at the connection level, and a JWT bearer grant proves it to the provider's OAuth server to get an access token.

Mutual TLS: choose the token type

The Integration Credstore token type depends on what the server requires. From Workday's Keystores and Truststores reference:

BCFKS_ versions of all three exist for environments that must be FIPS-compliant; Workday notes they are available only there.

Two details in the reference are easy to miss. The keystore must contain exactly one PrivateKeyEntry, so check a keystore exported from a store that holds several client certificates before you upload it. And for JKS_KEYSTORE_TRUSTSTORE, the order inside the ZIP is critical: keystore first, truststore second.

Build the token data

The Token Data field takes the ZIP file, base64-encoded. With standard tools, starting from a PKCS#12 file the partner or your PKI issued:

keytool -importkeystore -srckeystore client.p12 -srcstoretype PKCS12 \
  -destkeystore client-keystore.jks -deststoretype JKS
keytool -list -keystore client-keystore.jks
zip credential.zip client-keystore.jks custom-truststore.jks
openssl base64 -A -in credential.zip -out credential.b64

keytool -list should show one entry of type PrivateKeyEntry. zip adds files in the order you list them, which gives you keystore-then-truststore. Leave out the truststore for JKS_KEYSTORE.

Create the Integration Credstore

Run Create Integration CredStore in the tenant and complete:

• App ID: the Application Reference of the app that will use it (for example myextendapp2_weqef in Workday's example). One Integration Credstore maps to exactly one application.
• External Reference ID: the ID the orchestration will refer to, for example partnerBankMtls.
• Functional Feature Service Mapping: Workday Orchestrate.
• Token Type: from the table above.
• Token Data: the base64 text.
• Keystore Password: mandatory for the mutual TLS types, encrypted at rest. Truststore Password when you include a truststore.
• Expiration Time (optional): ISO 8601. Set it to the certificate's expiry so the store records when it stops being valid.

Attach it to Send HTTP Request

In Orchestration Builder, open the orchestration's Settings, choose Mutual Auth, give the configuration a Name, and either click Connect to a Tenant to import the credential or type the External Reference ID. Optionally set the Token Type and a description, then Create.

You then have two ways to apply it. On the Integration Credstore tab of Settings you can make it the default for every Send HTTP Request in the orchestration, or you can select it from the Authentication list on the Auth tab of an individual step. Use the per-step choice when only one endpoint needs a client certificate.

Send HTTP Request negotiates TLS 1.3 and falls back to TLS 1.2 if the endpoint does not support 1.3. Mutual TLS applies to Send HTTP Request, the component for external URLs; Workday's own APIs go through Send Workday API Request.

JWT bearer OAuth through the External Client CredStore

Some APIs issue access tokens only in exchange for a JWT signed with your private key (the JWT bearer grant). Workday documents this with the Create External Client CredStore task and the OAuth 2.0 Jwt Bearer value of Auth Scheme for External Client. Workday's setup for its IRS IRIS integration shows the fields involved:

• Client ID and Client Secret from the provider registration.
• Subject, Issuer and Audience: the sub, iss and aud claims the provider expects. In the IRIS setup the audience is the provider's token URL.
• Jwt Bearer Signature Algorithm: for example RS256.
• X509 Private Key Pair: a key pair created in the tenant with the Create 3rd Party X.509 Key Pair task, so the private key stays in Workday and you register the public side with the provider.
• JWT Header KID: the key ID the provider uses to pick your public key.
• Token Endpoint and Authorization Endpoint: as your provider's registration requires. (The IRIS setup leaves both blank.)

In the orchestration, reference the store the same way as any OAuth credential: Settings > Credentials, type OAuth, Cred Store Reference, with the store's External Reference ID, then select the credential on the Send HTTP Request step. The OAuth and refresh tokens guide walks through that part.

Workday's orchestration credential pages describe the Cred Store Reference option in general terms and do not single out the JWT bearer scheme, so make the first sandbox run your proof that the provider accepts the token before you build the rest of the flow on it.

Signing in the expression language: possible, but not the first choice

The String type has SHA256withRSASign(keystore, alias, password), which returns a base64 signature of the string, and SHA256withRSAVerify(signature, keystore, alias, password). In principle you could assemble a JWT header and claims, base64url-encode them and sign them yourself. Both functions take the keystore as Data and its password as an argument, so the orchestration would have to hold the private key material and password itself, which is exactly what the credential stores exist to avoid. Use the External Client CredStore unless the provider's scheme cannot be expressed there, and treat a hand-signed JWT as a last resort that needs a security review.

For AWS services, neither applies: use the separate AWSv4 credential type (Create AWS Signature v4 Credentials).

Prove the connection, then plan the expiry

1. Run the orchestration in a sandbox against the partner's test endpoint and confirm the response code on the Send HTTP Request step. Give the step a retry policy with a success range so a handshake or 401 failure fails the run rather than passing silently (HTTP retries and polling explains why that is needed).
2. If the handshake fails, check in this order: the right token type for what the server asks; exactly one PrivateKeyEntry; keystore before truststore in the ZIP; the keystore password; and whether the server's CA needs a truststore.
3. Ask the partner to confirm from their side which client certificate subject they saw.

Certificates expire on a date you already know. Record it in the store's Expiration Time and schedule the renewal with the partner. A safe approach is to load the new keystore under a new store while the old one still works; pointing the Mutual Auth configuration at the new External Reference ID is then an app change, so make it and test it in the sandbox before the old certificate lapses.