Skip to main content

OKTA SAML SSO

This page covers configuring Okta as a SAML 2.0 identity provider (IdP) for Swamp single sign-on. After setup, operatives with email addresses on the configured domain sign in via Okta instead of a password.

Prerequisites

  • An Okta admin account with permission to create SAML integrations
  • The email domain to federate (e.g. acmecorp.com)
  • A collective in Swamp that SSO operatives will be auto-added to on first login
  • The Single Sign-On URL and Audience URI (Entity ID) values provided by your Swamp admin — these are generated when the SSO connection is created on the Swamp side

Creating the Okta application

  1. In the Okta Admin Console, go to Applications > Applications and click Create App Integration.
  2. Select SAML 2.0 and click Next.
  3. Set the App name (e.g. "Swamp") and optionally upload a logo. Click Next.
  4. Fill in the SAML settings:
Okta field Value
Single sign-on URL The ACS URL provided by your Swamp admin
Audience URI (SP Entity ID) The Entity ID provided by your Swamp admin
Name ID format EmailAddress
Application username Email
  1. Leave Default RelayState blank.
  2. Click Next, select "I'm an Okta customer adding an internal app", and click Finish.

Attribute statements

Swamp expects three attribute statements on the SAML assertion. Configure these under SAML Settings > Attribute Statements in the Okta app:

Name Name format Value
email Basic user.email
displayName Basic user.displayName

Group attribute statement

Under Group Attribute Statements, add:

Name Name format Filter Value
groups Basic Matches regex .*

The groups claim controls which IdP groups are visible to Swamp. Use a more restrictive regex to limit which Okta groups are sent (e.g. ^swamp-.* to send only groups prefixed with swamp-). Groups are persisted on the operative's record on every SSO login and are available to downstream consumers via the groups claim on the userinfo endpoint.

The attribute name must be exactly groups, with the Basic name format. A namespaced name — the format Entra ID and ADFS emit by default — will not match, and the assertion will be read as carrying no groups at all.

Troubleshooting empty groups

If an operative's idp-group: grants are not matching, the question is whether the assertion carried their groups. A Swamp administrator can answer it directly from the SSO admin console, which records what each SSO sign-in received:

What the diagnostics show What it means
Last written: never No SSO login has provisioned this operative. They have not signed in via Okta yet.
Groups attribute: absent The assertion carried no attribute named groups. Check the Group Attribute Statement, and its name format.
Groups attribute: empty The attribute arrived with no values. The regex filter is likely excluding everything.
Groups attribute: string Exactly one group was sent, and it is recorded.
Groups attribute: array Two or more groups were sent.

If the attribute reads as absent but you expect groups to be sent, the next question is what name the identity provider used. Swamp logs the attribute names of every SAML assertion it accepts — search the application logs for SAML assertion attributes received and the provider id. A namespaced name in that list (http://schemas.microsoft.com/.../claims/groups, for example) means the identity provider is sending groups under a name the connection is not configured to read, rather than not sending them at all.

Group memberships are re-read only at sign-in for SAML connections — there is no background refresh, because a SAML assertion carries no token Swamp could use to re-query the IdP. An operative whose Okta groups changed must sign in again before the change reaches their grants.

Collecting Okta metadata

After creating the app, collect three values from the Okta side to complete the Swamp connection:

  1. Issuer (Entity ID) — found under Sign On > Settings > Issuer. Looks like http://www.okta.com/exk....
  2. Sign on URL — the IdP SSO URL from Sign On > Settings > Sign on URL. Looks like https://your-org.okta.com/app/.../sso/saml.
  3. X.509 Certificate — download from Sign On > SAML Signing Certificates. Use the active certificate in PEM format (starts with -----BEGIN CERTIFICATE-----).

Provide these three values to your Swamp admin to complete the SSO connection configuration.

Assigning operatives

In Okta, go to the application's Assignments tab and assign the operatives or groups who should have access. Only assigned operatives can authenticate via SSO.

When an assigned operative signs in to Swamp for the first time via SSO:

  • Their account is created automatically (no separate sign-up needed)
  • Their email is marked as verified (trusted from the IdP)
  • They are added as a member of the linked collective

Testing the connection

  1. Open the Swamp sign-in page and enter an email address on the configured domain.
  2. The sign-in form detects the SSO provider and redirects to Okta.
  3. Authenticate in Okta. On success, you are redirected back to Swamp and signed in.

To verify group claims are flowing correctly, check the operative's profile or query the userinfo endpoint — the groups field should contain the Okta groups assigned to that operative.

Known limitations

  • Group sync is login-time only. Changes to an operative's Okta group memberships are picked up on their next SSO login, not in real time. Session caching (up to 5 minutes) may delay visibility further.
  • One domain per provider. Each SSO connection covers a single email domain. Organizations with multiple domains need a separate connection per domain.
← PreviousTLS and ProxiesNext →swamp serve