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

# Enterprise SSO on Multi-Tenant SaaS

> Set up SAML or OIDC single sign-on between your identity provider and HoneyHive multi-tenant SaaS, including the values to configure and the user attributes HoneyHive needs.

Connect your identity provider (IdP) to HoneyHive multi-tenant SaaS (`app.us.honeyhive.ai`) so your users sign in with their work accounts. After setup, users enter their work email at sign-in and are redirected to your IdP automatically.

HoneyHive configures its side of the connection for you. This page covers what you set up in your IdP and what you send HoneyHive. For self-hosted deployments, see [Identity Provider](/v2/workspace/identity-provider) instead.

<Info>
  To start, [Contact us](mailto:sales@honeyhive.ai) or reach out to your account team.
</Info>

## Choose a protocol

HoneyHive supports SAML 2.0 and OpenID Connect (OIDC). Use whichever your IdP supports best.

| Step | SAML 2.0 | OIDC |
| - | - | - |
| You create in your IdP | A SAML application | An OIDC web application |
| HoneyHive sends you | ACS URL and entity ID | Redirect URI |
| You send HoneyHive | IdP metadata URL, or sign-in URL, issuer, and signing certificate | Issuer or discovery URL (or IdP domain), client ID, and client secret |

Complete the [shared setup](#shared-setup) first, then follow [Set up SAML](#set-up-saml) or [Set up OIDC](#set-up-oidc).

## Shared setup

<Steps>
  <Step title="List your email domains">
    List every domain your users sign in with. Matching is exact, so list subdomains such as `eng.acme.com` separately from `acme.com`.

    * Each domain can belong to only one HoneyHive organization.
    * Public domains such as `gmail.com` or `yahoo.com` never grant organization membership.
  </Step>

  <Step title="Send HoneyHive your details">
    Send HoneyHive your chosen protocol, your email domains, and your HoneyHive organization name if it already exists.

    HoneyHive replies with the values to enter in your IdP: the ACS URL and entity ID for SAML, or the redirect URI for OIDC.
  </Step>
</Steps>

## Set up SAML

<Steps>
  <Step title="Create a SAML application">
    In your IdP, create a SAML 2.0 application for HoneyHive and enter the values HoneyHive sent you:

    | IdP field | Value |
    | - | - |
    | ACS URL (also called single sign-on URL, reply URL, or post-back URL) | ACS URL from HoneyHive |
    | Entity ID (also called audience URI or identifier) | Entity ID from HoneyHive |
  </Step>

  <Step title="Configure the NameID and attributes">
    Set the `NameID` to the user's email address and add these attributes. Send the email attribute even though `NameID` is also the email, so the address reaches HoneyHive as the user's email. The attribute names are claim identifiers, not URLs to visit.

    | Attribute | Value | Required |
    | - | - | - |
    | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | User's email address | Yes |
    | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | First name | No |
    | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | Last name | No |
    | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | Display name | No |

    Sign the SAML response or assertion.
  </Step>

  <Step title="Assign users">
    Assign the users or groups who should have access to the application. HoneyHive grants no access to anyone your IdP does not authenticate.
  </Step>

  <Step title="Send HoneyHive your IdP details">
    Send one of the following:

    * Your IdP's SAML metadata URL (preferred).
    * Your IdP's sign-in URL, issuer (IdP entity ID), and X.509 signing certificate.
  </Step>
</Steps>

## Set up OIDC

<Steps>
  <Step title="Create an OIDC web application">
    In your IdP, create an OIDC web application for HoneyHive with these settings:

    | Setting | Value |
    | - | - |
    | Application type | Web application |
    | Grant type | Authorization code |
    | Redirect URI | Redirect URI from HoneyHive |
    | Scopes | `openid`, `email`, `profile` |

    Generate a client secret.
  </Step>

  <Step title="Assign users">
    Assign the users or groups who should have access to the application. HoneyHive grants no access to anyone your IdP does not authenticate.
  </Step>

  <Step title="Send HoneyHive your IdP details">
    The values you send depend on your IdP. Send the client secret through a secure channel.

    <Tabs>
      <Tab title="Okta">
        | Value | Where to find it |
        | - | - |
        | Okta domain | Your Okta org URL, for example `acme.okta.com` |
        | Client ID | The application's **General** tab |
        | Client secret | The application's **General** tab |
      </Tab>

      <Tab title="Microsoft Entra ID">
        | Value | Where to find it |
        | - | - |
        | Directory domain | Your Entra ID domain, for example `acme.onmicrosoft.com` or a verified custom domain |
        | Application (client) ID | The app registration's **Overview** page |
        | Client secret | The app registration's **Certificates & secrets** page |

        Set the redirect URI platform to **Web**.
      </Tab>

      <Tab title="Other OIDC providers">
        | Value | Where to find it |
        | - | - |
        | Discovery URL | Your issuer URL. It must publish `/.well-known/openid-configuration`. |
        | Client ID | Your IdP's application settings |
        | Client secret | Your IdP's application settings |
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Test sign-in

1. Open [app.us.honeyhive.ai](https://app.us.honeyhive.ai) and enter an assigned user's work email.
2. Confirm you are redirected to your IdP and back to HoneyHive.
3. Confirm the user appears as a member of your organization, not only signed in to HoneyHive. If not, see [Troubleshooting](#troubleshooting).

## User attributes

Both protocols must provide these values for each user:

| Value | Required | Notes |
| - | - | - |
| Unique user identifier | Yes | SAML `NameID` or OIDC `sub`. |
| Email | Yes | Must be a valid email address on one of your organization's domains. HoneyHive falls back to `upn` if no email is sent, but the `upn` must itself be a valid email address on one of your domains. |
| Verified email flag | Recommended | `email_verified`. A missing value counts as unverified. Unverified users can sign in and join an organization, but cannot set the organization's email domains in **Settings > Organization**. |
| First, last, and display name | No | Used for the user's display name. Names a user edits in HoneyHive are kept on later sign-ins. |

HoneyHive identifies each account by email address, compared case-insensitively:

* **Use a stable, unique email per person.** Two IdP users with the same email sign in to the same HoneyHive account. Do not send shared mailbox addresses.
* **Email changes create a new account.** A user whose email changes signs in as a new user with no memberships. [Contact us](mailto:sales@honeyhive.ai) to migrate memberships.
* **`NameID` format does not affect account identity.** HoneyHive matches accounts on email, so a transient `NameID` does not split a user's account.
* **Send the address users type at sign-in.** The email in the assertion or token must use one of your organization's domains.
* **Sign in through SSO, not a password account.** A HoneyHive username-and-password account with your domain is not added to your organization automatically.

## Group attributes

On multi-tenant SaaS, HoneyHive does not read IdP group claims. Access within the organization is managed in HoneyHive:

* Users who match your email domains join the organization as **Org Member** on first sign-in.
* Admins add users to workspaces and projects and assign roles. See [Inviting Teammates](/v2/workspace/inviting-teammates) and [Roles](/v2/workspace/roles).
* To limit who can reach HoneyHive, restrict assignment of the HoneyHive application in your IdP.

Deriving roles and memberships from IdP groups is available on [Dedicated Cloud](/v2/setup/dedicated) and [Self-Hosted](/v2/setup/self-hosted) deployments. See [SSO group-based provisioning](/v2/workspace/roles#sso-group-based-provisioning).

## Troubleshooting

| Symptom | Likely cause |
| - | - |
| An error appears after the user enters their email | The email domain is not registered for your organization. Send HoneyHive the missing domain. |
| A password field appears instead of a redirect to your IdP | The domain is not registered on your SSO connection. Send HoneyHive the missing domain. |
| An organization picker appears | The domain is registered on more than one SSO connection. Pick your company's organization, and let HoneyHive know so we can remove the duplicate. |
| User signs in but sees no organization | The email's domain is not in your organization's email domains, or the user signed in with a password account instead of SSO. |
| Sign-in fails with an invalid token or missing email error | Your IdP does not send an email, or sends a value that is not an email address. |
| A returning user appears as a new user | Their email address changed in your IdP. |


## Related topics

- [Identity Provider](/v2/workspace/identity-provider.md)
- [Multi-Tenant SaaS](/v2/setup/managed.md)
- [Multi-Instance Tracing](/v2/tracing/multi-instance.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.