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

# Okta SSO

> Connect Okta to Summand via the WorkOS Admin Portal — SAML, OIDC, and SCIM.

Okta is one of the best-tested IdPs in WorkOS, the identity layer Summand uses. Setup happens entirely inside the WorkOS Admin Portal, which Summand opens for you from the organization settings. You don't need to copy anything between Summand and Okta directly — the portal sits in the middle.

## What Okta unlocks

| Capability                | WorkOS intent | Notes                                                                    |
| ------------------------- | ------------- | ------------------------------------------------------------------------ |
| **SAML 2.0 SSO**          | `sso`         | Most common path. Uses Okta's SAML app integration.                      |
| **OIDC SSO**              | `sso`         | Alternative; pick whichever your security team prefers.                  |
| **Directory Sync (SCIM)** | `dsync`       | Auto-provisions and deprovisions users on Okta group membership changes. |

You can configure SSO without Directory Sync — users will be JIT-provisioned on first sign-in. For production, we strongly recommend pairing SSO with Directory Sync so deprovisioning is automatic.

## Setup

<Steps>
  <Step title="Verify your domain in Summand">
    In Summand, go to **Settings → Organization → Domain Verification → Configure**. The portal asks you to publish a DNS TXT record. Once verified, Summand routes any sign-in attempt from that email domain to your Okta tenant.
  </Step>

  <Step title="Open the SSO Admin Portal">
    From **Settings → Organization → Single Sign-On**, click **Configure**. Summand POSTs to `/api/workos/portal` with `intent: sso`, gets a one-time link, and redirects you. The portal session is scoped to your org and expires shortly after.
  </Step>

  <Step title="Pick Okta in the portal">
    Inside the portal, choose **Okta** as the connection type. WorkOS's wizard provides:

    * The **Single Sign-On URL** (ACS) you paste into Okta
    * The **Audience URI** (Entity ID) you paste into Okta
    * The required attribute statements: `email`, `name`, optionally `given_name` / `family_name` and `groups`
  </Step>

  <Step title="Create the SAML app in Okta">
    In your Okta admin console, **Applications → Create App Integration → SAML 2.0**. Paste the values from the portal into Okta's *Configure SAML* screen, set Name ID format to **EmailAddress**, add the attribute statements, and finish.

    Detailed Okta-side steps live in the [WorkOS Okta SSO guide](https://workos.com/docs/sso/identity-provider-handbook/okta).
  </Step>

  <Step title="Return to the WorkOS portal">
    On Okta's *Sign On* tab, copy the **Identity Provider metadata URL** (or download the XML). Paste it into the WorkOS portal. The portal validates the certificate, parses the metadata, and surfaces any mismatches inline.
  </Step>

  <Step title="Run the test sign-in">
    Click *Test connection* in the portal. WorkOS opens an Okta auth flow in a popup and reports success or a specific error. On success, the connection moves to *Active*.
  </Step>

  <Step title="Assign users in Okta">
    From the Okta SAML app's **Assignments** tab, assign the people or groups who should be able to sign in to Summand.
  </Step>

  <Step title="(Optional) Configure Directory Sync">
    Back in Summand, **Settings → Organization → Directory Sync → Configure**. Pick Okta SCIM and follow the portal's wizard. You'll provision a SCIM URL and bearer token, paste them into Okta's *Provisioning* tab on the SAML app, and toggle the SCIM features (Create Users / Update User Attributes / Deactivate Users / Group Push) you want enabled.
  </Step>
</Steps>

## What it looks like to your users

Once the connection is live, Okta-managed users sign in this way:

1. Open `summand.com`.
2. Enter their company email (e.g. `name@acme.com`).
3. Summand detects the verified domain and redirects them to Okta.
4. They authenticate at Okta as usual.
5. They land back in Summand, signed in. First-time users are auto-provisioned as standard members.

There's no "Sign in with Okta" button to click and no workspace URL to remember.

## Group → role mapping

If you want Okta groups mapped to Summand roles automatically, two paths:

* **Via SAML group attribute** (light) — Okta sends a `groups` attribute in the SAML response. WorkOS captures it; you map specific groups to Summand roles in the portal.
* **Via Directory Sync** (recommended) — Okta groups are first-class objects in WorkOS, and you map them to Summand roles in **Settings → Organization → Members**. Changes in Okta propagate within seconds.

Use Directory Sync if you can — group changes survive token refresh and aren't dependent on the user re-authenticating.

## Removing the connection

From the WorkOS portal, **Single Sign-On → Disable**. Active sessions remain valid until they naturally expire — to force immediate sign-out, also revoke sessions in **Settings → Organization → Members**. Once disabled, sign-in falls back to password (or other configured methods) for the affected domain.