Set up SAML with Okta

Let staff sign in to the admin with their Okta account over SAML 2.0, with accounts created on first sign-in and roles taken from Okta groups.

Before you start: an admin account in Spillway (the users.manage permission), BASE_URL set to the site's public address (the SAML URLs handed to Okta are built from it), and an Okta administrator who can create a SAML app integration. Okta's OIDC route is simpler if you can use it; see sso.md.

Steps

1. Spillway: Site settings → Sign-in → Add provider. Protocol SAML, slug okta, label Okta. Save it disabled for now. The screen shows the two URLs Okta needs: the ACS URL https://<your site>/sso/okta/acs and the SP entity id (default https://<your site>/sso/okta/metadata, which also serves the SP metadata XML).
2. Okta: Applications → Create App Integration → SAML 2.0. Single sign-on URL = the ACS URL; Audience URI = the SP entity id; Name ID format EmailAddress; application username Okta username (or email). Under attribute statements add email → user.email, name → user.displayName, and a group attribute statement groups matching the groups you will map.
3. Copy from Okta's Sign on tab: the Identity Provider Single Sign-On URL and the X.509 certificate.
4. Back in Spillway, edit the provider: entry point = the IdP SSO URL, IdP certificate = the PEM text. Turn on just-in-time provisioning, set default roles (for example author), set the group claim to groups and map Okta group names to Spillway roles (CMS Editors → editor, CMS Admins → admin). Optionally restrict allowed domains to your organization's email domain.
5. Test on the provider: Spillway parses the certificate and confirms the SP metadata URL. Then enable the provider and assign the Okta app to a test user.

Check the result

• /admin/login shows a Continue with Okta button.
• Signing in as the test user lands in the admin; Users lists the account with Okta as its sign-in method and the roles from its groups.
• /sso/okta/metadata serves the SP metadata XML.
• The audit log holds an auth.sso_login row for the sign-in.
• A user who is in no mapped group sees "Your groups do not map to any role here" and gets no session.

Notes

• Password login is refused for accounts Okta created; an admin can set a password on one if needed.
• Removing a user from the Okta app does not end an existing Spillway session; delete or edit the user in Spillway to revoke access at once.
• The same steps apply to Shibboleth and InCommon; see sso.md.

Going further

• Enterprise sign-in (SSO) for Entra ID, Google Workspace and Login.gov.
• Types reference: SsoProvider for every setting.
• Security for what each role can do.

Spillway 0.1.0 · Edit this page on GitHub