Product UpdatesStatus PageAutomation Institute
English
Get a trial
Embedded
Customer experience options
Implementation

# 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:

  1. Generate a public/private key pair
  2. Install a direct link URL microservice
  3. 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 the Update JWT signing key API or obtain it from your Workato Success Representative after providing your public key.

  • Customer team ID

  • Required. The customer team ID uniquely identifies the Embedded customer. Obtain the customer team ID from the UI by navigating to the Admin console and selecting the specific customer. When selected, the customer team ID appears in the URL. Alternatively, fetch the customer team ID by calling our get customer API. If using an external ID instead of the Workato ID, the segment should start with the prefix E.

  • Customer user ID

  • Optional. The customer user ID uniquely identifies 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 being created. You can fetch the customer user ID by calling our get customer workspace member API. Ensure each user is created using the add member to customer workspace API per customer team. If using an external ID 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. Include the origin URL in the JWT payload when the Workato iframe is fully embedded within a partner's application. Additionally, include it when using the Auth Widget with multiple origin URLs allowlisted in the OEM Config. 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.

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. For more information on direct link URLs for other widgets, refer to Constructing a direct link URL.

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>
Branded access SSO

The direct link URL format for Branded access 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:

  1. Configure the header
  2. Configure the payload
  3. Sign the token
1

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"
}
2

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)

3

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.

← Embedding Workato
JWT troubleshooting →


Last updated: 12/2/2024, 6:19:46 PM

On this page