> For the complete documentation index, see [llms.txt](https://docs.e6data.com/query-engine/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.e6data.com/query-engine/guides/security/authentication/sso-setup.md).

# SSO setup

Connect your identity provider to e6data via SAML 2.0 or OIDC so members sign in with corporate credentials, with just-in-time provisioning.

This guide is for **super admins**. It explains how to connect your company identity provider (IdP) so members sign in with your existing corporate login instead of one-time codes.

e6data supports two protocols:

* **SAML 2.0** - for IdPs like Okta, OneLogin, Microsoft Entra ID, and Google Workspace SAML apps.
* **OIDC (OpenID Connect)** - for IdPs that expose an OIDC discovery document, including Google, Okta, OneLogin, Entra ID, and Amazon Cognito.

Each organization uses **one** protocol at a time. To switch, delete the existing configuration and create a new one. You must be a super admin to view or change SSO settings (**Management → SSO** in the left nav).

## How SSO sign-in works

1. A member enters their work email.
2. e6data matches the email domain to your organization (by existing account or a matching auto-join domain) and redirects to your IdP.
3. The member authenticates at the IdP, which returns a SAML assertion or OIDC token.
4. If no account exists, one is created automatically (just-in-time) with the **Viewer** role; otherwise the member signs in.

**Just-in-time (JIT) provisioning** creates a member's account on first SSO sign-in with the Viewer role - promote them afterward from **Access Control → Users**. While SSO is enabled, **manual invitations are disabled** because the IdP is the source of truth for who can sign in. See [Domain auto-join and JIT provisioning](/query-engine/guides/security/authentication/domain-auto-join-and-jit.md).

## Before you start

* Super admin access to the **SSO** page.
* Admin access to your IdP to create an application.
* Your organization's email domain configured for auto-join, so domain routing sends members to the right IdP - see [Domain auto-join and JIT provisioning](/query-engine/guides/security/authentication/domain-auto-join-and-jit.md).

e6data exposes service-provider (SP) values to copy into your IdP. You choose the **SP Entity ID**; the **ACS URL**, **SP Metadata URL**, and OIDC **Redirect URI** are generated and shown on the SSO page once you create the configuration:

| Value                                                  | Protocol | Where you use it                                    |
| ------------------------------------------------------ | -------- | --------------------------------------------------- |
| ACS URL (`…/api/v1/auth/sso/acs/{orgId}`)              | SAML     | The assertion-consumer / SSO URL in your IdP        |
| SP Entity ID                                           | SAML     | The audience / entity ID in your IdP                |
| SP Metadata URL (`…/api/v1/auth/sso/metadata/{orgId}`) | SAML     | Some IdPs import SP settings from this URL          |
| Redirect URI (`…/api/v1/auth/sso/callback/{orgId}`)    | OIDC     | The authorized redirect URI in your IdP's OAuth app |

## Set up SAML

1. Open the **SSO** page and select the **SAML** tab.
2. Under **Identity Provider**, enter your IdP details:

   | Field           | What to enter                                                                           |
   | --------------- | --------------------------------------------------------------------------------------- |
   | Provider        | Your IdP type (Okta, OneLogin, Entra ID, Google, or Other) - a label for your reference |
   | IdP Entity ID   | The issuer / entity ID from your IdP                                                    |
   | IdP SSO URL     | Where e6data sends members to log in                                                    |
   | IdP Certificate | The IdP's X.509 signing certificate                                                     |

   Instead of typing these, use the **Metadata** section: paste the **Metadata XML** (recommended - auto-fills entity ID, SSO URL, and certificate) or provide a **Metadata URL**.
3. Set **Service Provider → SP Entity ID (Audience)** to match the audience configured in your IdP. Optionally configure **Attribute Mapping** (defaults: `email`, `firstName`, `lastName`) and **Advanced** options (Logout/SLO URL, IdP-initiated SSO, request signing).
4. Select **Create SAML Configuration**. Copy the generated **ACS URL** and **SP Metadata URL** into your IdP's SAML app.
5. **Enable** the configuration, then test from an incognito window with a test member's work email.

You can disable a configuration without deleting it - useful while testing.

## Set up OIDC

1. Open the **SSO** page and select the **OIDC** tab.
2. In your IdP, create an OAuth/OIDC application (type **Web application**) and set its authorized redirect URI to e6data's OIDC callback (`{base-url}/api/v1/auth/sso/callback/{orgId}`, also shown on the SSO page). Collect the app's **Issuer URL**, **Client ID**, and **Client Secret**.
3. On the SSO page, enter:

   | Field         | What to enter                                                  |
   | ------------- | -------------------------------------------------------------- |
   | Issuer URL    | Your IdP's issuer (for example, `https://accounts.google.com`) |
   | Client ID     | From your IdP's OAuth app                                      |
   | Client Secret | From your IdP's OAuth app (stored encrypted)                   |

   e6data discovers the authorization, token, JWKS, and userinfo endpoints from the issuer's `/.well-known/openid-configuration`. Standard scopes (`openid profile email`) and PKCE are always used.
4. Select **Create OIDC Configuration**, confirm the **Redirect URI** matches your IdP app, **Enable**, and test from an incognito window.

### Google

Connect Google as an **OIDC** provider - there's no separate Google option. In the Google Cloud Console, create an **OAuth 2.0 Client ID** (Web application), add e6data's Redirect URI as an authorized redirect URI, then create an OIDC configuration with issuer `https://accounts.google.com` and the client ID/secret. e6data recognizes the Google issuer automatically.

## After SSO is enabled

* **New members** are created on first sign-in (JIT) with the **Viewer** role - promote them from **Access Control → Users**.
* **Existing members** keep their roles; their account links to the IdP identity on next sign-in.
* **Blocked members** remain blocked - SSO does not bypass a block.
* **Manual invitations are disabled** while SSO is enabled.

## Troubleshooting

Sign-in failures return to the login page with a reason code:

| Reason                     | Likely cause                                                                                 | Fix                                                                                                           |
| -------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `not_configured`           | No SSO config for this organization                                                          | Create and enable a configuration                                                                             |
| `disabled`                 | Config exists but is disabled                                                                | Enable it on the SSO page                                                                                     |
| `user_not_found`           | Email domain isn't mapped to your organization, or the user has no e6data account            | Set the auto-join domain, or ensure the member already has an account                                         |
| `signature_invalid` (SAML) | Wrong or rotated IdP certificate                                                             | Update the signing certificate from current IdP metadata                                                      |
| `audience_mismatch` (SAML) | SP Entity ID in the IdP doesn't match e6data's                                               | Re-copy the SP Entity ID into your IdP                                                                        |
| OIDC callback fails        | Redirect URI mismatch, the IdP didn't return an authorization code, or token exchange failed | Verify the authorized redirect URI in your IdP exactly matches e6data's, and confirm the OAuth app is enabled |

For security, e6data does not log raw assertions or tokens - reproduce failures in an incognito window and note the reason code shown on the login page.

## See also

* [Domain auto-join and JIT provisioning](/query-engine/guides/security/authentication/domain-auto-join-and-jit.md)
* [Roles and permissions](/query-engine/guides/security/identity-and-rbac/roles-and-permissions.md)
* [Sign up and login](/query-engine/get-started/identity-access-setup/sign-up-and-login.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.e6data.com/query-engine/guides/security/authentication/sso-setup.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.