# JWT Direct Linking

Direct linking is the feature that allows a Workato Embedded partner to link their platform to a secure resource within a Workato account. This is especially relevant when Workato pages are embedded by IFrame on the partner’s platform.

A Workato session for the user is created before providing access to the secure resource. The access is granted using a JWT token generated using RS256 algorithm using an asymmetric key pair.

# Account structure

Typically the account structure for Workato Embedded partners and their customers will be as follows: Workato Embedded team structure Workato Embedded account hierarchy

# Required information

Information Required Source
RSA public key Yes Partner will provide the public key used to sign the JWT token to Workato. See Generate JWT keys for more details.
Workato Embedded vendor API Key Yes Please contact Workato when beginning the implementation of direct linking. Workato will provide the vendor API key securely.
Customer team account ID Yes This is the Workato user ID or external ID for every customer account created. If created using managed_users API, it is returned as the output.
If using UI to create the account,
  • The ID of the customer is in the URL when you click on it OR
  • Can be obtained when in the customer account in the data tree in any recipe (User ID)
If the external id is passed, it should be prefixed with an E (eg: EA2300) and the resulting id should be URL encoded.
I.e. If the external id is AM10:XV303 the url encoded value will be EAM10%3AXV303.
Customer user ID No This is the Workato user ID for a user within the customer team. Usually, this account belongs to:
  • An individual within the customer organization OR
  • The representative assigned by the partner to manage the customer account.
If created using managed_users API, it is returned as the output.

If using UI to create the user,
  • The ID of the customer can be obtained when in the customer account in the data tree in any recipe (User ID)
Paths to Workato assets Yes The paths to Workato pages the partner wishes to link to.
E.g. If trying to link to community recipes, the Workato URL is: https://www.workato.com/browse/recipes (opens new window).
Paths include all the parameters and fragments that append https://www.workato.com/ (opens new window).

# Workato Embedded partner implementation

A direct link URL generation micro service should be added to the vendor's server (https://www.vendor.com/integrate_direct_link (opens new window))

  • The endpoint should require vendor authentication.
  • This service should accept the path to the workato asset
  • The service should generate a url as follows:
    'https://www.workato.com/direct_link/' + path + '?' + query_params + '#' + fragment
    
  • The service should generate the JWT token as follows:
    • Header section
      • The typ claim should be set to JWT
      • The alg claim should be set RS256
    • Payload section
      • The sub claim should be set to
      <WORKATO_EMBEDDED_VENDOR_API_KEY>:<CUSTOMER_TEAM_ID>:<CUSTOMER_USER_ID>
      
      • The iat claim should be set to the current time in epoch
      • The jti claim should be set to a globally unique value. The value should be used only once in a 10 minute duration.
      • The origin claim is optional. It is required when two or more origins are provided at the customer or vendor level. The provided origin will be saved into the session object and will be used for the lifetime of the session.
    • Sign using the private key using RS256 algorithm (this should be the private key to the public key previously provided to Workato)
  • The service should redirect to the new url with parameter workato_dl_token set to the JWT token.

Use the direct link url to refer to any Workato asset in the vendor HTML page. Vendor should never expose JWT token in any HTML page.

Example:

<html>
<head></head>
<body>
  <p>
    <a href='https://www.vendor.com/integrate_direct_link/recipes/1' target=_blank>
      Salesforce to Vendor lead sync
    </a>
  </p>
</body>
</html>

# Generate JWT keys

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

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

# Converting keys to PEM format

You may need to convert your keys from other formats before sending it to Workato if you used a different approach to generate them.

To convert from an SSH public key:

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

# Errors

The following is a list of errors you may face upon implementing JWT direct linking and the ways to resolve them.

Category Error Description Course of action
HTTP request http_request_invalid The request sent to our servers do not meet one of the following conditions:
- Is a valid HTTP request
- In HTML format
- Not in XHR format
Ensure that the request sent meets the conditions specified
path_invalid The path provided must be valid and secured with HTTPS Ensure the URL/path is valid and begins with "https://"
JWT header/payload token_missing The JWT is not present Check that the JWT is present in the request
token_invalid A properly structured JWT should contain a header, payload and signature in the following format:
header.payload.signature. This error suggests that one of the components is missing/incorrectly formatted.
Check that the JWT has been correctly formatted
token_signature_invalid The signature (private key) used to sign the JWT is invalid Check that the signature used to sign the JWT is properly formatted/configured
alg_invalid The signing algorithm used in the header of the JWT is not RS256. Check that the 'alg' claim in the header has the value "RS256"
sub_missing The 'sub' (Subject) claim in the payload is not present Check that the 'sub' claim in the payload is present
sub_invalid The 'sub' (Subject) claim in the payload is not a string Check that the 'sub' claim in the payload is a string.
iat_missing The 'iat' (Issued at) claim in the payload is not present Check that the 'iat' claim in the payload is present
iat_invalid The 'iat' (Issued at) claim in the payload is not an integer Check that the 'iat' claim in the payload is an integer
token_expired The 'iat' (Issued at) claim in the payload has a value that is ±30s from the current time Check that the 'iat' claim provides a valid value based on the current time
jti_missing The 'jti' (JWT ID) claim is not present Check that the 'jti' claim in the payload is present
jti_invalid The 'jti' (JWT ID) claim is not a string or an integer Check that the 'jti' claim in the payload is either a string or an integer
jti_reused The 'jti' (JWT ID) claim has been used before Use a globally unique 'jti' claim value. The value should be used only once in a 10 minute duration.
Account related team_missing The user within the customer team trying to access Workato does not belong to any team Check that the member within the customer team trying to access Workato has been added to the customer team correctly
team_not_allowed The user is trying to login to the Workato Embedded partner's admin account. This is not allowed. Change the ID of the account to a customer account ID
team_direct_team_link_disabled The customer's team account has not been properly set up Please contact your Workato representative for help in resolving this error
member_invalid The user that is trying to access the team is not a valid member of the team Check that the member within the customer team trying to access Workato has been added to the customer team correctly
team_unconfirmed The team account has not been confirmed The customer team's email requires confirmation. If not possible, please contact your Workato representative for help in resolving this error
member_unconfirmed The team member's account has not been confirmed The customer team member's email requires confirmation. If not possible, please contact your Workato representative for help in resolving this error
team_saml_required The team the user is trying to access has SAML SSO enabled. They must be enabled with SAML SSO and login through the SAML IdP. Contact a team admin to ensure this user is SAML SSO enabled and that they have access to login through the SAML IdP.
vendor_missing The Workato Embedded partner's account has not been properly set up Please contact your Workato representative for help in resolving this error
vendor_direct_team_link_disabled The Workato Embedded partner's account has not been properly configured Please contact your Workato representative for help in resolving this error
vendor_admin_missing The Workato Embedded partner's account has not been properly configured Please contact your Workato representative for help in resolving this error
vendor_key_missing The Workato Embedded partner's account has not been assigned a unique key Please contact your Workato representative for help in resolving this error