How SAML works

How SAML 2.0 single sign-on works: the Organization's two SAML configurations, the sign-ins they serve, the sign-in flow, sign-in started from the identity provider, and what the identity provider must send.

With SAML 2.0 single sign-on, users sign in with their account in your identity provider (IdP). Any IdP that supports SAML 2.0 can be used; for Microsoft Entra ID there is a step-by-step guide. In SAML terms, the IdP authenticates the user and the platform is the service provider (SP). On these pages, “the platform” means the service the user signs in to: the Admin Portal, the Self-Service Portal or the Captive Portal. The platform redirects the user to the IdP, and the IdP returns a signed response that identifies the user.

An Organization has two SAML configurations, one for the Admin Portal and one for the Self-Service Portal. Each has its own Entity ID and Reply URL, so each is registered as a separate application in the IdP.

	Admin Portal	Self-Service Portal	Captive Portal
Configured under	Admin Access Control → Authentication	Selfservice Access Control → Authentication	Uses the Self-Service Portal configuration
Users	Organization administrators	End users: residents, group administrators, hosts, delegated administrators	Guests on a Sign-In Context’s network
Access decided by	Roles from the SAML configuration	Each Service Context’s Self-Service settings	The Sign-In Context’s Access Policies
Other sign-in methods	Form Login, always on	Email Magic Link, can be turned off	The Captive Portal’s other Sign In Modules

The Captive Portal has no SAML configuration of its own. The SAML SSO module signs guests in through the Self-Service Portal configuration, so changes to that configuration also apply to Captive Portal sign-in.

Only an Organization Owner can change the SAML configurations.

The steps below are the general SAML 2.0 sign-in when it starts on the platform’s sign-in page (service-provider initiated sign-in). The flow is the same for the Admin Portal, the Self-Service Portal and the Captive Portal; only the page the user starts on differs. Sign-in that starts in the IdP is described in the next section.

The user starts sign-in on the platform's sign-in page

The user clicks the SAML button on the Admin Portal or Self-Service Portal sign-in page, or chooses SAML on the Captive Portal.
The platform redirects the user to the IdP

The browser is redirected to the IdP’s Login URL with a SAML request, signed with the platform’s signing certificate.
The IdP authenticates the user

Passwords, MFA and conditional access are handled by the IdP and are not sent to the platform.
The IdP returns a signed response

The browser posts the response to the configuration’s Reply URL. The platform verifies the signature with the IdP X.509 Certificate and checks that the response comes from the configured IdP Identifier/EntityID and is addressed to the configuration’s Identifier (Entity ID).
The platform signs the user in

The platform reads the username from the response, and for the Admin Portal also the role. See How the username is chosen and Admin Portal roles.

Sign-in normally starts on the platform’s sign-in page. To start it from the IdP instead, for example from Entra’s Test button or a tile in My Apps, set the application’s Relay State in the IdP:

admin for the Admin Portal configuration.
selfservice for the Self-Service Portal configuration.

A sign-in started from the IdP without a Relay State is rejected. Captive Portal sign-in can only be started from the Captive Portal.

What the IdP must send

A signed response or assertion. The IdP must sign the response, the assertion, or both. Entra signs the assertion by default.
A username. The email-address claim, the username attribute or the Name ID. See How the username is chosen.
Unencrypted assertions. Assertion encryption is not supported. Leave it off in the IdP.
Correct time. The platform allows up to five minutes of clock difference. Responses from an IdP whose clock is further off are rejected.

The platform trusts one IdP certificate at a time. When the IdP starts signing with a new certificate, update IdP X.509 Certificate in the configuration at the same time; responses signed with the other certificate are rejected. See SAML configuration.