This is a series blog posts that deep dives into the world of SAML:
SAML 2.0 Explained in Simple Words - Part I: Intro and Overview
SAML 2.0 Explained in Simple Words - Part II: SAML Flows
SAML 2.0 Explained in Simple Words - Part III: SAML Model and Best Practices
In SAML 2.0 Explained in Simple Words - Part I, we looked at the details of SAML Metadata. Let's continue on this discussion and see how the metadata is exchanged between IDP and SP so that a trusted relationship can be established.
1. Exchange of Metadata
As seen from previous post, IDP metadata and SP metadata are XML-based data containing important information for the SAML entity (IDP and SP).
IDP metadata should be loaded into SP so that IDP can be recognized by SP. Vice versa, SP metadata should be loaded into IDP so that SP can be recognized by IDP.
In reality, there is no specific standard ways required to load those information into each party. We can send the metadata to each party as email attachment, or publish it online and let the other party to retrieve it via URL. The thing once the metadata information is received, it needs to be updated in the IDP/SP system. A lot of times, an IDP is a well developed IAM platform, an engineer can directly import the SP metadata file into it. On the other hand, SP could be an in-house developed application, and there is usually no straight-forward import function. In this case, a developer will extract the key values from IDP metadata and manually input into SP side.
All in all, the key information from IDP metadata needs to be configured in SP, and the key information from SP metadata needs to be configured in IDP.
2. How SAML Works
Now that we have established the trust relationship between IDP and SP, we can start to look at how SAML flow really works under the hood.
2.1 SAML Messages
SAML Messages in SAML are XML-based to convey SAML information between IDP and SP. For example, in the SP-initiated flow, SP will first send a SAML Request message to IDP and later IDP will send a SAML Response message back to SP. During the transport time, the XML-based content will be encoded using Base64.
Here is an example of an encoded sample SAML request:
PHNhbWxwOkF1dGhuUmVxdWVzdCB4bWxuczpzYW1scD0idXJuOm9hc2lzOm5hbWVzOnRjOlNBTUw6Mi4wOnByb3RvY29sIiB4bWxuczpzYW1sPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6YXNzZXJ0aW9uIiBJRD0iT05FTE9HSU5fODA5NzA3ZjAwMzBhNWQwMDYyMGM5ZDlkZjk3ZjYyN2FmZTlkY2MyNCIgVmVyc2lvbj0iMi4wIiBQcm92aWRlck5hbWU9IlNQIHRlc3QiIElzc3VlSW5zdGFudD0iMjAxNC0wNy0xNlQyMzo1Mjo0NVoiIERlc3RpbmF0aW9uPSJodHRwOi8vaWRwLmV4YW1wbGUuY29tL1NTT1NlcnZpY2UucGhwIiBQcm90b2NvbEJpbmRpbmc9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMDpiaW5kaW5nczpIVFRQLVBPU1QiIEFzc2VydGlvbkNvbnN1bWVyU2VydmljZVVSTD0iaHR0cDovL3NwLmV4YW1wbGUuY29tL2RlbW8xL2luZGV4LnBocD9hY3MiPg0KICA8c2FtbDpJc3N1ZXI+aHR0cDovL3NwLmV4YW1wbGUuY29tL2RlbW8xL21ldGFkYXRhLnBocDwvc2FtbDpJc3N1ZXI+DQogIDxzYW1scDpOYW1lSURQb2xpY3kgRm9ybWF0PSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoxLjE6bmFtZWlkLWZvcm1hdDplbWFpbEFkZHJlc3MiIEFsbG93Q3JlYXRlPSJ0cnVlIi8+DQogIDxzYW1scDpSZXF1ZXN0ZWRBdXRobkNvbnRleHQgQ29tcGFyaXNvbj0iZXhhY3QiPg0KICAgIDxzYW1sOkF1dGhuQ29udGV4dENsYXNzUmVmPnVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMDphYzpjbGFzc2VzOlBhc3N3b3JkUHJvdGVjdGVkVHJhbnNwb3J0PC9zYW1sOkF1dGhuQ29udGV4dENsYXNzUmVmPg0KICA8L3NhbWxwOlJlcXVlc3RlZEF1dGhuQ29udGV4dD4NCjwvc2FtbHA6QXV0aG5SZXF1ZXN0Pg==The decoded XML content is
2.2 SAML Bindings
In SAML, bindings are methods used to transport SAML messages between IDP and SP. There are several bindings defined in the SAML specification:
HTTP POST Binding
HTTP Redirect Binding
HTTP Artifact Binding
SOAP Binding
2.2.1 HTTP POST Binding
This is the most frequently used binding method. The SAML messages are transported via HTTP POST requests, where the message content is in the payload of an HTML form.
2.2.2 HTTP Redirect Binding
This method is sometimes used as well. The SAML message are transported via HTTP GET requests. The message is transported as a URL query string parameter called "SAMLRequest".
2.2.3 HTTP Artifact Binding
This binding is less used today. It doesn't send the full SAML message in the HTTP call, but instead, using an intermediary token as an artifact. And then, once SP receives the artifact, it calls the IDP's ArtifactResolutionService (ARS) endpoint to exchange the artifact for the full content.
The artifact token is an opaque identifier ( meaning some random string to represent an 'ID') transported in the HTTP response from IDP to SP. Then the exchange of artifact for full response content happens on a backend socket channel, which is NOT HTTP.
2.2.4 SOAP Binding
This binding, as its name, uses SOAP (Simple Object Access Protocol) messaging framework to transport SAML messages. This is less used today as well.
2.3 SP-Initiated Flow with HTTP POST Binding
Since HTTP POST Binding is mostly used nowadays, let's take a look at the SP-Initiated flow again (shown in SAML 2.0 Explained in Simple Words - Part I), but this time with more details.
When user accesses the service from SP, SP detects no active user session exists, so it needs redirects user to IDP for authentication. Note here a SAML Request is generated by SP and forwarded to IDP's SingleSignOnService Endpoint via HTTP POST.
SingleSignOnService Endpoint is the target at IDP to invoke the SAML flow and HTTP POST is a binding method, i.e. how SAML request should be sent from SP to IDP. Although there are other binding methods, e.g. HTTP Redirect and Artifact Binding, it is HTTP POST that is mostly used. Then let's understand this SAML Request with more details.
2.3.1 SAML Request
A SAML Request (or AuthnRequest) is a message from SP to IDP, requesting IDP to issue a SAML Response describing the properties of a user after the user authenticates to the IDP. This happens in the SP-Initiated flow.
Here is an example SAML Request in the XML format:
Some key elements are highlighted.
Version - Indicates it is SAML 2.0
IssueInstant - The date and time the SAML request was issued. This field is used to ensure that the message is not replayed or reused after a certain period of time
Destination - The entityID of the IDP that this message is supposed to be sent to
Protocol Binding - The binding method used to transmit SAML messages
AssertionConsumerServiceURL - The ACS URL at SP where IDP will return the SAML response to
Issuer - The entityID of SP
SignatureValue - The signature value (redacted in the example) of the SAML request
X509Certificate - The public cert (redacted in the example) that can be used to verify the signature of this request
NameIDPolicy - The NameIDFormat that IDP should use in the SAML Response
RequestedAuthnContext - The level of authentication that is required by the SP. This may include information such as authentication method, strength of authentication and any additional context needed
Not all elements listed above are required and from time to time, some of the elements are omitted. For example, if AssertionConsumerServiceURL is not specified in the request, IDP usually has a default one that's preconfigured for this SP during metadata exchange, and when sending the SAML Response back, it will use the default AssertionConsumerServiceURL.
The signature information is not required in the SAML Request, but is always good to have. In this case, IDP can always verify the signature using the Public Cert provided (how to verify signature is outside the scope of this post) to make sure the request is not tampered.
The NameIDFormat is important too, as it depicts how the subject value (the value that identifies the user authenticated to IDP) returned in the SAML response should be interpreted by SP. For example, it's shown as 'emailAddress' in the example, so in the SAML response, the subject value should be interpreted as an email value.
RequestedAuthnContext provides a mean for SP to ask IDP to authenticate the user with a specific authentication mechanism. For example, if SP specifie PasswordProtectedTransport in the SAML Request, the IDP knows it has to authenticate the user through login/password, protected by SSL/TLS. In turn, IDP will also show in the SAML response which mechanism it used to authenticate the user through AuthnContextClassRef. AuthnContextClassRef is required in the SAML Response.
2.3.2 SAML Response and Assertion
Once browser sends the SAML Request to IDP, it will ask user to login to IDP (if no active user session presented). Once user authenticated to IDP, it will pull the user profile from the User Directory and generate a SAML Response, which will be sent back to SP's ACS endpoint.
The format of SAML Response is similar to SAML Request. However, the major component in SAML Response is the SAML Assertion.
SAML Assertion
A SAML Assertion is a part in the SAML where all necessary user profile information e.g. email, first name, last name, role and etc, as well as the authentication context/status are present.
Here is an Assertion example:
Some key elements are highlighted:
Issuer - The entityID of IDP
Subject - The user who has been authenticated, presented in a specified NameIDFormat
NotOnOrAfter - Indicate how long this assertion will be valid for
Conditions - Conditions that must be met for the assertion to be considered valid
Audience - The entityID of the target SP who this message is intended for
AuthnContext - The level of authentication context that happened with this user authentication
Attribute - List of additional user attributes such as first name, last name, role and etc.
As you can see, with the authentication contexts and identity profiles presented in the assertion, SP who receives those information has what is necessary to confirm a user identity. Yet, to properly send the SAML Assertion back to SP, it needs a wrapper following the SAML protocol.
SAML Response
An example SAML Response looks like below. Assertion is still the main part, but there are some other added entries to make it a valid SAML Response.
Highlighted elements:
Response - Indicate this is a SAML response instead of SAML request
Issuer - The entityID of IDP
SignatureValue - The signature value for the entire SAML response message
X509Certificate - The public certificate that is used to verify the signature
StatusCode - The status of the SAML flow, success, requestDenied and etc.
Once the SP receives the SAML response and verify the signature to make sure the data integrity, SP can extract identity information from the Assertion and create a user session and set browser cookie.
2.4 IDP-Initiated Flow with HTTP POST Binding
The IDP-Initiated Flow is similar to the SP-Initiated Flow, with less steps.
IDP-Initiated flow is used from time to time. This could be based on various reasons. For example, IDP just finishes some other function and would like to trigger the SAML flow, or SP doesn't support SP-Initiated flow well.
Regarding the flow, instead of accessing SP, the browser directly accesses IDP and a login page is present. Once user finishes authentication at IDP, the remaining steps are the same as in SP-Initiated flow.
One thing to note is that IDP needs to know which SP to forward the SAML Response to if there are multiple SP. This could be done by passing a URL parameter to IDP when triggering the IDP-initiated flow or other means that IDP supports.
3. Sum Up
In this post, we continue our exploration of SAML 2.0 protocol. Metadata Exchange provides established a trusted foundation between IDP and SP. SAML Messages are Base64 encoded XML data to be transported between IDP and SP. There are different SAML bindings to define how SAML data and information are exchanged, where HTTP POST binding is the most popular one. Then we looked at SAML request and SAML response, where Assertion is a major component in the latter.
We will continue our SAML exploration in SAML 2.0 Explained in Simple Words - Part III.