# Okta SSO

Let your team sign in to the Capsule portal with their Okta credentials using SAML 2.0 or OIDC 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 **identity provider (IdP)**; Capsule uses **Auth0** as its identity broker (the **service provider, SP**) and accepts the assertion or ID token Okta issues at sign-in.

Capsule supports two protocols, and you pick **one or the other** for your tenant:

- **SAML 2.0** - Okta posts a signed SAML assertion to Capsule.
- **OIDC** - Capsule exchanges an authorization code with Okta for an ID token.


Both protocols give your users the same login experience and both support SCIM provisioning and group-to-role mappings. See [Choosing a Protocol](#choosing-a-protocol) if you have no existing preference.

> **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 the app integration in Okta, paste Okta's details into Capsule, then copy the 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 returns the user's identity to Capsule - a signed SAML assertion posted to Capsule's ACS URL, or an authorization code that Capsule exchanges for an ID token at the callback URL.
5. Capsule validates the assertion or token 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 app integrations
- A **verified email domain** your users sign in with (e.g., `your-company.com`)


## Choosing a Protocol

If your organization has no standing preference, either protocol is a fine choice. The practical differences:

|  | SAML 2.0 | OIDC |
|  --- | --- | --- |
| Okta object | SAML 2.0 app integration | OIDC app integration (Web Application) |
| Secret you manage | Signing certificate (Okta rotates it) | Client secret |
| Extra Okta config | Attribute statements, and Name ID must be the user's email | None, when you use the Okta org authorization server |
| First and last name | Sent as separate attribute statements | Not available - Okta sends only a combined `name` claim, see [Attribute Mapping](#attribute-mapping) |
| Okta dashboard tile | Needs a separate bookmark app | Works on the app itself, see [IdP-Initiated Login](#idp-initiated-login) |
| SCIM provisioning | Configured on the same app integration | Requires a **second** app integration, see [SCIM Provisioning](#scim-provisioning-optional) |


> The protocol is locked once a connection exists - the other option is greyed out in the portal. To switch protocols, turn off **Enable SSO configuration** and **Save** to remove the current connection, then configure the new one. Users signing in during the gap fall back to email magic links.


## Setup Overview

Setup is a round trip between the Okta Admin Console and the Capsule **Single Sign On** settings. The shape is the same for both protocols:

1. **Create the app integration** in Okta and collect the values Capsule needs
2. **Configure the connection** in Capsule - paste Okta's details, set your domains, then read back the values Capsule generates
3. **Copy Capsule's values** back into the Okta app integration
4. **Assign users** and test


## Step 1: Create the App Integration in Okta

Follow the section for the protocol you chose. Capsule generates its own URLs only after the connection is saved (Step 2), so enter **temporary placeholder URLs** here - you'll replace them in Step 3.

### SAML: create a SAML 2.0 app integration

1. Sign in to your **Okta Admin Console** as an admin.
2. Go to **Applications and Resources** → **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 **This is an internal app that we have created**, 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`)


### OIDC: create an OIDC app integration

1. Sign in to your **Okta Admin Console** as an admin.
2. Go to **Applications and Resources** → **Applications**, then click **Create App Integration**.
3. Select **OIDC - OpenID Connect** as the sign-in method and **Web Application** as the application type, then click **Next**.
4. Give the app a name (e.g., `Capsule Security`) and under **Grant type** leave **Authorization Code** checked. Capsule uses the back-channel authorization-code flow, so no other grant type is needed.
5. Under **Sign-in redirect URIs**, enter Capsule's callback URL: `https://<capsule-login-domain>/login/callback`
> Capsule shows the exact value as **Callback URL (Redirect URI)** after you save the connection in Step 2. If you don't have it yet, enter a placeholder such as `https://example.com/placeholder` and correct it later in Step 3.
6. Remove any **Sign-out redirect URIs** - Capsule does not send a logout request to Okta.
7. Under **Assignments**, either pick the groups that should have access now or select **Skip group assignment for now** and assign users in Step 4. Click **Save**.
8. On the app's **General** tab, under **Client Credentials**, confirm **Client authentication** is **Client secret**, then copy:
  - **Client ID** - this is the **Client ID** you enter in Capsule
  - **Client secret** - this is the **Client Secret** you enter in Capsule
> Unlike some providers, Okta lets you read the client secret again later. If you ever rotate it, update it in Capsule at the same time or SSO stops working.
9. Determine the **Issuer URL** you'll enter in Capsule. Use your Okta org authorization server:

```
https://<your-org>.okta.com
```
If your org uses an Okta custom sign-in domain, use that hostname instead (e.g., `https://login.your-company.com`).
> Capsule derives the discovery document by appending `/.well-known/openid-configuration` to exactly the URL you enter, so use the bare origin with no trailing slash and no extra path.
You can also point Capsule at a **custom authorization server** (`https://<your-org>.okta.com/oauth2/<authorization-server-id>`), but then you must check its claim configuration - see the note below.
10. No further Okta configuration is required for the org authorization server. It returns the `email` claim Capsule needs whenever the `email` scope is requested, and Capsule always requests `openid profile email`.
> **If you use a custom authorization server**, open **Security** → **API** → your authorization server → **Claims** and make sure the claim carrying the user's email is configured with **Include in token type** set to **ID Token** and **Always**. By default Okta only puts configured claims in the ID token when the request does not also return an access token, which is never the case in the authorization-code flow. Auth0 does not call the IdP's `/userinfo` endpoint for OIDC connections, so a claim that is missing from the ID token is missing from Capsule, and login has nothing to match the account on.


## Step 2: Configure the Connection in Capsule

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

1. Sign in to the Capsule portal as an **Owner** and go to **Settings → Single Sign On**.
2. Turn on **Enable SSO configuration**, then choose your protocol - **SAML** or **OIDC**.
3. Set **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.
4. Fill in the protocol-specific fields.
**SAML:**
  - **Sign In Endpoint** - paste the Okta **Sign on URL** from Step 1.
  - **SSL/TLS Certificate** - upload the Okta signing certificate from Step 1 (`.pem`, `.crt`, or `.cer`). Capsule uses it to verify Okta's SAML signature.
**OIDC:**
  - **Client ID** - paste the **Client ID** from the app's General tab.
  - **Client Secret** - paste the **Client secret** from the app's General tab.
  - **Issuer URL** - the issuer you determined in Step 1, e.g. `https://<your-org>.okta.com`. Capsule resolves the discovery document from it.
5. Click **Save**.
6. After saving, the **Identity Provider Configuration** section appears with the values Okta needs. Keep this page open for Step 3:
  - **SAML** - **Identifier (Entity ID)** and **Reply URL (ACS URL)**
  - **OIDC** - **Callback URL (Redirect URI)**
Both protocols also show an **IdP-initiated login URL**. Okta doesn't need it for sign-in to work; you only need it if you want to give users a working tile on their Okta dashboard. See [IdP-Initiated Login](#idp-initiated-login).


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

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

### SAML

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.


### OIDC

1. In Okta, open the app → **General** tab → **General Settings** → **Edit**.
2. Under **Sign-in redirect URIs**, make sure the list contains the Capsule **Callback URL (Redirect URI)** exactly - same scheme, host, and path, no trailing slash. Remove the placeholder from Step 1.
3. Click **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.

> The Capsule tile on the Okta dashboard needs a little extra setup before it works, and what that is depends on the protocol - see [IdP-Initiated Login](#idp-initiated-login).


## IdP-Initiated Login

Capsule sign-in is always **service-provider-initiated**: the flow begins at Capsule, which picks the connection (from the email domain the user enters, or from an organization hint on the link) and then redirects to Okta. Whether you can offer users a launch point on their Okta dashboard depends on the protocol.

Both routes below use the **IdP-initiated login URL** that Capsule shows under **Settings → Single Sign On** → **Identity Provider Configuration**. It has the form:

```
https://<capsule-portal-domain>/api/v1/auth/login?redirect_url=<capsule-portal-domain>&org=<your-organization-id>&auth0_org=<your-sso-organization-id>
```

> Use the URL exactly as Capsule gives it to you, including the query string. The `org` and `auth0_org` parameters are what make a dashboard tile behave like IdP-initiated login: together they route the request straight to your organization's SSO connection, so the user is never asked for their email and goes directly to Okta, or straight into Capsule if they already have a live Okta session.
Do not point a tile at Capsule's **Callback URL (Redirect URI)**, or at an Auth0 `/authorize` URL. Both only accept requests belonging to a login Capsule already started, and return an error page.
If the tile opens Capsule but still asks for the user's email, one of the two parameters was dropped - Capsule only applies the hint when both are present, and otherwise falls back to the email prompt rather than failing. Re-copy the URL from the settings page.


### SAML

Capsule does **not** support IdP-initiated SAML sign-in. An unsolicited SAML response sent straight from Okta will not complete a login, so the Capsule tile on the Okta dashboard is a dead end.

Hide it: open the app → **General** → **App Visibility** and uncheck **Display application icon to users**. Point users at the Capsule login page instead.

If you want to keep a tile on the dashboard, add a **Bookmark App** as a launcher: **Applications** → **Browse App Catalog** → search for **Bookmark App** → **Add Integration**, set its **URL** to the Capsule IdP-initiated login URL above, and assign the same users and groups. The bookmark only opens a link, so the SAML app still does the authentication.

### OIDC

IdP-initiated login does not exist in OIDC - the protocol has no equivalent of an unsolicited SAML response. Every OIDC login is started by the service provider.

You can still give users a working dashboard tile, and unlike some providers you don't need a second app for it: Okta launches an OIDC app's tile by sending the browser to the app's **Initiate login URI**, which then starts the normal service-provider-initiated flow.

1. Copy the **IdP-initiated login URL** from Capsule.
2. In Okta, open the app → **General** tab → **General Settings** → **Edit**, and in the **Login** section set:
  - **Login initiated by** - **Either Okta or App**
  - **Application visibility** - check **Display application icon to users**
  - **Login flow** - **Redirect to app to initiate login (OIDC Compliant)**
  - **Initiate login URI** - paste the Capsule IdP-initiated login URL
3. Click **Save**, then confirm the tile works from a test user's **My Apps** dashboard.


> Okta adds its own `iss` parameter when it opens the Initiate login URI. That is expected; Capsule ignores parameters it doesn't use, so leave the URL as copied.
Do not choose **Send ID Token directly to app (Okta Simplified)** for the login flow. Capsule has no endpoint that accepts an unsolicited ID token, so the tile fails.


If you created a second app integration for SCIM (see [SCIM Provisioning](#scim-provisioning-optional)), uncheck **Display application icon to users** on it, so users see one working tile instead of two.

## Attribute Mapping

### SAML attribute statements

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

### OIDC claims

Capsule requests the `openid profile email` scopes and reads the claims from the ID token:

| ID token claim | Source | Maps to in Capsule | Required |
|  --- | --- | --- | --- |
| `sub` | Okta | User identity (unique ID) | Yes |
| `email` | `email` scope | Email, account linking | Yes |
| `name` | `profile` scope | Display name | No |


Because Auth0 does not call Okta's `/userinfo` endpoint for OIDC connections, a claim that is missing from the ID token is missing from Capsule.

That matters here because Okta returns a reduced ID token whenever it also issues an access token, which is always the case in the authorization-code flow. The reduced token still carries `email` and `name`, which is everything Capsule needs, but `given_name` and `family_name` are only available from `/userinfo`. Users therefore get a display name from `name` rather than separate first and last names. Choose SAML if you need those as distinct fields.

## 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 either SSO connection type, SAML or OIDC - 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 SSO.

> **Using OIDC? SCIM needs a second Okta app integration.** Okta does not offer SCIM provisioning on OIDC app integrations, so an OIDC app has nowhere to enter Capsule's SCIM endpoint. Create a **second app integration using SAML 2.0** used only for provisioning (same steps as the SAML app in Step 1, but leave the placeholder URLs in place and never configure it in Capsule) and set SCIM up there. Sign-in keeps running through your OIDC app; the Capsule side is identical either way. Background: [Okta - Configure SCIM for a custom OIDC app](https://support.okta.com/help/s/article/configure-scim-for-a-custom-oidc-app).
The trade-off is that assignment lives in two places: a user must be assigned to the **OIDC app** to sign in, and to the **provisioning app** to be created and deactivated by SCIM. Assign the same users and groups to both.
The provisioning app can never complete a login, so uncheck **Display application icon to users** on it (**General** → **App Visibility**) to keep users from trying.


### Prerequisites

- 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, select **Okta Workforce**.
> Capsule pre-selects Okta Workforce only for SAML connections, by recognizing an Okta Sign In Endpoint. **On an OIDC connection there is no detection and the dropdown defaults to 'Other', so you must select Okta Workforce yourself.**
The provider selection controls how Capsule matches SCIM-provisioned users to SSO 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 app that will handle provisioning → **General** tab → **App Settings** → **Edit**. Under **Provisioning**, select **SCIM**, then **Save**. A **Provisioning** tab appears on the app.
> On an OIDC connection this is the second, SAML-based app integration described above, not the OIDC 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. The picker lists the built-in system roles alongside any custom roles your tenant has defined, and shows the permissions each one grants. 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 is granted **every** matching role, and their effective permissions are the union of those roles.
- 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.
- **Users are provisioned but can't sign in (OIDC)** - they are assigned to the provisioning app but not to the OIDC app. Assignment on the provisioning app only drives SCIM; sign-in access comes from the OIDC app.


## Troubleshooting

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


### SAML: 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**.


### OIDC: Okta shows a redirect URI mismatch

**Cause**: The **Sign-in redirect URIs** list in Okta doesn't contain Capsule's callback URL.

**Solution**:

1. In Capsule → **Settings → Single Sign On**, copy the **Callback URL (Redirect URI)**.
2. In Okta → app → **General** → **General Settings** → **Edit**, add it to **Sign-in redirect URIs** exactly as shown, remove the Step 1 placeholder, and **Save**.


### OIDC: saving the connection fails, or Capsule can't reach Okta

**Cause**: The Issuer URL is wrong, so the discovery document can't be resolved.

**Solution**:

1. Confirm the value is the bare origin of your Okta org (`https://<your-org>.okta.com`) or your Okta custom sign-in domain, with no trailing slash and no path.
2. Open `<issuer-url>/.well-known/openid-configuration` in a browser - it must return JSON whose `issuer` matches what you entered.
3. If you are using a custom authorization server, include its full path: `https://<your-org>.okta.com/oauth2/<authorization-server-id>`.


### OIDC: login completes at Okta but Capsule can't sign the user in

**Cause**: The ID token has no `email` claim, so Capsule has nothing to key the account on.

**Solution**:

1. If you are using a custom authorization server, set the email claim's **Include in token type** to **ID Token** and **Always** (**Security** → **API** → your authorization server → **Claims**). Okta otherwise leaves it out of the ID token whenever an access token is also issued, and Capsule never calls `/userinfo`.
2. Confirm the user has an email address on their Okta profile.
3. Switching the Issuer URL to the org authorization server (`https://<your-org>.okta.com`) also resolves this, since it always includes `email` for the `email` scope.


### OIDC: sign-in worked and suddenly stopped for everyone

**Cause**: The Okta client secret was rotated or removed.

**Solution**:

1. In Okta → app → **General** → **Client Credentials**, copy the current **Client secret**.
2. In Capsule → **Settings → Single Sign On**, paste it into **Client Secret** 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**.


### The Okta dashboard tile doesn't sign the user in

**Cause**: The tile isn't pointing at Capsule's IdP-initiated login URL, or the app is using a login flow Capsule can't accept.

**Solution**: See [IdP-Initiated Login](#idp-initiated-login) - OIDC apps need the **Initiate login URI** set and **Login initiated by** set to **Either Okta or App**; SAML apps need a separate bookmark app, since Capsule cannot accept an unsolicited SAML response.

### User reaches Capsule but their name is blank

**Cause**: The name claims or attributes aren't reaching Capsule.

**Solution**:

1. **SAML**: in Okta → app → **General** → **SAML Settings** → **Attribute Statements**, confirm `given_name` and `family_name` are present with values `user.profile.firstName` and `user.profile.lastName`.
2. **OIDC**: confirm the user has a first and last name on their Okta profile, which is what Okta composes the `name` claim from. Note that OIDC connections never receive `given_name` and `family_name` separately - see [Attribute Mapping](#attribute-mapping).
3. 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 or an ID token.
- **Your policies stay in force** - MFA, device trust, session lifetime, and sign-on policies are enforced by Okta at sign-in.
- **Verified responses** - Capsule validates Okta's SAML signature against your uploaded certificate, and validates OIDC ID tokens against the signing keys published by your Okta issuer, rejecting anything it can't verify.
- **Owner-only configuration** - only Capsule **Owners** can view or change the SSO connection. The client secret is write-only once saved.
- **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 email Okta sends (SAML Name ID, or the OIDC `email` claim), 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`)
- Which protocol you configured - **SAML** or **OIDC**
- The email domain(s) users sign in with
- For SAML, your Okta Sign on URL; for OIDC, your Issuer URL and Client ID (never the client secret)
- Screenshots of any error pages (the error usually appears after the redirect back from Okta)
- Timestamp when the issue occurred