Adding authentication

Prevent non-authenticated responders from accessing your flows.

An out-of-the-box Formsort flow allows anyone to access it.

To restrict the responders who are allowed to complete your flows, it's possible to connect your identity provider, so that you can only permit authenticated users.

We do not currently support authenticated flows outside of the embedding context, although we plan to add support for this in the future.

Today, we support Auth0, and plan to add other providers depending on demand.

Setting up Auth0 authentication

Authentication is configured on a flow-by-flow basis, like other integrations, and can be configured on a per-environment basis.

Unlike the other integrations, the authentication settings take effect immediately for all variants in the flow for the selected environment.

You should see that once an identity provider is configured, you will not be able to access variants within the flow, until you provide a valid ID token.

Passing an ID token to the flow

To identify the responder, you must pass a valid Auth0 ID token JSON Web Token (JWT) into the flow.

First, use the Auth0 client libraries to authenticate your responder within the page that is embedding the Formsort form.

Once your user is authenticated, you can initialize the Formsort embed, and pass an authentication object in your configuration, with the idToken containing the ID token JWT.

  authentication?: {
    idToken?: string; // ID Token for authenticated flows
  };

Make sure you are passing the ID token JWT, not the Access token JWT.

See the web-embed-api documentation for more detail on other settings that can be passed in. Use jwt.io to verify and inspect JWT tokens.

Behind the scenes

An authenticated flow will verify the ID token in the following places:

1. When uploading answers.

2. When downloading answers (for returning responders).

We automatically handle public key rotation, since we use Auth0's JSON Web Key Sets to retrieve the correct public key depending on the key referenced within the ID token itself.

We don't yet verify the ID token when retrieving the flow definition itself. We will add this in the future.

Dealing with authentication errors

The web embed will emit an unauthorized event whenever the embedded flow has an authentication requirement but the idToken is missing or is invalid.

It's important to handle this, since even correctly-formatted tokens are only valid for a limited period of time.

When you receive an unauthorized event, prompt the user to re-authenticate, and re-initialize the embed with the newly-generated ID token.

Authenticating API variable lookups

We do not pass the ID token along with API requests that happen when resolving API variables.

Formsort does, however, include credentials when making API requests from authenticated flow. This means that if you set cookies within the parent page, they will be included with API requests, which you can use to verify users.

Including credentials means that a GET request is no longer considered a simple request, and therefore requires that your server supports the OPTIONS method for Cross-Origin Resource Sharing (CORS). Read more about CORS at MDN.