# JSON Web Token
For additional security, API consumers can make use of JSON Web Tokens (JWT). This is a standard RFC 7159 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:
- Workato supported JWT Signing methods
- How to generate a JWT token
- Calling a Workato API endpoint with JWT
- 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
The 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, the essential information is the Workato access key and the name of the user. These should be placed in a JSON structure similar to the following:
{
"sub": "d4aee74e131926682043395edecaf377765fae48e56e232cb295af475b314545",
"name": "John Doe"
}
Here sub is a claim that denotes the principal subject (or API requester). The sub value is the API key that is obtainable from the Access Profile screen in Workato. Lastly, name is the name of the requester.
Workato namespace claim
Workato will inspect the sub claim to look for a valid API key before accepting the API request. If the sub claim is restricted by the identity provider and you are unable to provide the API key in this claim, you can configure custom Workato claims to store the API key. Learn more here.
The JWT token is a signed representation of the JSON structure. You can generate a JWT token using the tools at JWT.IO.
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 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.
The example below shows how the token is used in Postman:
Example of a JWT token used in PostmanThe 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. 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 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 2048 characters. Requests containing JWT token with larger payloads, will fail with the following error:
{
"error": "JWT payload size exceeded (3358, max 2048)"
}
# 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 automtically parsed at runtime. JWT payload claims parsed at runtime |