Transcend Documentation

The following guide outlines how to create an endpoints on your authentication server to support JWT account login.

Sign users into the Privacy Center using JWTs.

We recommend setting up a redirect URL on your server that checks a user's authentication, then redirects the user to the Privacy Center with a JWT on the URL fragment.

If you haven't read about "identifiers" yet, we recommend reading this doc first.

Here's the flow:

The end-user is sent to a route on your site, (for example, https://api.{{yourOrganizationDomain}}/privacy-center-redirect).
Check their session:
- If they are not logged in, redirect them to your login page, ideally in a way where they will return to this route after a successful login attempt.
- If they are logged in, first generate a JWT on your backend containing information about their session:

const jwt = require('jsonwebtoken');

const token = jwt.sign(
  {
    /**
     * This can be the email (if globally unique) or the user ID of the
     * data subject in your user table.
     */
    coreIdentifier: 'benfarrell',

    /**
     * The main email address for the data subject.
     * Used to query data and to communicate with the data subject.
     */
    email: 'benfarrell@gmail.com',

    /**
     * Whether the email is already verified as belonging to the data subject.
     *
     * When set to false, Transcend will verify the email using a magic link,
     * so long as Transcend email verification is turned on for your organization.
     *
     * Email verification can be configured on the Request Identifier Settings
     * (https://app.transcend.io/privacy-requests/identifiers).
     *
     * If you want Transcend to always perform email verification as a second
     * factor of auth, leave this as always false.
     */
    emailIsVerified: true, // defaults to false

    /**
     * OPTIONAL - Additional identifiers that your server is attesting to.
     * Each of these identifiers can be used to look up data in the data
     * systems on your data-map. Setting this is similar to the Identity
     * Enrichment step.
     *
     * It is extremely important that you have verified that these identifiers
     * belong to the data subject with this coreIdentifier and email.
     */
    attestedExtraIdentifiers: {
      custom: [{ name: 'deviceId', value: '123' }],
    },

    /**
     * OPTIONAL - Additional metadata about the data subject, to be displayed
     * on the Privacy Center. Be sure to match these supported keys.
     */
    profile: {
      nickname: 'Ben',
      picture: 'https://example.com/images/benfarrell', // profile avatar
    },
  },
  SIGNING_PRIVATE_KEY, // more on this in "Generate a keypair" below
  {
    algorithm: 'ES384', // required
    expiresIn: 1000 * 60 * 15, // expires in 15 minutes
    // You can find your sombra audience at https://app.transcend.io/infrastructure/sombra/sombras
    audience: yourOrganizationURI, // required
  }
);

Lastly, redirect (HTTP status code 302 or 303) the authenticated user to your Privacy Center at the /login route, and include the JWT after a # fragment:

https://privacy.{{yourOrganizationDomain}}/login#eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 ...

That way, users who are logged in and click on the privacy policy link will arrive in the Privacy Center with an already-authenticated session.

To protect your private key, the JWT has to be signed server-side, but the signed token can be sent to the frontend.

Transcend expects your JWT to be signed using the ES384 algorithm. A keypair can be generated using the following script.

PRIVATE_FILE="./jwtES384-private-key.key"
PUBLIC_FILE="./jwtES384.key.pub"

openssl ecparam -name secp384r1 -genkey -noout -out "$PRIVATE_FILE"
openssl ec -in "$PRIVATE_FILE" -pubout -out "$PUBLIC_FILE"

You can set your public key in the Data Subject settings on the Admin Dashboard.

JSON Web Tokens (JWTs)

Tip: render the "privacy" link on your footer to go to this redirect route, instead of privacy.yourOrganizationDomain

Generate a keypair