> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up Okta SSO with Serval (SAML)

> Configure SAML 2.0 single sign-on between Okta and Serval, including prerequisites, supported features, catalog setup, and the SAML attributes Serval expects.

This guide walks an Okta administrator through connecting Okta to Serval for SAML 2.0 single sign-on, so your users sign in to Serval with their Okta credentials. Serval brokers SAML through [WorkOS](https://workos.com/); the in-product setup gives you the exact values to paste into Okta.

## Prerequisites

Before you begin, make sure you have:

* **A Serval administrator account**: an account with the **Admin** organization role in the Serval organization you're configuring. Sign-in URL: `https://app.serval.com`.
* **Okta administrative permissions**: a **Super Administrator** (or an admin role that can add and configure OIN applications) in your Okta org.
* **A verified domain in Serval**: verify the email domain your users sign in with under **Organization → Security** in Serval before you enable SSO. SAML sign-in is rejected for users whose email domain isn't verified on your organization.

## Supported features

| Feature                         | Supported                                                                                                   |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| SP-initiated SSO                | Yes                                                                                                         |
| IdP-initiated SSO               | Yes                                                                                                         |
| Just-In-Time (JIT) provisioning | No                                                                                                          |
| User provisioning (SCIM)        | Yes, via [SCIM directory sync](/sections/documentation/platform/org-settings#security-sso-scim-and-domains) |
| Single Logout (SLO)             | No                                                                                                          |
| Force authentication            | Yes                                                                                                         |

<Note>
  Serval does not create accounts through SAML JIT provisioning. To provision and deprovision users automatically, configure **SCIM** alongside SSO from **Organization → Security**.
</Note>

## Add Serval from the Okta Integration Network

1. In the Okta Admin Console, go to **Applications → Applications**.
2. Select **Browse App Catalog**.
3. Search for **Serval** and select it.
4. Select **+ Add Integration**.
5. Set the **Application label** (for example, `Serval`), then select **Done**.

## Configure SAML SSO

Serval generates a unique Service Provider (SP) configuration for your organization. Retrieve those values from Serval, then enter them in the Okta app.

<Steps>
  <Step title="Start SSO setup in Serval">
    In Serval, switch to the **Organization** workspace, open **Settings → Security**, and select **Configure SSO**. This launches a guided setup that displays your organization's **Single Sign-On URL (ACS URL)** and **Audience URI (SP Entity ID)**.
  </Step>

  <Step title="Enter the SP values in Okta">
    In the Serval app in Okta, open the **Sign On** tab, select **Edit**, and enter the values from the previous step:

    * **Single sign-on URL**: the ACS URL from Serval.
    * **Audience URI (SP Entity ID)**: the Audience URI from Serval.
    * **Name ID format**: `EmailAddress`.
    * **Application username**: `Email`.

    Save your changes.
  </Step>

  <Step title="Send the Okta metadata to Serval">
    In the Okta app's **Sign On** tab, copy the **Metadata URL** (or download the IdP metadata / certificate). Provide it in the Serval guided setup so Serval can trust assertions signed by your Okta org.
  </Step>

  <Step title="Assign users and test">
    Assign the Serval app to the users or groups who should have access (**Assignments** tab). Then sign in from the Okta dashboard (IdP-initiated) or from Serval's sign-in page (SP-initiated) to confirm access.
  </Step>
</Steps>

## SAML attribute statements

Serval requires all of the following attributes in the SAML assertion. Add these under **Attribute Statements** in the Okta app's SAML settings.

| Attribute name | Value            |
| -------------- | ---------------- |
| `id`           | `user.id`        |
| `email`        | `user.email`     |
| `firstName`    | `user.firstName` |
| `lastName`     | `user.lastName`  |

<Note>
  `email` identifies the user, and `id` provides a stable identifier that doesn't change if the user's email does. Send all four attributes — sign-in fails if any is missing.
</Note>

## SP-initiated sign-in

Users can start sign-in from Serval directly:

1. Go to `https://app.serval.com`.
2. Enter your work email. Serval detects your organization's SSO domain and redirects you to Okta.
3. Complete authentication in Okta. Serval returns you to the app, signed in.

## Troubleshooting

* **"Profile domain does not belong to the target Organization"**: the signed-in user's email domain isn't verified on your Serval organization. Verify the domain under **Organization → Security**.
* **"Invalid SAML Response"**: the Okta metadata registered in Serval doesn't match the app sending the assertion (for example, after recreating the Okta app). Re-send the current Okta metadata URL to Serval.
* **Locked out after enabling Require SSO**: enabling **Require SSO** makes SSO the only sign-in method for members on a verified domain. If Okta sign-in is unavailable, an administrator can restore access through magic-link sign-in for guest accounts, or contact your Serval representative.

<Warning>
  Turning on **Require SSO** disables password and magic-link sign-in for members on your verified domains. Confirm SSO works end to end for at least one administrator before enforcing it.
</Warning>

If sign-in still fails after these checks, reach out to your Serval representative or Serval support with the time of the attempt and the error message shown.