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
- In the Okta Admin Console, go to Applications > Applications and click Create App Integration.
- Select SAML 2.0 and click Next.
- Set the App name (e.g. "Swamp") and optionally upload a logo. Click Next.
- 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 |
- Leave Default RelayState blank.
- 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.
Collecting Okta metadata
After creating the app, collect three values from the Okta side to complete the Swamp connection:
- Issuer (Entity ID) — found under Sign On > Settings > Issuer. Looks
like
http://www.okta.com/exk.... - Sign on URL — the IdP SSO URL from Sign On > Settings > Sign on URL.
Looks like
https://your-org.okta.com/app/.../sso/saml. - 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
- Open the Swamp sign-in page and enter an email address on the configured domain.
- The sign-in form detects the SSO provider and redirects to Okta.
- 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.