Configuring a SAML Provider
SAML connects the platform to an enterprise identity provider. This article covers configuring the connection; the next covers turning it on and what users experience.
Where to find it
Architect Panel → Integration & Connections:
- SAML Identity Providers — the connections themselves
Architect Panel → Security:
- Certificates — signing certificates
- Authentication Methods — which sign-in routes are enabled
Both sides need configuring
SAML is a two-ended arrangement. Your identity provider needs to know about the platform, and the platform needs to know about the identity provider. A connection that fails is usually one side missing something the other assumed.
Exchange metadata rather than typing
Most identity providers publish a metadata document describing their endpoints and certificate. Using it is faster and removes a class of transcription error — certificate fingerprints and endpoint URLs are long and unforgiving.
Where you must enter values by hand, copy and paste. Do not retype.
Attribute mapping is where connections fail
The identity provider sends attributes about the user; the platform needs to know which is the identifier, which is the e-mail address, and which is the name.
Providers differ enormously in what they call these, and the defaults rarely match. A connection that authenticates successfully and then fails to resolve a user is almost always an attribute mapping problem rather than a certificate one.
Choose a stable identifier
The attribute identifying the user should not change. An e-mail address is tempting and changes when somebody marries or the organisation renames its domain — at which point they become a new person to your system.
Prefer an immutable identifier where the provider offers one, even though it is less readable.
Certificates expire
SAML depends on signing certificates with expiry dates, and an expired one stops all sign-in at once for everybody on that connection.
It is a known date, so diary it well ahead — 60 days is sensible. This is the most common single-sign-on outage there is, and it is entirely preventable.
Agree the changeover
Certificate rotation needs both sides ready. Agree it with whoever runs the identity provider rather than doing it and hoping — a swap done unilaterally takes the connection down until the other side catches up.
Test with a real account
Not an administrator's. A test account with ordinary group membership exercises the attribute mapping and the group resolution in a way an administrator's does not, because administrators frequently bypass exactly the things you need to check.
Keep a record of the arrangement
Who the provider is, who administers it there, which attributes are mapped, and when the certificate expires. This information is needed rarely and urgently, and usually by somebody who was not involved in setting it up.
Worked example
An organisation connects to a client's identity provider by exchanging metadata, maps the provider's immutable identifier rather than the e-mail address, and tests with an ordinary account rather than an administrator's — which surfaced a name attribute mapped to the wrong field. The certificate expiry is diarised at 60 days with both sides named.
Recommendations
- Exchange metadata rather than typing values.
- Map an immutable identifier, not the e-mail address.
- Diary certificate expiry 60 days ahead.
- Test with an ordinary account.