Passing encrypted data to the Forethought widget with JSON Web Tokens

The most common method for inputting data into the Forethought widget is to use widget parameters. However, this option won’t work well for items like security tokens that you want to leverage in API calls downstream or a user ID or email that you want to use for making actions on users’ behalf.

In such cases, Forethought provides the option to pass the necessary data in an encrypted way through JSON Web Tokens (JWT). You can learn more about JWTs from these articles: Introduction to JSON Web Tokens and A Primer on JSON Web Tokens.

By using JWT tokens, you can pass in an encoded payload and decode it using a secret key to populate context variables. You can create as many Context Variables (CV) as you need and generate a JSON payload on your end. The context variable `Display Name` should be used as the keys, while the CV values should be set as the JSON values. 

{
   "Context Variable 1": "some value",
   "First Name": "First",
   "Last Name": "Last"
}

Typical sequence of leveraging JSON Web Token in the product

1. First, encode the JWT token and pass it as a context variable.
2. Before you need to use the decoded data, add the 'Parse JWT' action. You can read more information about actions in this article. Specify the context variable from which the token should be fetched and the values you expect to read from the token. Also, mention the context variables where the values should be stored.
3. Use the Context Variables you got in the rest of the workflow.

Parse JWT action requires the following values to be set:

1. Key:  This value is required to decode the payload. It is often known as a secret key or signing key and is used in both encoding (by the customer) and decoding (by Forethought).
2. Encoded Context Variable:  This is the name of the context variable that contains the encoded content. It's recommended to pass this data via a workflow param context variable.
3. Context Variables to Update:  These are the names of the context variables that you want to extract from the payload.

Demo video of Parse JWT in action

We provide an encoded value as input for illustration purposes only. Normally, this is provided programmatically as a widget parameter.

Lastly, it is important to note that some devolopment work is needed to propagate the encoded user data as a JWT token to the users’ browsers where the widget is loaded. There are a few ways to do this, which will depend on the specific setup. However, the most common method is to perform the encoding on the backend when an authenticated user loads a page with the widget. The encoded token would then be passed as a response header or a cookie. Subsequently, when the widget is initialized on the front end, the token would be read and passed to the Forethought widget. Generally, this should not require more than a few days of development time.