# Okta SSO (SAML)

Let your team sign in to the Capsule portal with their Okta credentials using SAML 2.0 single sign-on.

## Overview

Okta SSO lets your users authenticate to Capsule through your existing Okta org instead of an email magic link. Okta acts as the **SAML identity provider (IdP)**; Capsule uses **Auth0** as its identity broker (the **service provider, SP**) and accepts the SAML assertion Okta issues at sign-in.

> **This is not the same as the Okta integration.** The [Okta integration](/guides/okta) is a directory sync that *enriches user profiles* with group and attribute data. Okta SSO governs *how people log in* to Capsule Portal. The two are independent - you can enable either, both, or neither.


You configure SSO yourself from **Settings → Single Sign On** in the Capsule portal. Setup is a round trip with Okta: create a SAML app in Okta, paste Okta's sign-in URL and certificate into Capsule, then copy the SP values Capsule generates back into Okta.

## How It Works

1. A user opens the Capsule login page and enters their work email.
2. Capsule matches the email domain to your Okta connection and redirects the browser to Okta.
3. The user authenticates with Okta (password, MFA, or whatever policies your org enforces).
4. Okta posts a signed SAML assertion back to Capsule's ACS URL.
5. Capsule validates the assertion and signs the user in, provisioning the account on first login.
6. If the account e-mail already exists in Capsule, it will be linked with the Okta one.


## Prerequisites

Before you begin, ensure you have:

- The **Owner** role in Capsule - only Owners can manage settings and open the **Single Sign On** tab. See [User Roles & Permissions](/guides/user-roles).
- An **Okta admin** role that can create and assign SAML app integrations
- A **verified email domain** your users sign in with (e.g., `your-company.com`)


## Setup Overview

Setup is a round trip between the Okta Admin Console and the Capsule **Single Sign On** settings:

1. **Create a SAML app** in Okta (with placeholder URLs for now)
2. **Configure the connection** in Capsule - paste Okta's sign-in URL and certificate, set your domains, then copy the SP values Capsule generates
3. **Copy Capsule's SP values** back into the Okta app
4. **Assign users** and test


## Step 1: Create a SAML App Integration in Okta

Create the Okta app first to obtain its IdP sign-in URL and signing certificate. Capsule generates its SP values only after the connection is saved (Step 2), so enter **temporary placeholder URLs** here - you'll replace them in Step 3.

1. Sign in to your **Okta Admin Console** as an admin.
2. Go to **Applications** → **Applications**, then click **Create App Integration**.
3. Select **SAML 2.0** as the sign-in method, then click **Next**.
4. On **General Settings**, give the app a name (e.g., `Capsule Security`), optionally add a logo, then click **Next**.
5. On **Configure SAML**, enter temporary placeholders (you'll update these in Step 3):
  - **Single sign-on URL** - a placeholder such as `https://example.com/placeholder`. Leave **Use this for Recipient URL and Destination URL** checked.
  - **Audience URI (SP Entity ID)** - a placeholder such as `https://example.com/placeholder`.
  - **Name ID format** - select **EmailAddress**.
  - **Application username format** - select **Email**.
6. Click **Next**, choose **I'm an Okta customer adding an internal app**, then click **Finish**.
7. Under **Sign On** tab you'll find **Attribute Statements** section, add the following so Capsule receives the user's identity and profile. Use the exact names:
| Name | Expression |
|  --- | --- |
| `email` | `user.profile.email` |
| `given_name` | `user.profile.firstName` |
| `family_name` | `user.profile.lastName` |
Only `email` is required; the name attributes populate the user's display name in Capsule.
8. On the new app's **Sign On** tab, click **More details** under **SAML 2.0** and copy both of the following - you'll enter them in Capsule in Step 2:
  - **Sign on URL** - e.g., `https://<your-org>.okta.com/app/<app-id>/sso/saml`
  - **Signing Certificate** - download or copy the signing certificate (make sure it ends with the following extensions: `.pem` / `.crt` / `.cer`)


## Step 2: Configure the Connection in Capsule

Enter Okta's IdP details in the Capsule **Single Sign On** settings, then read back the SP values Capsule generates.

1. Sign in to the Capsule portal as an **Owner** and go to **Settings → Single Sign On**.
2. Turn on **Enable SAML SSO configuration**. SAML is the supported protocol; others are coming soon.
3. Fill in the fields:
  - **Authorized Domains** - the email domain(s) that should use this connection (e.g., `your-company.com`). Capsule routes sign-ins from these domains to Okta.
  - **Sign In Endpoint** - paste the Okta **Identity Provider Single Sign-On URL** from Step 1.
  - **SSL/TLS Certificate** - upload the Okta **X.509 certificate** from Step 1 (`.crt` or `.cer`). Capsule uses it to verify Okta's SAML signature.
4. Click **Save**.
5. After saving, the **Identity Provider Configuration** section appears with two values Okta needs. Keep this page open for Step 3:
  - **Identifier (Entity ID)**
  - **Reply URL (ACS URL)**


## Step 3: Copy Capsule's SP Values Back into Okta

Replace the Step 1 placeholders with the real values Capsule generated.

### Steps

1. In Okta, open the app → **General** tab → **SAML Settings** → **Edit**, and continue to **Configure SAML**.
2. Update the two URLs:
  - **Single sign-on URL** - paste the Capsule **Reply URL (ACS URL)**. Leave **Use this for Recipient URL and Destination URL** checked.
  - **Audience URI (SP Entity ID)** - paste the Capsule **Identifier (Entity ID)**.
3. Click **Next**, then **Finish** to save.


## Step 4: Assign Users and Test

### Assign access in Okta

1. On the app's **Assignments** tab, assign the **people** or **groups** who should be able to sign in to Capsule.
2. Users who aren't assigned the app in Okta cannot complete SSO.


### Test the connection

Capsule SSO is **service-provider-initiated** - users start from Capsule, not from the Okta dashboard:

- Go to the Capsule login page, enter a work email on an authorized domain, and confirm you're redirected to Okta and back into Capsule.


On first successful login, Capsule links the user's account automatically to existing Capsule users.

> Capsule does not support IdP-initiated sign-in, so the **Capsule Security** tile on the Okta dashboard won't complete a login. To avoid confusion, hide the app icon in Okta (**General** → **App Visibility** → uncheck **Display application icon to users**).


## Attribute Mapping

| Okta attribute statement | Maps to in Capsule | Required |
|  --- | --- | --- |
| `email` | User identity (unique ID) | Yes |
| `given_name` | First name | No |
| `family_name` | Last name | No |


`email` is the stable identifier Capsule keys the account on, so make sure the Okta **Name ID** is the user's email and stays consistent.

## SCIM Provisioning (Optional)

With SSO alone, Capsule creates accounts **just-in-time** - a user exists in Capsule only after their first successful login. SCIM (System for Cross-domain Identity Management) upgrades this to full lifecycle management driven by Okta:

- **Create** - users assigned to the Okta app are provisioned in Capsule before they ever sign in
- **Update** - profile changes in Okta (name, email) sync to Capsule automatically
- **Deactivate** - unassigning or deactivating a user in Okta deactivates their Capsule account
- **Group push** - Okta groups sync to Capsule, where you can map them to Capsule roles


Capsule supports **inbound SCIM 2.0** on top of the SAML connection you configured above - Okta pushes changes to a SCIM endpoint Capsule hosts; nothing flows back into Okta. Authentication uses bearer tokens you generate and revoke in the Capsule portal. SCIM does not change how users sign in - login still happens through SAML SSO.

### Prerequisites

- SAML SSO configured and working (Steps 1–4 above) - the SCIM section only appears once SSO is set up
- The **Owner** role in Capsule
- An Okta admin who can edit the app's provisioning settings


### Step 1: Enable SCIM in Capsule

1. Go to **Settings → Single Sign On**. Below your SSO connection you'll find the **SCIM provisioning** section.
2. In the identity provider dropdown, confirm **Okta Workforce** is selected. Capsule pre-selects it when your Sign In Endpoint is an Okta URL.
> The provider selection controls how Capsule matches SCIM-provisioned users to SAML logins. Okta sends the login email in the SCIM `userName` attribute, so Capsule keys the email off `userName`. With the wrong provider selected, provisioned users can't be matched at login.
3. Click **Enable SCIM**.
4. Copy the **SCIM endpoint URL** that appears - you'll paste it into Okta in Step 3.


### Step 2: Generate a Provisioning Token

1. Under **Provisioning tokens**, click **Generate token**.
2. Copy the token from the dialog **immediately - it is shown only once**.


You can keep multiple tokens active (useful for rotation), see when each was created and last used, and revoke any token at any time.

### Step 3: Enable SCIM Provisioning in Okta

1. In the Okta Admin Console, open the Capsule app → **General** tab → **App Settings** → **Edit**. Under **Provisioning**, select **SCIM**, then **Save**. A **Provisioning** tab appears on the app.
2. On the **Provisioning** tab → **Integration** → **Edit**, fill in:
  - **SCIM connector base URL** - the Capsule **SCIM endpoint URL** from Step 1
  - **Unique identifier field for users** - `userName`
  - **Supported provisioning actions** - check **Push New Users** and **Push Profile Updates**; also check **Push Groups** if you plan to use group-to-role mappings (Step 4)
  - **Authentication Mode** - **HTTP Header**
  - **Authorization** - paste the provisioning token from Step 2
3. Click **Test Connector Configuration** to verify, then **Save**.
4. Still on the **Provisioning** tab, open **To App** → **Edit** and enable **Create Users**, **Update User Attributes**, and **Deactivate Users**, then **Save**.
5. Under the **To App** attribute mappings, delete the **Primary email type**, **Primary phone type**, and **Address type** mappings - Okta sends values for these that the Capsule endpoint rejects.
6. Users and groups already assigned on the **Assignments** tab are provisioned automatically; new assignments provision as you add them.


### Step 4: Map Okta Groups to Capsule Roles (Optional)

Once groups are pushed from Okta (app → **Push Groups** tab), you can drive Capsule roles from group membership:

1. In Capsule, go to **Settings → Single Sign On** → **Group mappings** and click **Add mapping**.
2. Pick an Okta group and the Capsule role its members should receive - **Admin**, **Security Admin**, **Viewer**, or **Legal Discovery**. If the group list is empty, push the groups in Okta first, then click **Refresh groups**.


How group mappings behave:

- Roles are applied at **every SSO sign-in**, so membership changes in Okta take effect the next time the user logs in.
- While any mappings exist, group membership **replaces manual role assignment** - a user's role follows their groups.
- A user in multiple mapped groups gets the **highest-privilege** role among them.
- A user in **no** mapped group has their role removed at next sign-in.
- Removing all mappings returns the tenant to manual role management.


### Disabling SCIM

Click **Disable SCIM** to stop provisioning: the endpoint stops accepting requests and **all provisioning tokens are revoked**. Users that were already provisioned keep their access - manage or remove them from **Settings → Users**.

### SCIM Troubleshooting

- **Okta's "Test Connector Configuration" fails** - confirm the base URL matches the Capsule SCIM endpoint URL exactly, the Authentication Mode is **HTTP Header**, and the token hasn't been revoked in Capsule. Generate a fresh token if in doubt.
- **Provisioned user can't sign in, or a duplicate account appears** - the provider selection was likely wrong when SCIM was enabled. Disable SCIM, re-enable it with **Okta Workforce** selected, and confirm Okta's **Unique identifier field for users** is `userName`.
- **No groups appear in the Capsule group-mapping picker** - groups only appear after Okta pushes them. Enable **Push Groups** on the app, push your groups, then click **Refresh groups** in Capsule.


## Troubleshooting

### Redirected to Okta, but login fails with a SAML error

**Cause**: The SP values in Okta don't match what Capsule generated, or the assertion isn't addressed correctly.

**Solution**:

1. In Okta → app → **General** → **SAML Settings**, confirm the **Single sign-on URL** matches the Capsule **Reply URL (ACS URL)** and the **Audience URI** matches the Capsule **Identifier (Entity ID)** exactly (no trailing spaces) - see Step 3.
2. Confirm **Name ID format** is **EmailAddress** and **Application username** is **Email**.
3. Re-test after saving.


### Login succeeds in Okta but Capsule rejects the assertion

**Cause**: Capsule can't verify the SAML signature - usually because Okta rotated its certificate and Capsule has a stale copy.

**Solution**:

1. In Okta → app → **Sign On** → **View SAML setup instructions**, download the current **X.509 Certificate**.
2. In Capsule, go to **Settings → Single Sign On**, re-upload the certificate under **SSL/TLS Certificate**, and click **Save**.


### "Email" entered on the Capsule login page doesn't redirect to Okta

**Cause**: The email domain isn't in **Authorized Domains** for the connection.

**Solution**:

1. Confirm the address uses one of your configured domains (e.g., `name@your-company.com`).
2. In Capsule → **Settings → Single Sign On**, add the domain to **Authorized Domains** (comma-separated) and click **Save**.


### User reaches Capsule but their name is blank

**Cause**: The `given_name` / `family_name` attribute statements aren't being sent.

**Solution**:

1. In Okta → app → **General** → **SAML Settings** → **Attribute Statements**, confirm `given_name` and `family_name` are present with values `user.firstName` and `user.lastName`.
2. Have the user sign out and back in to refresh their profile.


### User can't sign in at all

**Cause**: The user (or their group) isn't assigned the app in Okta.

**Solution**:

1. In Okta → app → **Assignments**, confirm the user or one of their groups is assigned.
2. Re-test SSO for that user.


## Security & Privacy

- **No passwords reach Capsule** - authentication happens entirely in Okta; Capsule only receives a signed SAML assertion.
- **Your policies stay in force** - MFA, device trust, session lifetime, and conditional access are enforced by Okta at sign-in.
- **Signed assertions** - Capsule validates Okta's SAML signature against your uploaded certificate and rejects anything it can't verify.
- **Owner-only configuration** - only Capsule **Owners** can view or change the SSO connection.
- **Access is governed in Okta** - unassigning a user or group from the Okta app immediately removes their ability to sign in via SSO.
- **Email is the identity key** - Capsule keys accounts on the Name ID (email), so keep it stable to avoid duplicate accounts.


## Support

Need help with SSO?

- **Documentation**: [docs.capsule.security](https://docs.capsule.security)
- **Email Support**: support@capsule.security


When contacting support, please include:

- Your Okta org domain (e.g., `your-org.okta.com`)
- The email domain(s) users sign in with
- Your Okta IdP Single Sign-On URL
- Screenshots of any SAML error pages (the error usually appears after the redirect back from Okta)
- Timestamp when the issue occurred