> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traversal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How users sign in to Traversal, how organizations manage access, and how to troubleshoot common authentication issues.

Traversal uses single sign-on (SSO) to authenticate users. Your organization administrator controls who can access Traversal and which sign-in methods are available.

## How sign-in works

Visit [app.traversal.com](https://app.traversal.com) (or your [BYOC deployment](/architecture/byoc)'s address) and enter your email address. Traversal uses your email domain to match you to your organization and present the available sign-in methods. For SSO users, Traversal identifies your organization's identity provider and redirects you there automatically.

If no organization matches your email, Traversal displays an **"Email not found"** error.

<Steps>
  <Step title="Enter your email">
    Traversal matches your email to an organization and displays the available sign-in methods.
  </Step>

  <Step title="Authenticate with your provider">
    Sign in using the method your organization has configured (e.g., enterprise SSO, Google, or email magic link).
  </Step>

  <Step title="Access Traversal">
    After successful authentication, you are signed in and can start using Traversal immediately.
  </Step>
</Steps>

## Organization access models

Your administrator chooses one of two access models when setting up your organization.

### Invite-only

New users **must** receive an email invitation before they can sign in. This is the default for most organizations and provides the tightest access control.

* An administrator sends an invite to your email address.
* You receive an email with a sign-in link containing a one-time invite code.
* Click the link and authenticate with your provider to complete sign-in.
* The invite code is consumed on first use and cannot be reused.

### Open access (domain-based)

Any user with a matching email domain can sign in without an explicit invite. This is useful for organizations that want frictionless onboarding for all employees.

* No invite is required — just sign in with your corporate email.
* Your email domain must match one of the domains your administrator has registered.

<Tip>
  Even in open-access organizations, users with email domains that are not registered to the organization still require an invite.
</Tip>

## Inviting users

Organization administrators can invite new users from the Traversal web app.

<Steps>
  <Step title="Open user management">
    Navigate to **Settings** and select **User Management**.
  </Step>

  <Step title="Send invites">
    Enter one or more email addresses (comma-separated) and choose a role:

    * **Member** — can run investigations, view results, and use integrations.
    * **Admin** — everything a member can do, plus manage users, integrations, and organization settings.
  </Step>

  <Step title="Users receive an email">
    Each invitee receives an email with a personalized sign-in link. The link includes a one-time invite code tied to their email address.
  </Step>
</Steps>

### Inviting an existing user

If the email address you invite belongs to an existing Traversal user in your organization, the system checks their current role:

* **User already has the role** — no action is taken.
* **User needs a role upgrade** — the new role is granted immediately (e.g., promoting a member to admin).

No duplicate accounts are created.

## Enterprise SSO onboarding

Enterprise Single Sign-On (SSO) allows your organization to authenticate users through an existing identity provider (IdP) such as Okta, Microsoft Entra ID, Google Workspace, or any SAML 2.0 / OIDC-compliant provider. This eliminates separate credentials — your team signs in to Traversal with the same accounts they already use.

<Warning>
  Across all identity providers, you **must** assign users or groups to the Traversal application in your IdP. Users who are not assigned to the client application cannot sign in, even if they have valid credentials. This is the most common cause of failed SSO logins.
</Warning>

### Attribute mapping

Traversal identifies users by their email address. Regardless of which identity provider you use, the **NameID** (SAML) or **sub/email** claim (OIDC) must map to the user's **primary email address**. This is how Traversal matches authenticated users to their organization and account.

| Protocol | Required mapping                                        |
| -------- | ------------------------------------------------------- |
| **SAML** | NameID → primary email address (format: `EmailAddress`) |
| **OIDC** | `email` scope and claim → primary email address         |

<Note>
  If the NameID or email claim does not return the user's primary email, Traversal cannot match the user to an organization, and sign-in will fail with an "Email not found" error.
</Note>

### SCIM provisioning

Traversal does not currently support SCIM. User provisioning and deprovisioning must be managed manually through Traversal's invite system or by assigning and unassigning users in your identity provider.

### Setup instructions

<Tabs>
  <Tab title="Okta (OIDC)">
    <Steps>
      <Step title="Create an app integration in Okta">
        Go to **Okta Admin Console → Applications → Applications → Create App Integration**. Select **OIDC - OpenID Connect** as the sign-in method and **Web Application** as the application type.
      </Step>

      <Step title="Configure redirect URIs">
        Set the **Sign-in redirect URI** to:

        ```
        https://login.traversal.com/login/callback
        ```

        Optionally, set the **Initiate login URI** to:

        ```
        https://app.traversal.com
        ```
      </Step>

      <Step title="Assign users and groups">
        In the **Assignments** tab, add every user or group that needs access to Traversal. Unassigned users will receive a "User is not assigned to the client application" error and cannot sign in.
      </Step>

      <Step title="Copy credentials">
        From the application settings, copy the **Client ID** and **Client Secret**. Verify that the granted scopes include `openid`, `email`, and `profile`.
      </Step>

      <Step title="Send details to Traversal">
        Provide the following to the Traversal team:

        * Okta domain (e.g., `yourcompany.okta.com`)
        * Client ID
        * Client Secret
        * Scopes used (`openid email profile`)
      </Step>
    </Steps>
  </Tab>

  <Tab title="Microsoft Entra ID">
    <Steps>
      <Step title="Register Traversal in Entra ID">
        Go to **Microsoft Entra admin center → Identity → Applications → App registrations → New registration**. Give the application a name (e.g., "Traversal").
      </Step>

      <Step title="Configure redirect URIs">
        Under **Authentication → Platform configurations**, add a **Web** platform with the redirect URI:

        ```
        https://login.traversal.com/login/callback
        ```
      </Step>

      <Step title="Generate a client secret">
        Go to **Certificates & secrets → Client secrets → New client secret**. Copy the secret **Value** immediately — it is only displayed once.
      </Step>

      <Step title="Enable user assignment">
        Go to **Enterprise Applications → Traversal → Properties** and set **User assignment required** to **Yes**. Then under **Users and groups**, assign the users or groups that need access. Users who are not assigned cannot sign in.
      </Step>

      <Step title="Send details to Traversal">
        Provide the following to the Traversal team:

        * Domain (e.g., `yourcompany.onmicrosoft.com` or your custom domain)
        * Application (client) ID (found on the app's **Overview** page)
        * Client Secret value
      </Step>
    </Steps>
  </Tab>

  <Tab title="SAML 2.0">
    If your identity provider supports SAML 2.0, you can configure Traversal as a service provider.

    <Steps>
      <Step title="Gather SAML details from your IdP">
        Send Traversal **either** your IdP's metadata URL (recommended — it contains the sign-in URL, signing certificate, and supported bindings) **or** the individual sign-in URL and signing certificate. Either path works; the metadata URL is faster and less error-prone.

        | Field                             | Required                             | Description                                                                                                                                                                                                                                                                                                                                                          |
        | --------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | **Metadata URL**                  | Send this **or** the next two fields | The URL where your IdP publishes its SAML metadata XML. The metadata document declares the IdP's endpoints, signing certificate, and supported bindings. If you send this, you can skip the Sign In URL and X509 Signing Certificate.                                                                                                                                |
        | **Sign In URL**                   | Required if no Metadata URL          | The URL where SAML authentication requests are sent. This is also called the single sign-on (SSO) endpoint.                                                                                                                                                                                                                                                          |
        | **X509 Signing Certificate**      | Required if no Metadata URL          | The public-key certificate required by the SP to validate the signature of the authentication assertions that have been digitally signed by the IdP. Traversal accepts the `.pem` and `.cer` formats.                                                                                                                                                                |
        | **Sign Out URL**                  | Optional                             | The URL where SAML logout requests are sent. This is also called the single logout (SLO) endpoint. Provide this if you want users to be signed out of your IdP when they sign out of Traversal.                                                                                                                                                                      |
        | **User ID Attribute**             | Optional                             | The attribute in the SAML assertion that identifies the user. Defaults to the NameID. Provide this only if your IdP exposes the user's primary email under a different attribute.                                                                                                                                                                                    |
        | **Protocol Binding**              | Optional                             | The HTTP binding the IdP expects for SAML authentication requests (`HTTP-POST` or `HTTP-Redirect`). Defaults to `HTTP-Redirect`.                                                                                                                                                                                                                                     |
        | **Signed authentication request** | Optional                             | Whether your IdP requires Traversal to sign outbound SAML authentication requests (`yes` or `no`, defaults to `no`). If `yes`, also specify the signing algorithm (`RSA-SHA256` or `RSA-SHA1`, defaults to `RSA-SHA256`) and the digest algorithm (`SHA256` or `SHA1`, defaults to `SHA256`). Traversal will share back a signing certificate to upload to your IdP. |

        You will also need **attribute mappings** for `email`, `name`, and optionally `groups` or `roles`. The NameID (or the User ID Attribute, if specified) must map to the user's primary email address (see [Attribute mapping](#attribute-mapping)).
      </Step>

      <Step title="Assign users to the application">
        In your IdP, assign the users or groups that should have access to Traversal. Users who are not assigned to the SAML application cannot sign in.
      </Step>

      <Step title="Send details to Traversal">
        Provide the required fields, plus any of the optional fields above that apply to your IdP, to the Traversal team. Traversal will provide you with the **Assertion Consumer Service (ACS) URL** and **SP Entity ID** to complete configuration on your side. If signed authentication requests are required, Traversal will also provide a signing certificate.
      </Step>
    </Steps>
  </Tab>

  <Tab title="OIDC (generic)">
    For any OIDC-compliant identity provider not listed in the other tabs:

    <Steps>
      <Step title="Gather OIDC details from your IdP">
        Obtain the following:

        * **Issuer URL** (e.g., `https://idp.example.com`) — Traversal uses this to auto-discover endpoints via `/.well-known/openid-configuration`
        * **Client ID** and **Client Secret**
        * **Scopes** (`openid email profile`)
      </Step>

      <Step title="Configure the redirect URI">
        In your IdP, register the following redirect URI for the Traversal application:

        ```
        https://login.traversal.com/login/callback
        ```
      </Step>

      <Step title="Assign users to the application">
        Ensure all users who need access to Traversal are assigned to the application in your IdP. Unassigned users cannot sign in.
      </Step>

      <Step title="Send details to Traversal">
        Provide the following to the Traversal team:

        * Issuer URL
        * Client ID
        * Client Secret
        * Scopes
      </Step>
    </Steps>
  </Tab>

  <Tab title="Google Workspace">
    <Steps>
      <Step title="Add Traversal as a SAML app">
        Go to **Google Admin Console → Apps → Web and mobile apps → Add app → Add custom SAML app**. Follow the wizard and download the **IdP metadata XML** when prompted.
      </Step>

      <Step title="Configure the SAML app">
        When asked for service provider details, enter the **ACS URL** and **Entity ID** provided by the Traversal team. Set the **Name ID format** to `EMAIL` and map the `email` and `name` attributes.
      </Step>

      <Step title="Enable the app for users">
        In the SAML app settings, go to **User access** and set the app to **On for everyone** — or scope it to specific organizational units. Users in disabled OUs cannot sign in.
      </Step>

      <Step title="Send details to Traversal">
        Provide the following to the Traversal team:

        * Google Workspace domain (e.g., `yourcompany.com`)
        * Downloaded IdP metadata XML file
        * Attribute mappings (`email`, `name`, and optionally `groups`)
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Tip>
  After SSO is configured, coordinate a test sign-in with the Traversal team before rolling out to all users. This catches misconfigured redirect URIs, missing attribute mappings, or unassigned user groups early.
</Tip>

## Common issues

<AccordionGroup>
  <Accordion title="'Email not found' error">
    Traversal could not match your email to an organization. Either your email domain is not registered with any Traversal organization, or you have not been invited. Contact your administrator or reach out to [support@traversal.com](mailto:support@traversal.com).
  </Accordion>

  <Accordion title="'An invite is required' error">
    Your organization uses invite-only access, and you do not have a valid invite. Ask your organization administrator to send you an invitation from the **User Management** settings page.
  </Accordion>

  <Accordion title="'Your invite has expired' error">
    Invite codes expire after a set period. Ask your administrator to resend the invitation — this generates a fresh code and invalidates the old one.
  </Accordion>

  <Accordion title="SSO redirect fails or loops">
    The redirect URI configured in your identity provider does not match the expected value. Verify that the redirect URI is set to exactly:

    `https://login.traversal.com/login/callback`

    Extra trailing slashes, `http` instead of `https`, or incorrect paths will cause the redirect to fail.
  </Accordion>

  <Accordion title="I signed in but don't see any data">
    You are authenticated, but your organization's integrations may not be configured yet. Ask your administrator to connect your observability, code, and communication tools in **Settings > Knowledge Base**.
  </Accordion>
</AccordionGroup>

## Roles and permissions

Traversal uses role-based access control (RBAC). Roles are assigned per organization.

| Role       | Capabilities                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------- |
| **Member** | Run investigations, view results, interact with Slack, access the knowledge bank                        |
| **Admin**  | Everything a member can do, plus manage users, configure integrations, and update organization settings |

Roles are assigned when a user is invited, and can be updated by any administrator.

## Security

All authentication flows use industry-standard protocols:

* **OIDC / OAuth 2.0** with PKCE for browser-based sign-in.
* **Short-lived access tokens** that refresh automatically in the background.
* **HTTPS-only cookies** with strict same-site policies.
* **CSRF protection** on all state-changing requests.

For details on Traversal's broader security posture, certifications, and architecture, see the [Security](/responsible-use/security) page.