SAML applications

SAML 2.0 is the protocol enterprise IT teams have been deploying for two decades. If your application needs to plug into a customer's IdP (Okta, Entra, Ping, ForgeRock, ADFS) on SAML's terms, you register a SAML application here.

This page covers the SP side from the IntelliAuth tenant admin's perspective. The developer-facing setup for an external IdP lives in SAML — Okta and SAML — Entra.

SAML application vs OIDC application

Conceptually:

OAuth/OIDC application — your tenant is an OAuth Authorization Server. Apps call /oauth2/authorize, get codes, exchange for tokens.
SAML application — your tenant is a SAML Service Provider (SP). An external IdP POSTs SAMLResponses; your tenant verifies them and issues an IntelliAuth session.

A SAML application differs from an OAuth one in:

No client_id / client_secret. Authentication is certificate-based.
No redirect URIs in the OAuth sense. Instead: an ACS URL.
No scope list in the OAuth sense. Instead: attribute mappings.

Register a SAML application

Applications → New application → SAML as the type.

The form has SAML-specific fields:

Name — your label.
Slug — URL-safe identifier; becomes part of the ACS URL.
Description — optional bookkeeping.

Save. You land on the application's detail page. Three things are now visible:

SP Entity ID — https://<tenant>-<org>.<domain>/saml/<slug>. The unique identifier your tenant uses when speaking SAML.
ACS URL — https://<tenant>-<org>.<domain>/auth/saml/<slug>/acs. Where the external IdP will POST the SAMLResponse.
SP Metadata URL — https://<tenant>-<org>.<domain>/saml/<slug>/metadata. A downloadable XML document describing the SP. Many IdPs accept this URL directly instead of asking for Entity ID + ACS URL manually.

Share these three values with whoever runs the external IdP. They configure the IdP-side counterpart and send you back their metadata.

Configure the IdP side

You get back from the external IdP, usually:

The IdP's metadata XML (or a metadata URL).
OR the individual fields: IdP Entity ID, IdP SSO URL, X.509 signing certificate.

Open your SAML application's detail page → SAML tab → IdP metadata. Paste the XML, or paste the URL (the platform fetches it). The form auto-fills IdP Entity ID, SSO URL, and certificate.

Attribute mapping

The IdP sends SAML attributes on the assertion. You map each attribute to a field on the IntelliAuth user record.

Common starter mapping:

SAML attribute	IntelliAuth user field
`email` or `emailaddress`	email
`firstName` or `givenname`	given_name
`lastName` or `surname`	family_name
`displayName` or `name`	name
`groups`	group memberships

The mapping is interactive — once an IdP metadata is loaded and you've received a real SAMLResponse (e.g., from a test sign-in), the platform shows you the actual claims the IdP is sending. Pick which one goes where.

For non-standard claims (department, employee_id, region), map them to custom user attributes.

JIT provisioning

A toggle in the SAML application settings. When on, the first time a user signs in via SAML, the platform creates an IntelliAuth user record from the SAML attributes. When off, the user must already exist; sign-in refuses otherwise.

JIT is the default for most B2B scenarios — your customer's IdP is the source of truth, you just want every employee who comes through to get a user record.

JIT off makes sense when:

You pre-provision users via SCIM or a bulk import.
You want strict control over who can access your tenant — refusing unknown users.

Test the connection

Detail page → Test sign-in (top right).

The platform opens a popup, sends you to the IdP, waits for the SAMLResponse. The result page shows:

Signature verification — pass / fail.
Attribute claims — the raw map of what the IdP sent.
Mapping result — what each claim maps to on the user record.
Errors, if any.

Iterate on the mapping until this returns clean.

Signing your SAMLRequests

For SP-initiated sign-ins, IntelliAuth sends SAMLRequests to the IdP. Some IdPs require signed requests.

Detail page → SAML tab → Sign requests → toggle on. IntelliAuth generates an SP signing certificate; download it via the application's metadata URL and share with the IdP.

Default is unsigned (works for most IdPs; the assertion's own signature is what matters for security).

Certificate rotation

Both sides have certificates:

SP certificate — IntelliAuth's; rotates automatically on a tenant-wide schedule. The new certificate appears in the SP metadata before the old expires, so IdPs that fetch metadata pick it up.
IdP certificate — the external IdP's; rotates on their schedule. If they expose a metadata URL, the platform refreshes it daily and picks up the new cert. If you pasted XML by hand, watch for InvalidSignature errors in audit and refresh manually.

Audit

Every SAML sign-in records an audit event. Filter audit on federation.sso_completed / federation.sso_failed and check the connection slug. Each failed sign-in has the specific SAML error code in details.

For investigation, the SAMLResponse XML is captured for failed attempts (configurable retention; default 7 days). The metadata helps with "what did the IdP actually send" debugging.

Common pitfalls

Clock skew. SAML assertions have tight validity windows (5 minutes typical). Clock drift between the IdP and IntelliAuth causes silent failures. The connection has a "clock skew tolerance" knob (default 30 seconds); widen if persistent.
Stale metadata. If your IdP rotates certificates and you pasted XML by hand, you'll get InvalidSignature on every sign-in until you re-paste. Prefer the metadata URL.
Missing attributes. If a user has no email on the IdP side, IntelliAuth's user record has no email — and if your tenant policy requires email verification, sign-in refuses. Fix on the IdP side, or relax the policy, or map a different claim to email.