# JWT direct linking

JSON Web Token (JWT) is an open standard that defines a compact and self-contained method for securely transmitting information between two parties as a JSON object. JWTs are signed with private/public key pairs, which verify the integrity of the token and add an additional layer of security.

JSON Web Tokens authenticate users and provide verified access to applications and resources. Generate a JWT before implementing any Workato Embedding models.

JWT direct linking consists of the following steps:

Generate a public/private key pair
Install a direct link URL microservice
Generate a JWT

# Prerequisites

The following information is required to implement JWT direct linking.

Private and public key pair: Required.The JWT token must be signed using a private key generated with the RS256 algorithm. Workato uses the public key to verify the generated JWT tokens. Use the Update JWT signing key API to set the public key or provide the public key to your Workato Success Representative.
Embedded vendor ID: Required.The Embedded vendor ID is required to generate the JWT. Use the vendor ID returned by Update JWT signing key API or ask your Workato Success Representative to provide the value for this ID after you provide your public key.
Customer team ID: Required. The customer team ID is the unique ID of the Embedded customer. From the UI, obtain the customer team ID by navigating to the Admin console and selecting the specific customer. When selected, the customer team ID is present in the URL. Alternatively, fetch the customer team ID by calling our get customer API.
If the external id is used instead of the Workato id, the segment should start with the prefix E.
Customer user ID: Optional. The customer user ID is the unique ID of an individual workspace member in the customer workspace. Include the customer user ID when the user's specific role must apply to the Workato session created. Fetch the customer user ID by calling our get customer workspace member API.
If the external ID is used instead of the Workato ID, the segment should start with the prefix E.
Origin URL: Required. The origin URL is the default domain where you embed the Workato iframe. In specific cases, you must include the origin URL in the payload of the JWT. Provide your Workato Success Representative with the origin URL.

# Step 1: Generate a private and public key pair

# Generate a private key

To generate the private key from scratch, use the following:

$ openssl genrsa -out private.key 2048
$ cat private.key
-----BEGIN RSA PRIVATE KEY-----

...

-----END RSA PRIVATE KEY-----

# Generate a public key

Then, extract the public key using the following:

$ openssl rsa -in private.key -pubout -out public.key
$ cat public.key
-----BEGIN PUBLIC KEY-----

...

-----END PUBLIC KEY-----

# Convert keys to PEM format

If you used a different method to generate your public/private key pair, convert your keys to PEM format before sending them to Workato.

To convert from an SSH public key:

$ ssh-keygen -f key.pkcs -e -m pem > key.pem

# Step 2: Install a direct link URL generation microservice

The purpose of the direct link URL microservice is to automatically generate a JWT when needed to facilitate access to secure resources. Install a direct link URL microservice to your server.

The microservice must meet the following specifications:

The endpoint must require vendor authentication.
The microservice must accept the path to the Workato asset.
The microservice must generate a URL with the following structure:

https://app.workato.com/direct_link/<resource_path>?<query_params>#<fragment>

# Example microservice:

import nanoid from 'nanoid';
import {sign} from 'jsonwebtoken';

function getToken(WorkatoEmbeddedVendorId, customerAccountId, privateKey) {
  return sign({
    sub: `${WorkatoEmbeddedVendorId}:${customerAccountId}`,
    jti: nanoid()
  },
  privateKey,
  {
    algorithm: 'RS256'
  });
}

# Step 3: JWT direct linking

# JWT structure

A JWT consists of a header, payload, and signature. In their compact form, JWT sections are separated by ..

header.payload.signature

Header: The first part of the token is the header. The header usually consists of two parts: the type of token and the type of algorithm used to generate the signature.
Payload: The second part of the token is the payload, which contains the claims. Claims are statements about the user and additional data.
Signature: The final part of the token is the signature. Signatures verify the integrity of the claims.

# Direct link URL

You must generate a JWT token on your server and construct the direct link URL. The direct link URL format differs depending on the CX option you plan to implement.

Embedded connection widget

The direct link URL format for the Embedded connection widget should match the following examples:

Workato accounts hosted in the US Data Center

https://app.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

Workato accounts hosted in the Europe Data Center

https://app.eu.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

Workato accounts hosted in the Singapore Data Center

https://app.sg.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

Workato accounts hosted in the Japan Data Center

https://app.jp.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

Workato accounts hosted in the Australia Data Center

https://app.au.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

Fully Embedded

The direct link URL format for Fully Embedded should match the following examples:

Workato accounts hosted in the US Data Center

https://app.workato.com/direct_link?workato_dl_path=<workato_path>&workato_
dl_token=<jwt_token>

Workato accounts hosted in the Europe Data Center

https://app.eu.workato.com/direct_link?workato_dl_path=<workato_path>&workat
o_dl_token=<jwt_token>

Workato accounts hosted in the Singapore Data Center

https://app.sg.workato.com/direct_link?workato_dl_path=<workato_path>&workat
o_dl_token=<jwt_token>

Workato accounts hosted in the Japan Data Center

https://app.jp.workato.com/direct_link?workato_dl_path=<workato_path>&workat
o_dl_token=<jwt_token>

Workato accounts hosted in the Australia Data Center

https://app.au.workato.com/direct_link?workato_dl_path=<workato_path>&workat
o_dl_token=<jwt_token>

White-label SSO

The direct link URL format for White-label SSO should match the following examples:

Workato accounts hosted in the US Data Center

https://app.workato.com/direct_link/recipes?workato_dl_token=<jwt_token>

Workato accounts hosted in the Europe Data Center

https://app.eu.workato.com/direct_link/recipes?workato_dl_token=<jwt_token>

Workato accounts hosted in the Singapore Data Center

https://app.sg.workato.com/direct_link/recipes?workato_dl_token=<jwt_token>

Workato accounts hosted in the Japan Data Center

https://app.jp.workato.com/direct_link/recipes?workato_dl_token=<jwt_token>

Workato accounts hosted in the Australia Data Center

https://app.au.workato.com/direct_link/recipes?workato_dl_token=<jwt_token>

# Generate a JWT

Generating a JWT consists of the following steps:

Configure the header
Configure the payload
Sign the token

Step 1: Configure the header

alg: Set the alg claim to RS256, the algorithm used to generate the signature.
typ: Set the typ claim to JWT, the type of token used.

Example:

{
  "alg": "RS256",
  "typ": "JWT"
}

Step 2: Configure the payload

sub: Set the sub claim to:

<workato_embedded_vendor_id>:<customer_team_id>:<customer_user_id>

::: tip PREREQUISITES

Visit the Prerequisites section for detailed instructions on obtaining the Embedded vendor ID, customer team ID, and customer user ID.

:::

iat: Set the iat claim to the current time in epoch.
jti: Set the jti claim to a globally unique value. Use the value only one time in a 10-minute duration.
origin: The origin claim is required when the connection iframe is embedded in two or more origins.

MULTIPLE ORIGINS

If you are embedding the Connection Widget in multiple domains, you must configure the origin URL in each customer workspace. To override the origin URL in an individual account, go to the Admin console > manage customers, and access the relevant customer workspace. Access the settings menu and update the origin URL.

Example:

{
  "sub": "911672h4203fae7ffbe2eca1bbcaa79cc8c47af5377a6c6240:303363:313646",
  "iat":"1624043461",
  "jti": "3oay2t2kntGbxr1yhSINn",
  "origin": "http://www.acme.com"
}

See more JWT microservice examples. (opens new window)

Step 3: Sign the JWT

Sign the JWT with your private key generated with the RS256 algorithm in Step 1. The private key must match the public key previously provided to Workato.

Last updated: 4/25/2024, 5:58:27 PM