# Authentication (/docs/sombra/deploying/customizing-sombra/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.

## Authentication Categories [#authentication-categories]

Sombra authenticates two types of users:

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

## Employee Authentication [#employee-authentication]

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`.

### SAML 2.0 SSO Authentication Strategy [#saml-20-sso-authentication-strategy]

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)

<Callout type="info">
  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](https://app.transcend.io) 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.
</Callout>

## Data Subject Authentication [#data-subject-authentication]

### Available Methods [#available-methods]

Configure data subject authentication using the `DATA_SUBJECT_AUTHENTICATION_METHODS` environment variable:

| Configuration Value        | Description                                     |
| -------------------------- | ----------------------------------------------- |
| `session,transcend`        | Enable email verification login                 |
| `session,jwt`              | Enable JWT Magic Link authentication            |
| `session,oauth`            | Enable OAuth 2.0 authentication                 |
| `session,authorized_agent` | Enable email verification for authorized agents |

_Session_ is always required in your configuration. You can include multiple authentication methods if needed.

### Email Authentication [#email-authentication]

Users will receive an email to verify their address and be granted access to execute their Data Subject Request.

### Authorized Agent Authentication [#authorized-agent-authentication]

Include `authorized_agent` in `DATA_SUBJECT_AUTHENTICATION_METHODS` to allow authorized agents to verify their email and submit requests on behalf of data subjects. See [Authorized Agent Requests](../../../dsr-automation/processing-requests/authorized-agent-requests.mdx) for the Privacy Center flow.

Authorized Agent authentication uses email magic-link verification, scoped to authorized agent sessions. The agent verifies their own email address, the same way the `transcend` method verifies a data subject. No additional JWT or OAuth environment variables are required.

For self-hosted Sombra, add `authorized_agent` to `DATA_SUBJECT_AUTHENTICATION_METHODS`. For example:

```shell
DATA_SUBJECT_AUTHENTICATION_METHODS=session,authorized_agent
```

If Transcend hosts your Sombra, enable Authorized Agent authentication from Privacy Center > Authentication Methods in the Admin Dashboard instead.

### JWT Magic Link Authentication [#jwt-magic-link-authentication]

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

#### Configuration Steps [#configuration-steps]

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

```shellscript
# 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"
```

1. Configure the environment variables:

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

### OAuth 2.0 Authentication [#oauth-20-authentication]

Configure OAuth when `oauth` is included in `DATA_SUBJECT_AUTHENTICATION_METHODS`. This configuration requires getting an access token, then fetching a user ID and email address. You can optionally fetch extra attested identifiers and a profile picture from the same or another userinfo URL.

#### Get an Access Token [#get-an-access-token]

- `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](https://tools.ietf.org/html/rfc6749#section-4.1.3), which resolves an `authorization_code` to an `access_token`
- `OAUTH_GET_TOKEN_BODY_GRANT_TYPE`: (optional) The [grant type](https://oauth.net/2/grant-types/) 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 [Workspace Configuratoin ->  Data Subjects](https://app.transcend.io/privacy-requests/settings/data-subjects)

#### Get Core ID (User ID) [#get-core-id-user-id]

- `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`.&#xA;&#xA;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`).

#### Get an Email Address [#get-an-email-address]

- `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.

#### Get a Profile Picture for the User [#get-a-profile-picture-for-the-user]

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`.

#### Get extra identifiers (optional) [#get-extra-identifiers-optional]

After Sombra exchanges the authorization code for an access token, it can call a userinfo endpoint to collect additional identifiers attested by your identity provider. Use this when preference records or DSRs should resolve on an identifier other than email (for example a member ID).

Set both of the following. If either is omitted, Sombra skips this step.

- `OAUTH_GET_EXTRA_IDENTIFIERS_URL`: HTTPS endpoint that returns attested identifiers. Sombra sends `Authorization: Bearer <access_token>`. This is often the same userinfo URL as `OAUTH_GET_EMAIL_URL`.
- `OAUTH_GET_EXTRA_IDENTIFIERS_PATH`: Dotted JSON path to an array of objects. Each object must have `name` (the identifier type configured in Transcend, such as `authId0`) and `value` (the identifier value for this user).

Example response:

```json
{
  "user": {
    "email": "alex@example.com",
    "identifiers": [
      { "name": "authId0", "value": "member-123" }
    ]
  }
}
```

For that body, set `OAUTH_GET_EXTRA_IDENTIFIERS_PATH` to `user.identifiers`.

If this request or decode fails, Sombra logs a warning and continues the login with email and core ID only. Extra identifiers are not required for a successful OAuth session.

On Transcend-hosted Sombra, configure the same values in the Admin Dashboard under **Privacy Center** → **Authentication Methods** → **Extra Identifier Settings** (**Extra Identifiers Endpoint** and **Extra Identifiers Path**). Do not set these environment variables on Transcend-hosted clusters.

## Session Duration [#session-duration]

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](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.