Authentication

Sombra provides authentication mechanisms for both administrators and data subjects. This guide covers the configuration of various authentication methods, including OAuth 2.0, JWT Magic Links, and SAML SSO.

Sombra authenticates two types of users:

1. Employees: Administrators and staff using the Admin Dashboard
2. Data Subjects: Your end-users making privacy choices

Sombra supports SAML 2.0 single sign-on (SSO) for authentication of employees at your company who need to sign in to the Admin Dashboard. You can also let Transcend handle the authentication via email and password (not recommended).

The identity verification methods that Sombra allows are controlled via the EMPLOYEE_AUTHENTICATION_METHODS environment variable.

Your options are:

• session,saml: Enable SAML SSO authentication only (recommended).
• session,transcend: Enable Transcend authentication (default). This delegates authorization to Transcend's server, using email/password authentication. We do not recommend keeping this enabled after SAML is set up.
• session,saml,transcend: Enable both authentication methods. This is a good intermediate option when migrating from session,transcend to session,saml. After you've confirmed SAML is configured correctly, we recommend switching to session,saml.

To authenticate employees who need to sign in to the Admin Dashboard and Sombra, you can use SAML single sign-on.

Every Sombra cluster starts with session,transcend. When setting up SAML, we recommend:

1. Setting EMPLOYEE_AUTHENTICATION_METHODS=session,saml,transcend
2. Completing SAML configuration
3. Once SAML is fully functioning (i.e., you can sign in to the Admin Dashboard using SSO), removing Transcend as an authentication method by setting EMPLOYEE_AUTHENTICATION_METHODS=session,saml

To configure SAML authentication, the following values must be set:

• SAML_ENTRYPOINT: The login endpoint where the SAML assertion comes from (e.g., https://sso.yourdomain.com/saml2/idp/ssoService)
• SAML_CERT: The public key to validate the SAML assertion against
• SAML_ISSUER: (optional) The issuer of the SAML certificate (defaults to transcend)
• SAML_AUDIENCE: (optional) The audience of the SAML assertion (defaults to transcend)

For testing purposes:

• ACCEPT_CLOCK_SKEWED_MS: Artificially skew the clock used to validate the expiration on the assertion (in ms)

This authentication configuration is for Sombra. When EMPLOYEE_AUTHENTICATION_METHODS=session,saml, users logging in to the Admin Dashboard without SAML will not have the ability to access Sombra, and thereby will not have access to your customer data. This can be useful if you want to invite third-party vendors into your Transcend organization. You can configure their accounts in the Admin Dashboard to only have permissions to view their own integration. They will never be able to authenticate to Sombra or view any of your customer data—including the customer data they upload.

Configure data subject authentication using the DATA_SUBJECT_AUTHENTICATION_METHODS environment variable:

Configure JWT Magic Link authentication when jwt is included in DATA_SUBJECT_AUTHENTICATION_METHODS.

1. Generate an ES384 key pair using the following command:

# Set output directory
export WRITE_DIR=${WRITE_DIR:-"."}

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

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

# Display encoded keys
echo "JWT_AUTHENTICATION_PUBLIC_KEY:"
< "$PUBLIC_FILE" base64

echo "JWT_AUTHENTICATION_PRIVATE_KEY:"
< "$PRIVATE_FILE" base64

# Clean up
rm "$PRIVATE_FILE"
rm "$PUBLIC_FILE"

2. Configure the environment variables:

• Set JWT_AUTHENTICATION_PUBLIC_KEY in Sombra's environment
• Store JWT_AUTHENTICATION_PRIVATE_KEY in your signing server's environment

Configure OAuth when oauth is included in DATA_SUBJECT_AUTHENTICATION_METHODS. This configuration requires two steps: (A) getting an access token and (B) fetching a user ID and email address.

• OAUTH_CLIENT_ID: The Client ID of your Privacy Center's OAuth 2 application
• OAUTH_CLIENT_SECRET: The Client Secret of your Privacy Center's OAuth 2 application
• OAUTH_GET_TOKEN_URL: The endpoint (e.g., https://api.acme.com/oauth/token) to make an Access Token Request, which resolves an authorization_code to an access_token
• OAUTH_GET_TOKEN_BODY_GRANT_TYPE: (optional) The grant type for this OAuth token
• OAUTH_GET_TOKEN_BODY_REDIRECT_URI: The redirect URI for a successful response from the authorization server
• OAUTH_GET_TOKEN_METHOD: (optional) The HTTP method to use when retrieving the OAuth token. Defaults to POST
• OAUTH_GET_TOKEN_HEADERS: (optional) The headers to use when retrieving the OAuth token
• OAUTH_GET_CORE_ID_DATA_SUBJECT_TYPE: The type of Data Subject that the OAuth configuration refers to. This should use the Data Subject slug, which is the value found in parentheses under DSR Automation -> Request Settings -> Data Subjects

• OAUTH_GET_CORE_ID_URL: The API endpoint to retrieve the core identifier of a user (e.g., https://api.example.com/v1/user-profile). The core identifier is usually a User ID that should be unique to the user and never change.

• OAUTH_GET_CORE_ID_PATH: The JSON path to extract the coreIdentifier (or user ID) from a JSON response body from OAUTH_GET_CORE_ID_URL.

  For example, if the JSON response is:

  JSON

  {
    "data": {
      "user": {
        "id": "123ade451b38283",
        "name": "Ben Farrell",
        "email": "benfarrell@gmail.com",
        "avatar_url": "https://cdn.acme.com/img/ff0d5418-7c65-485c-92d3-b3acd99f51fe.png"
      },
      "activities": [{}]
    }
  }
  

  Then OAUTH_GET_CORE_ID_PATH should be data.user.id.

• OAUTH_GET_CORE_ID_PATH: A path to the coreIdentifier (User ID) to traverse a JSON body (i.e., data.user.id).

• OAUTH_GET_EMAIL_URL: The API endpoint to find the email of a user (e.g., https://api.example.com/v1/user-profile). This is often the same endpoint as OAUTH_GET_CORE_ID_URL.
• OAUTH_GET_EMAIL_PATH: The JSON path to extract the user's email address from a JSON response body from OAUTH_GET_EMAIL_URL. In the example above, this would be data.user.email.
• OAUTH_EMAIL_IS_VERIFIED: (optional) A boolean indicating whether all user emails have been verified by you previously. If this is true, Transcend will assume that you have confirmed all email addresses belong to their respective logged-in users. Verified emails can be used to discover data in other systems (such as marketing, sales, and other SaaS tools).
• OAUTH_EMAIL_IS_VERIFIED_PATH: (optional) The JSON path to extract a boolean field indicating whether the email of this specific user has been verified. When this resolves to false, Transcend will send a verification email to confirm that the data subject has access to that email inbox. If this resolves to true, Transcend will skip that step.

You can display the user's profile picture when they're logged into the Privacy Center. This is purely cosmetic and not required.

• OAUTH_GET_PROFILE_PICTURE_URL: (optional) The API endpoint to retrieve a profile picture for the user (often the same as OAUTH_GET_CORE_ID_URL or OAUTH_GET_EMAIL_URL).
• OAUTH_GET_PROFILE_PICTURE_PATH: (optional) The JSON path to extract the profile picture URL for the user. In the example above, this would be data.user.avatar_url.

To control how long data subjects or employees can keep an active session to Sombra (such as for PCI DSS or other compliance needs), use the following variables:

• EMPLOYEE_SESSION_EXPIRY_TIME: The amount of time the employee session JWT will last. Defaults to 3 hours.
• DATA_SUBJECT_SESSION_EXPIRY_TIME: The amount of time the data subject session JWT will last. Defaults to 5 days.

These time periods can be expressed with a time unit, like 2 days or 10h. A unitless value is interpreted as milliseconds. See https://github.com/vercel/ms for more information.

Note that not every action on the Admin Dashboard requires a Sombra session. Sombra sessions are only necessary for actions like creating new requests, viewing sample data from data discovery, viewing DSAR contents, connecting an integration, etc.