A short introduction to SAML 2#
For comprehensive information about SAML 2, please refer to the specification. This guide will just cover a sub section of SAML 2 which is covered by this library.
What is SAML#
SAML, Security Assertion Markup Language, is a standard for authentication and authorization, commonly used to provide single sign on capabilities to web applications. It is especially popular with companies as it usually operates on an organization level, not a user level. With SAML, it is trivial to give every user in your organization access to a service, as long as that service supports SAML.
Key concepts and terms#
- Service Provider#
A service, often a web application, which can be logged into using SAML. If you’re using MiniSAML, you’re building a Service Provider. Service Provider is often shortened to SP.
- Identity Provider#
A web application which manages users and their authentication. An Identity Provider receives SAML Requests and sends SAML Response to Service Providers. MiniSAML does not provide support for building Identity Providers. Identity Provider is often shortened to IdP.
- Issuer#
A unique identifier of each party in SAML. Both a Service Provider and Identity Provider have an Issuer. To a Identity Provider, the Issuer of the Service Provider is called the Audience.
- SAML Request#
A request sent from the Service Provider to the Identity Provider to authenticate a user. MiniSAML generates these for you.
- Relay State#
Extra information contained in a SAML Request which is unrelated to SAML. This is sent back together with the SAML Response in case of successful authentication. The main use-case is to remember the path in your web application the user attempted to access before authentication in order to redirect them there after successful authentication. MiniSAML supports including a Relay State in your SAML Request, but it is your responsibility to retrieve it when processing the SAML Response and to ensure that the value is valid.
- SAML Response#
Sent from the Identity Provider to the Service Provider containing the result of the SAML Request. MiniSAML parses these for you.
- Audience#
The Issuer of a Service Provider. This is used by the Identity Provider to distinguish different Service Providers. Since both the Identity Provider and the Service Provider have an Issuer, MiniSAML refers to the Service Provider Issuer as the Audience. Some Identity Providers refer to Audience as the Entity ID.
- Assertion Consumer Service#
An endpoint on the Service Provider which handles SAML Response sent from the Identity Provider. Assertion Consumer Service is often shortened to ACS.
How does SAML work#
Before using SAML, the Service Provider has to be registered with the Identity Provider. How this is done differs from Identity Provider to Identity Provider and therefore is out of scope for this document.
A user attempts to access a Service Provider and needs to be authenticated.
The Service Provider redirects the user to the Identity Provider with a SAML Request.
The Identity Provider parses the SAML Request, verifies the Service Provider using the Audience specified in the SAML Request, then authenticates the user, for example by asking them for a username and password.
If the authentication on the Identity Provider is successful, the Identity Provider redirects the user back to the Service Provider by sending a HTTP POST request to the Assertion Consumer Service of the Service Provider
The Service Provider parses the SAML Response, validates that it is from the Identity Provider and optionally validates the Relay State and
request_id.
Some Service Providers also support what is called Identity Provider Initiated SSO, in which case the user directly access the Service Provider from the Identity Provider and there is no SAML Request involved, only a SAML Response.