Okta SSO (SAML)

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

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

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.

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

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)

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)

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

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.

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.

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

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.

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.

• 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

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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

Need help with SSO?

• Documentation: 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