Skip to main content
SAML SSO lets your users authenticate through their organization’s Identity Provider (IdP), such as Okta, Google Workspace, or JumpCloud. Prelude Auth acts as the SAML Service Provider (SP): it consumes signed assertions from the IdP, provisions or links the matching user, and issues a session.

​
Prerequisites

Before you start, make sure you have:
  • A Prelude account with access to Prelude Auth
  • An Application ID (appID) — see Applications
  • Your Management API key for backend calls
  • A verified custom domain — SAML Service Provider URLs are anchored to your domain
  • Admin access to the Identity Provider you want to connect

​
Supported providers

ProviderIdentifier
Oktaokta
Google Workspacegoogle
JumpCloudjumpcloud

​
How the flow works

Prelude Auth supports both flows defined by SAML 2.0:
  • SP-initiated — your app calls a SAML initiate endpoint, the SDK redirects the user to the IdP, and the IdP posts a signed SAMLResponse back to the connection’s Assertion Consumer Service (ACS) URL. The flow is bound with PKCE so the resulting challenge_token can only be finalized by the browser that started the flow.
  • IdP-initiated — the user clicks the application tile in the IdP dashboard and the IdP posts directly to the ACS URL. No RelayState is involved.
Both flows converge on the ACS endpoint and redirect back to your app with a challenge_token you finalize the same way as social login.

​
Service Provider endpoints

When you create a connection, Prelude Auth derives a unique set of SP endpoints from your domain, the provider identifier, and the generated connection ID:
EndpointPattern
Entity ID (Audience URI)https://${YOUR_DOMAIN}/v1/session/login/saml/${PROVIDER}/${CONNECTION_ID}
ACS URL (Single sign-on URL)…/${CONNECTION_ID}/acs
Metadata URL…/${CONNECTION_ID}/metadata
These values are returned in the sp block of the connection response and are immutable — they are what you register on the IdP side.
Because the SP endpoints embed the connection ID, you create the connection in Prelude first, then copy the generated sp values into your IdP application. The provider guides below walk through the exact ordering.

​
Connection behavior

Every connection carries a behavior block that controls provisioning and login enforcement:
FieldTypeDescription
jit_provisioningbooleanWhen true, just-in-time provisions a new user on first SSO login.
allow_email_account_mergebooleanWhen true, links the SAML identifier to an existing user that owns the same verified email.
email_domain_allowliststring[]Email domains this connection covers. This is the only domain→connection binding, and is required for email-resolved login and for enforce_login.
enforce_loginbooleanWhen true, emails in the allowlist must sign in through SAML — OTP and OAuth are refused for them. See Enforce SSO login.
default_redirect_uristringRedirect URI used for IdP-initiated logins and when an SP-initiated flow omits redirect_uri.

​
Attribute mapping

The mapping block maps assertion attributes to user profile fields (email, first_name, last_name, groups, plus arbitrary custom claims). Sensible per-provider defaults are applied when you omit it — Google Workspace, for example, defaults to the snake_case attribute names it recommends.

​
Provider guides

Okta

Configure an Okta SAML application.

Google Workspace

Configure a Google Workspace custom SAML app.

JumpCloud

Configure a JumpCloud custom SAML application.

​
What’s next?

Enforce SSO login

Require allowlisted email domains to authenticate through SAML.

Web integration

Start a SAML login from the JavaScript SDK.