Skip to main content
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; 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

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

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

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

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

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

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.

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

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