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

# SSO overview

> How Summand uses the WorkOS Admin Portal for SSO setup — and what your admin can configure from a single dashboard.

Summand's identity layer is built on [WorkOS](https://workos.com). When an org admin clicks **Configure** under any Enterprise feature in **Settings → Organization**, Summand generates a one-time WorkOS **Admin Portal** link and redirects you to it. The portal is where every actual configuration step happens — Summand doesn't reimplement the IdP wizard.

This means every IdP and integration WorkOS supports is automatically available to Summand customers, without us shipping a new release.

## What's available in the Admin Portal

The portal exposes one hosted UI per **intent**. Each intent is a separate "Configure" button in Summand's organization settings.

| Intent | What it configures | Common IdP examples |
| - | - | - |
| **SSO** | SAML 2.0 or OIDC for sign-in | Okta, Azure AD / Entra, Google Workspace, OneLogin, JumpCloud, Auth0, Ping, custom |
| **Directory Sync** | SCIM provisioning + deprovisioning | Okta, Azure AD, OneLogin, JumpCloud, BambooHR, Rippling |
| **Domain Verification** | Claim ownership of an email domain | DNS TXT record validation |
| **Certificate Renewal** | Rotate SAML signing certificates | Per-IdP rotation flows |

Organization settings also link to the Admin Portal's **Audit Logs** and **Log Streams** pages. Summand doesn't send events to WorkOS Audit Logs, so those pages hold no Summand events. See [Audit logs](https://docs.summand.com/enterprise/audit-logs.md) for what Summand records.

See the per-IdP guides for setup details:

> [card] [Okta](https://docs.summand.com/enterprise/sso/okta.md)
>
> SAML or OIDC, with optional SCIM directory sync.

> [card] [Azure AD / Entra ID](https://docs.summand.com/enterprise/sso/azure-ad.md)
>
> OIDC or SAML, with Entra-native directory sync.

> [card] [Google Workspace](https://docs.summand.com/enterprise/sso/google-workspace.md)
>
> Custom SAML, with manual user provisioning.

> [card] [Other IdPs](https://docs.summand.com/enterprise/sso/generic-saml.md)
>
> OneLogin, JumpCloud, Auth0, Ping, custom — any standards-compliant SAML or OIDC provider.

## How sign-in works

```
User enters email at summand.com
   │
   ▼
Summand calls /api/auth/sso/check-domain
   │  GET workos.organizations.listOrganizations({ domains: [<domain>] })
   ▼
Domain matches a WorkOS organization with SSO?
   │
   ├─ Yes → redirect to WorkOS authorization URL
   │     └─ User authenticates at the IdP
   │        └─ WorkOS validates the response
   │           └─ Redirects to /auth/callback with code
   │              └─ Summand exchanges the code for a session
   │                 └─ JIT-provisions the user if first sign-in
   │                    └─ Sets session cookies → user is in
   │
   └─ No → falls back to email + password (or Google / GitHub OAuth)
```

The user **never types a workspace URL**. Email-domain lookup handles routing automatically. Summand also exposes direct **Continue with Google** and **Continue with GitHub** buttons on the sign-in screen — those go straight to WorkOS's hosted social providers.

## Setting up SSO end-to-end

**1. Verify your domain**

From **Settings → Organization → Domain Verification**, click **Configure**. The Admin Portal asks you to add a TXT record at the apex of your domain. Once DNS propagates and you click *Verify*, that domain becomes the routing key for SSO sign-ins.

Multiple domains are supported — verify each one separately.

**2. Configure your IdP**

From **Settings → Organization → Single Sign-On**, click **Configure**. The Admin Portal opens; pick your IdP (Okta, Azure AD, Google Workspace, etc.) and follow the per-IdP wizard. WorkOS provides ACS URLs, Entity IDs, and metadata download links inline — copy them into your IdP, paste your IdP's metadata back into the portal, and click *Test*.

The whole step takes 5-10 minutes if you have IdP admin access.

**3. (Optional) Set up Directory Sync**

Under **Directory Sync → Configure**, connect a SCIM provider so users are auto-provisioned when added to your IdP and auto-deprovisioned when removed. Without directory sync, users are JIT-created on first sign-in but not removed automatically when they leave.

**4. Test as a real user**

Open `summand.com` in an incognito window, enter an email at your verified domain, and confirm you're redirected to your IdP. New users are auto-provisioned via JIT and added to your WorkOS organization.

## Authentication options

Summand surfaces three sign-in paths on the login screen:

| Method | When to use |
| - | - |
| **Email-based SSO** | Default for SSO-enabled domains. Email entry triggers IdP redirect automatically. |
| **Continue with Google / GitHub** | Direct social login via WorkOS-hosted OAuth, useful for individual accounts. |
| **Email + password** | Fallback for non-SSO domains and individual accounts. |

Email + password and social login coexist with SSO. If your org wants password login disabled for SSO-eligible domains, configure that in your **WorkOS organization settings** via the Admin Portal — it's enforced at the WorkOS layer, not in Summand code.

## Just-in-time (JIT) provisioning

When a new user signs in via SSO for the first time, Summand creates their account automatically using attributes from the IdP. Required attributes:

| Attribute | Purpose |
| - | - |
| `email` | Primary identifier |
| `name` (or `given_name` + `family_name`) | Display name |

New users join as **members**. Admins change roles in **Settings → Organization → Members**.

## What Summand stores vs. what WorkOS stores

| Data | Stored in |
| - | - |
| User identity, sessions, MFA factors | WorkOS |
| SSO connection config (cert, ACS URL, attributes) | WorkOS |
| Directory sync state | WorkOS |
| Organization membership | WorkOS, mirrored into Summand's OpenFGA authorization store |
| Datasets, connectors, computed-context layers | Summand AWS |

This split is intentional — identity-critical data is held by a SOC 2 Type II identity provider rather than reimplemented inside Summand.

## Troubleshooting

For symptom-level debugging — bad metadata, attribute mismatches, certificate issues — see [SSO troubleshooting](https://docs.summand.com/enterprise/sso/troubleshooting.md).


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