JSON Web Token

For additional security, API consumers can make use of JSON Web Tokens (JWT). This is a standard RFC 7159 (opens new window) for web authentication. JWT tokens are signed using a secret or key selected by the manager of the access profile.

JWT tokens are used by identity providers (for example Okta, OneLogin, Auth0) that authenticate users and provide verified access to business applications. Also known as Single-Sign On, identity providers streamline access to applications through a central authentication mechanism.

Also, JWT tokens can be signed to verify that the token is legitimate. This allows the recipient to validate that the contents have not been modified by anyone else, adding another layer of security.

This document will cover:

1. Workato supported JWT Signing methods
2. How to generate a JWT token
3. Calling a Workato API endpoint with JWT
4. Accessing JWT payload claims

Supported signing methods

Workato supports two signing methods:

Signing method	Description
HMAC	HMAC uses a symmetric shared secret (client and server have the same secret). This uses a 256-bit secret value.
RSA	RSA uses an asymmetric key pair (client has a private key and shares the public key with the server).

HMAC signing method

If you select HMAC, you will see the following fields in the Access Profile screen:

JWT Token Configuration HMAC authentication

How to generate a HMAC secret

The shared secret can be any value that you select, but for best security, it should be a long value generated by a secure random number generator. If you have OpenSSL, you can generate such a secret with the command:

openssl rand -base64 32

Paste the secret value into the JWT HMAC secret field.

RSA signing method

If you select RSA, you will see the following fields in the Access Profile screen:

JWT Token Configuration RSA authentication

How to generate a RSA public/private key pair

To configure a RSA authentication, you must have an RSA public key/certificate and a corresponding RSA private key. One way to generate this is by using OpenSSH:

$ ssh-keygen -t rsa

This will generate two files, one for the private key (no extension) and one for the public key (.pub extension). A typical public key file might look like this:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC4O6vRGXTkXWQ4yjj6baC7xAlrJPagWQ1WgI7RBUfk5PRPyD88Lp1vqe0CqshOIEeIVca3mD+W0YtJGlu4IaFh2gIC0W2lQY+3yXkzw2IQvnK1jjzxLJ6Dho7Vh3kLVqlmDB0ABdFhoU+vZf19AnLMqGhmu81xXoutK89MJAfvGFWbZ/zfM/yl9aqTOVrEJFpUxloL2IY/EAiUqblRTH5KWtimetEPF8VG3hu/YeU/5/CzPGZaLKUOcO3k0A6a6iIA2ruV180QN0FmgrCUsQ6oA6vWZsY1LuJm3bnLv7KJApR+WYqp7OCMlhk67N7zxkbZqNb2+eyUCx7E2SFCjFkR jdart@bear

Extract and convert the public key into PEM encoded PKCS8 format.

$ ssh-keygen -f id_rsa.pub -e -m pkcs8

-----BEGIN PUBLIC KEY-----
MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA5Km1rCwq8kYq/hbw14Se
bc7Y+2/0DRt+GmCGOdqAZoYm0CknVwvTzzlDrAlMcSdb3kQNHf2eJc+tJ8+krhOI
jKVhr4+RXEJ2tL+dvlB+BwrhVV2MmmYY1YtHyJvb+lhWPvevq5PsJ2U0uNtLyvuv
wOucUzofi2N8iSelpNcYgga0TTXb41KxLUVRoFVEFUl10iUL8JWbK1WOiCAncUwi
T5gg6c+M+g65+DILnCN7cFJ50CFVLET4WQLN8gMkMR5/buXkA35YGKZLUtm299Ju
H1Hx+DrJ+U9tm+3lRsYX+208sn+9IFzdVqQLnNPP5GFzM8m3k5bVxn2d9I+Isq2C
7X5crDcGWAdjp0OE+iMISa9yMeEVj8WgEeC8hHe9LDzPd0D3+kHHtKV4ETCjI15C
kmYiDzGvxPuKGBSZdeMOC3xSx5cDtPc7KIJKohtOn7nbTh/5cXAtlyes4iYibX20
IF04bOOp+QaTUZUIfv/ZkBbQmgbd16nJLjHBR9X5wRudAgMBAAE=
-----END PUBLIC KEY-----

Finally, this PEM encoded public key needs to be pasted into the Public Key field in the Access Profile screen.

How to generate JWT Tokens

A JWT token can encapsulate several pieces of information that the API requester communicates to the server. For Workato, what is essential is the Workato access key. It should be placed in the JWT header like this:

{
  "alg": "HS256",
  "kid": "d4aee74e131926682043395edecaf377765fae48e56e232cb295af475b314545"
}

Alternative claims

Here, the Workato access key is included in the header as the kid claim. Some identity providers may restrict the kid claim. If this is the case, you can include the access key in the payload section of the token, under one of the following claims: https://www.workato.com/sub, workato_sub or sub.

Learn more about alternative claims here.

The JWT token is a signed representation of the JSON structure. You can generate a JWT token using the tools at JWT.IO (opens new window).

With JWT, the API requester is responsible for generating and packaging a token in the correct format. An online tool is available at JWT.IO (opens new window) to facilitate this. The JSON format text mentioned above should be pasted or typed into the payload field on the Decoded side of the tool. In addition, they will paste in the private key (RSA) or secret string (HMAC) in the Verify Signature section. The signed and encoded key then appears on the left-hand side in the Encoded section.

The two standard algorithms Workato supports are HS256 (aka HMAC) and RS256 (aka RSA).

For example, generation of an HMAC JWT might look like this:

JWT Generation

Similarly, an identity provider will be able to issue JWT token with the API key embedded in the corresponding JWT claim. See here for more information on JWT Workato claim.

Calling an API endpoint with JWT

The encoded and signed token is passed to the Workato API in the header (see Calling APIs). The access token is sent in the Authorization header with the Bearer authentication scheme.

1. The example below shows how the token is used in Postman: Example of a JWT token used in Postman

2. The example below shows how the token is used in a curl request:

   curl -XGET \
   -H 'Authorization: Bearer ayJhbGciOiJIUzI1NakIKjkJFVCJ9.eyJzdWIiOiI4OJSIFMLLdkZTY0ZWZkNDY1MTcyMjk2MDA2ZTlmNDEwNGEzOGJmMDAzZTk0YmYyYzRiMzhjYzg3ZDgwYjU0ODk1IiwibmFtZSI6os9fvaG4gRG9lIn0.D_ZHmYZkbRAFQeL' \
   'https://apim.workato.com/api-endpoints-v1/call?email=john-doe%40acme.com'
   

Extracting JWT payload claims

Identity providers who manage employee identities often load several pieces of information about the subject, for example Email, Employee ID, or assigned Permissions or scopes. They are written in the JWT as payload claims.

Below shows an example of a decoded JWT payload. Here, the sub claim is used to identify the Workato access profile, while the other claims are additional information about the API caller.

{
    "sub": "588dec828cc4fc6f579e5252ca4a3acb3d24527efa588e0329a9490a0d1dc062",
    "name": "John Doe",
    "email": "john@acme.com",
    "acme_id": "A0122152",
    "admin": true
}

Workato will parse the JWT and read all payload claims. Priority will be given to standard claims (opens new window) and claims that are required for Access profile authentication. If the JWT exceeds the character limit, the payload will be truncated and some payload claims may no longer be accessible.

Character limit

The character limit for the encoded JWT payload is 4096 characters. Requests containing JWT token with larger payloads, will fail with the following error:

{
  "error": "JWT payload size exceeded (5358, max 4096)"
}

How to extract JWT payload claims

In the recipe building phase, JWT payload claims are found in the JWT claims datapill.

Steps	Description
1	Switch to Formula mode and parse the JWT claims datapill as a JSON object. For example, use the syntax [JWT Claims]["email"] to extract the email claim. Extract JWT payload claims
2	Payload claims will be automatically parsed at runtime. JWT payload claims parsed at runtime