> ## 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                                                          |
| **Audit Logs**          | View authentication & security events | WorkOS-hosted log viewer                                                           |
| **Log Streams**         | Forward events to your SIEM           | Datadog, Splunk, AWS S3, generic webhook                                           |
| **Certificate Renewal** | Rotate SAML signing certificates      | Per-IdP rotation flows                                                             |

See the per-IdP guides for setup details:

<CardGroup cols={2}>
  <Card title="Okta" icon="circle-o" href="/enterprise/sso/okta">
    SAML or OIDC, with optional SCIM directory sync.
  </Card>

  <Card title="Azure AD / Entra ID" icon="microsoft" href="/enterprise/sso/azure-ad">
    OIDC or SAML, with Entra-native directory sync.
  </Card>

  <Card title="Google Workspace" icon="google" href="/enterprise/sso/google-workspace">
    Custom SAML, with manual user provisioning.
  </Card>

  <Card title="Other IdPs" icon="key" href="/enterprise/sso/generic-saml">
    OneLogin, JumpCloud, Auth0, Ping, custom — any standards-compliant SAML or OIDC provider.
  </Card>
</CardGroup>

## 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="(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.
  </Step>

  <Step title="(Optional) Set up audit log streaming">
    Under **Log Streams → Configure**, forward auth events to Datadog, Splunk, S3, or any HTTPS webhook. Keep this enabled in production for compliance.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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       |

Group memberships and roles are mapped via Directory Sync if enabled, or manually 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                                          |
| Audit log events for auth                         | WorkOS (forwarded to your SIEM via Log Streams) |
| Organization membership in Summand                | Summand DynamoDB                                |
| Datasets, connectors, semantic 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](/enterprise/sso/troubleshooting).