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.

​
How setup works

Setup is a round trip between Serval and Okta. Serval brokers SAML through WorkOS, and the in-product Configure SSO flow gives you the values you need and collects the one value Okta produces:
  1. In Serval, start Configure SSO to get your connection ID (and the SP endpoints derived from it).
  2. In Okta, add Serval from the catalog and enter that connection ID.
  3. Back in Serval, paste your Okta metadata so Serval trusts your identity provider.
Keep the Serval Configure SSO screen open in one tab and the Okta Admin Console in another — you’ll move between them.

​
Prerequisites

  • 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. SAML sign-in is rejected for users whose email domain isn’t verified on your organization.

​
Supported features

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

​
Set up SSO

1

Get your Serval SSO connection ID

In Serval, switch to the Organization workspace, open Settings → Security, and select Configure SSO.Copy your connection ID — a short identifier like conn_01ABC…. It’s shown as your Audience URI (SP Entity ID) and as the last segment of your ACS URL (https://auth.workos.com/sso/saml/acs/<connection-id>).Leave this screen open. You’ll return to it in the last step to hand Okta’s metadata back to Serval.
2

Add Serval from the Okta Integration Network

In the Okta Admin Console, go to Applications → Applications → Browse App Catalog, search for Serval, and select + Add Integration.On the General Settings page, set the Application label (for example, Serval) and paste your Serval SSO Connection ID from the previous step into the connection ID field. Okta uses it to build your ACS URL and Audience URI automatically, so you don’t enter any URLs by hand. Select Done.
Add Serval from the catalog — don’t create a custom SAML app. The catalog app builds the SAML endpoints from your connection ID; you only supply the connection ID and, later, your Okta metadata.
3

Add the SAML attribute statements

Open the Serval app’s Sign On tab and confirm the populated settings:
  • Single sign-on URL (ACS URL): https://auth.workos.com/sso/saml/acs/<your-connection-id>
  • Audience URI (SP Entity ID): <your-connection-id>
  • Name ID format: EmailAddress
  • Application username: Email
Then add the four attribute statements below. All four are required.
4

Send your Okta metadata to Serval

This is what lets Serval trust logins from your Okta org — SSO fails until you complete it.On the Serval app’s Sign On tab in Okta, copy the Metadata URL (or download the IdP metadata / certificate). Return to the Serval Configure SSO screen from step 1 and provide it where prompted.
5

Assign users and test

On the app’s Assignments tab, assign Serval to the users or groups who should have access. Then confirm sign-in works both ways: from the Okta dashboard (IdP-initiated) and from Serval’s sign-in page (SP-initiated).

​
SAML attribute statements

Serval requires all four attributes below. Add them under Attribute Statements in the Okta app’s SAML settings.
email identifies the user, and id is a stable identifier that doesn’t change if their email does. Send all four — 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 Serval has doesn’t match the app sending the assertion. This happens if you recreate the Okta app or rotate its signing certificate. Re-run Configure SSO in Serval and send the current Okta Metadata URL again.
  • Sign-in prompts you to verify a domain: the email domain you’re signing in with isn’t verified on the Serval organization. Add and verify it under Organization → Security.
  • Locked out after enabling Require SSO: 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.