Understand SAML

SAML in 3 minutes

SAML lets you log in to an application with your organisation's account, without the application ever seeing the password.

See also: the SAML history timeline · the OAuth and OpenID Connect one

A picture to understand

Imagine a concert. The application is the venue: it wants to know who comes in, but it does not check your papers itself. The identity provider is your company's accreditation desk: it really knows your identity. At the entrance, the venue sends you to the desk, which hands you a sealed badge bearing your name. The venue only trusts the seal, which it knows how to recognise.

This sealed badge is the SAML assertion. The seal is the signature.

The three actors

You

The user, with their browser. It carries the messages from one site to the other.

The application

The service you want to access. The jargon says "SP", for service provider.

The identity provider

The one that authenticates you: Microsoft Entra ID, Okta, Keycloak, Google Workspace… The jargon says "IdP".

A login in five steps

Youin your browserApplicationthe service (SP)Identity provideryour organisation (IdP) 1 I open the application and I am not logged in yet 2 "Can you identify this person?" request (AuthnRequest), carried by the browser authentication: password, MFA… 3 "Here is their identity, signed" response (Response + Assertion), via the browser 4 I'm logged in the application verified the signature (5)
  1. You open the application. It sees that you are not logged in.
  2. It sends you to your identity provider with a request: "identify this person and send them back to me at this address".
  3. The identity provider authenticates you (password, phone approval…). This step only happens on its side.
  4. It sends you back to the application with a signed message: the assertion (who you are, for which application, until when).
  5. The application checks the signature and the conditions, then opens a session for you.

What the assertion contains

  • Who: the person's identifier (the NameID, often their email).
  • For whom: the recipient application (the Audience) and the exact receiving address (the ACS).
  • Until when: a very short validity period, a few minutes.
  • What else: information about the person (name, groups…), called attributes.
  • The seal: the signature, which proves the message really comes from the identity provider and was not modified.

Why the application trusts the message

Before the first test, the application and the identity provider exchange a kind of technical ID card: the metadata. It holds their names (Entity ID), their addresses and above all the certificate used to recognise the seal. This is the "configuration" part, and it is where almost all problems originate.

What to configure, on each side

Identity provider sideApplication side
The application's name (Entity ID)The identity provider's name (Entity ID)
The address to send the person back to (ACS URL)The address to send them to identify themselves (SSO URL)
Optionally the application's certificateThe identity provider's certificate

A one-character mistake (a trailing slash, http instead of https) is enough to block everything. ID-Kit tells you exactly which value does not match.

And where does ID-Kit fit in?

  • Do you have an application to test? ID-Kit plays the identity provider.
  • Do you have an identity provider to test? ID-Kit plays the application.

To go further: the technical detail, or common errors.

Want to see it for real? ID-Kit plays the role you are missing and shows you each step.

Open my spaceDecode a SAML response