> ## 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
> Connection requirements, identity attributes, and group attributes for connecting your identity provider to HoneyHive multi-tenant SaaS through Auth0 Organizations.
HoneyHive multi-tenant SaaS (`app.us.honeyhive.ai`) signs users in through Auth0. Enterprise customers connect their own identity provider (IdP) as an Auth0 **enterprise connection** attached to an Auth0 **Organization** for their company. Auth0 discovers the right Organization and IdP from the user's email address, so your users never pick a connection by hand.
This page lists what HoneyHive needs from your IdP. HoneyHive creates and manages the Auth0 side for you. For self-hosted deployments, see [Identity Provider](/v2/workspace/identity-provider) instead.
To set up SSO, [Contact us](mailto:sales@honeyhive.ai) or reach out to your account team with the details listed in [What to send HoneyHive](#what-to-send-honeyhive).
## How sign-in works
```mermaid theme={null}
sequenceDiagram
participant U as User
participant HH as HoneyHive app
participant A as Auth0 (HoneyHive tenant)
participant IdP as Your IdP
U->>HH: Open app.us.honeyhive.ai
HH->>A: OIDC authorization request (code + PKCE)
A->>U: Prompt for email (identifier first)
U->>A: alice@acme.com
A->>A: Organization domain discovery on acme.com
A->>IdP: SAML or OIDC request to your enterprise connection
IdP->>A: Assertion with user attributes
A->>HH: Authorization code, then ID token
HH->>HH: Create or update user, join org by email domain
```
1. HoneyHive starts a standard OpenID Connect authorization code flow with PKCE against HoneyHive's Auth0 tenant, whose discovery document is published at `https:///.well-known/openid-configuration`.
2. Auth0 asks for the user's email address first ([Identifier First Authentication](https://auth0.com/docs/manage-users/organizations/login-flows-for-organizations)).
3. Auth0 matches the email domain against **verified** Organization domains ([Organization Domain Discovery](https://auth0.com/docs/manage-users/organizations/login-flows-for-organizations#organization-domain-discovery-optional)). If exactly one Organization matches, Auth0 selects it. If several Organizations share the domain, Auth0 shows an Organization picker. If none match, Auth0 shows an error.
4. Within that Organization, Auth0 routes the user to the enterprise connection whose IdP domains include the email domain (Home Realm Discovery), and your IdP authenticates the user.
5. Auth0 returns an ID token to HoneyHive. HoneyHive validates it, creates or updates the user, and adds the user to the HoneyHive organization whose **email domains** include the user's domain.
Steps 2-4 are Auth0 behavior configured by HoneyHive in its tenant. Step 5 is HoneyHive behavior and depends on the attributes described below.
## Connection requirements
| Requirement | Details |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Protocol | SAML 2.0 (recommended) or OpenID Connect. HoneyHive creates the matching Auth0 enterprise connection. |
| Email domains | Every domain and subdomain your users sign in with. Matching is exact, so `eng.acme.com` must be listed separately from `acme.com`. Each domain is added as a verified Auth0 Organization domain and as an IdP domain on the connection, and must also be listed in your HoneyHive organization's email domains. |
| One organization per domain | A domain can be claimed by only one HoneyHive organization. If you need more than one organization, plan which domains belong to which. |
| Corporate domains only | Public email domains such as `gmail.com` or `yahoo.com` never grant organization membership. |
| User assignment | Assign the HoneyHive application to the users or groups who should have access in your IdP. HoneyHive grants no access to anyone your IdP does not authenticate. |
| Signing | SAML responses or assertions must be signed. Share the IdP signing certificate (usually in the metadata). |
### What to send HoneyHive
* **SAML:** your IdP metadata URL or XML (entity ID, single sign-on URL, and signing certificate).
* **OIDC:** your issuer URL, client ID, and client secret. The issuer must publish `/.well-known/openid-configuration`.
* The list of email domains your users sign in with.
* Your HoneyHive organization name, if it already exists.
HoneyHive replies with the service provider details to enter in your IdP: the Auth0 assertion consumer service (ACS) URL and entity ID for SAML, or the callback URL for OIDC.
## Required user attributes
HoneyHive reads these claims from the ID token Auth0 issues after your IdP authenticates the user. Map your IdP attributes so Auth0 can populate them.
| Claim | Required | SAML attribute commonly mapped | Purpose |
| ------------------------------------------- | -------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sub` | Yes | Derived by Auth0 from the connection and the SAML `NameID` (or the OIDC `sub`) | Subject identifier, validated on every token and stored on the user. |
| `email` | Yes (or `upn`) | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | HoneyHive account key and organization domain matching. |
| `upn` | Fallback | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn` | Used only when `email` is absent. Must be an email-formatted address. |
| `email_verified` | Recommended | Set by Auth0 for the connection | Multi-tenant SaaS treats a missing value as unverified. Unverified users can still sign in and join an organization by email domain, but cannot set an organization's email domains in **Settings > Organization**. |
| `given_name`, `family_name`, `name` | Optional | `givenname`, `surname`, `name` | Display name. Values a user edits in HoneyHive are kept on later sign-ins. |
| `nickname`, `preferred_username`, `picture` | Optional | - | Profile details. |
A sign-in fails if the ID token has no `sub`, has neither `email` nor `upn`, or the address is not a valid email.
### Unique identifier requirements
HoneyHive identifies a user account by **email address**, compared case-insensitively. The `sub` claim is validated and stored, and is updated to the latest value on each sign-in.
* **Use a stable, unique email per person.** Two IdP users with the same email address sign in to the same HoneyHive account. Do not reuse addresses across people or send shared mailbox addresses.
* **Email changes create a new account.** If a user's email changes (for example after a name change or domain migration), they sign in as a new HoneyHive 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. A persistent identifier (such as an employee ID or object ID) is still good practice in your IdP.
* **Send the same address users type at the prompt.** Organization discovery runs on the email typed at the Auth0 prompt, but organization membership uses the `email` claim in the token. Both must use a domain on your organization's email domain list.
* **Sign in through SSO, not a password account.** A HoneyHive username-and-password account (Auth0 subject `auth0|...`) whose email matches your domain is not added to your organization automatically. Users should always sign in through the SSO prompt.
## Group attributes
On multi-tenant SaaS, HoneyHive does not read IdP group claims. Access below the organization level is managed in HoneyHive:
* Users who match your organization's email domains join the organization as **Org Member** on first sign-in.
* Org Admins, Workspace Admins, and Project 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 at all, 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 |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Auth0 shows an error after the user enters their email | The email domain is not a verified domain on your Auth0 Organization. Send HoneyHive the missing domain. |
| Auth0 shows a password field instead of redirecting to your IdP | The domain is not listed on the enterprise connection's IdP domains. |
| Auth0 shows an Organization picker | More than one Organization claims the domain. Pick your company's Organization. |
| User signs in but sees no organization | The `email` claim's domain is not in your HoneyHive 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 | The assertion does not map an email attribute, or maps a value that is not an email address. |
| A returning user appears as a brand-new user | Their email address changed in the 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)