Skip to main content

SAML Protocol

info

This content is adapted from Okta documentation.

SAML is mostly used as a web-based authentication mechanism as it relies on using the browser agent to broker the authentication flow. At a high-level, the authentication flow of SAML looks like this:

samlflow

  • A Service Provider (SP) is the entity providing the service, typically in the form of an application.

  • An Identity Provider (IdP) is the entity providing the identities, including the ability to authenticate a user. The Identity Provider typically also contains the user profile: additional information about the user such as first name, last name, job code, phone number, address, and so on. Depending on the application, some service providers may require a very simple profile (username, email), while others may require a richer set of user data (job code, department, address, location, manager, and so on).

  • A SAML Request, also known as an authentication request, is generated by the Service Provider to "request" an authentication.

  • A SAML Response is generated by the Identity Provider. It contains the actual assertion of the authenticated user. In addition, a SAML Response may contain additional information, such as user profile information and group/role information, depending on what the Service Provider can support.

  • A Service Provider Initiated (SP-initiated) sign-in describes the SAML sign-in flow when initiated by the Service Provider. This is typically triggered when the end user tries to access a resource or sign in directly on the Service Provider side, such as when the browser tries to access a protected resource on the Service Provider side.

  • An Identity Provider Initiated (IdP-initiated) sign-in describes the SAML sign-in flow initiated by the Identity Provider. Instead of the SAML flow being triggered by a redirection from the Service Provider, in this flow the Identity Provider initiates a SAML Response that is redirected to the Service Provider to assert the user's identity.

Key Notes
  • The Service Provider never interacts with the Identity Provider. A browser acts as the agent to carry out all the redirections.
  • The Service Provider needs to know which Identity Provider to redirect to before it has any idea who the user is.
  • The Service Provider doesn't know who the user is until the SAML assertion comes back from the Identity Provider.
  • This flow doesn't have to start from the Service Provider. An Identity Provider can initiate an authentication flow.

Understanding The Role Of Service Providers​

A SAML IdP generates a SAML response based on configuration that is mutually agreed to by the IdP and the SP. After receiving the SAML assertion, the SP needs to validate that the assertion comes from a valid IdP and then parse the necessary information from the assertion: the username, attributes, and so on.

To do this, the SP requires at least:

  • Certificate - The SP needs to obtain the public certificate from the IdP to validate the signature. The certificate is stored on the SP side and used whenever a SAML response arrives.
  • ACS Endpoint - Assertion Consumer Service URL - often referred to simply as the SP sign-in URL or "reply URL". This is the endpoint provided by the SP where SAML responses are posted. The SP needs to provide this information to the IdP.
  • IdP Sign-In URL - This is the endpoint on the IdP side where SAML requests are posted. The SP needs to obtain this information from the IdP.
tip

These values are usually provided via XML-based metadata. If you are working with a third-party vendor, they will provide this to you in order to enable single-sign-on.

The easiest way to implement SAML is to leverage an open source SAML toolkit. These toolkits provide the logic needed to digest the information in an incoming SAML Response. In addition, if the SP needs to support the SP-initiated sign-in flow, the toolkits also provide the logic needed to generate an appropriate SAML authentication request.

Understanding SP-Initiated Sign-In Flow​

An IdP-initiated sign-in flow starts from the IdP. Since it begins on the IdP side, there is no additional context about what the user is trying to access on the SP side other than the fact that the user is trying to get authenticated and access the SP. Typically, after the user is authenticated, the browser will be taken to a generic landing page in the SP.

In an SP-initiated flow, the user tries to access a protected resource directly on the SP side without the IdP being aware of the attempt. Two issues arise. First is the need to identify the right IdP if authentication of a federated identity is needed. With SP-initiated sign in, the SP initially doesn't know anything about the identity. Developers need to figure out how the SP can determine which IdP should be receiving the SAML request.

In some cases, if application URLs contain subdomain information that is mapped to a unique tenant and IdP, then the resource link being hit is enough to identify the IdP. If this isn't the case, prompting the end user for additional information from the end user such as user ID, email, or a company ID will work.

Deep Links & Relay State​

Another issue with SP-initiated sign-in flow is the support for deep links. Most applications support deep links. For example, you might receive a link to a document that resides on a content management system. Ideally, if you need to authenticate prior to accessing the document, you would like to be taken to the document immediately after authentication.

SAML is an asynchronous protocol by design. The SP-initiated sign-in flow begins by generating a SAML authentication request that gets redirected to the IdP. At this point, the SP doesn't store any information about the request. When the SAML response comes back from the IdP, the SP wouldn't know anything about the initial deep-link that triggered the authentication request. Luckily, SAML supports this with a parameter called RelayState.

A RelayState is an HTTP parameter that can be included as part of the SAML request and SAML response. In an SP-initiated sign-in flow, the SP can set the RelayState parameter in the SAML request with additional information about the request. A SAML IdP, after receiving the SAML request, takes the RelayState value and simply attaches it back as an HTTP parameter in the SAML response after the user has been authenticated. This way, when the round trip completes, the SP can use the RelayState information to get additional context about the initial SAML authentication request.

In the case of a deep link, the SP sets the RelayState of the SAML request with the deep-link value. When the SAML response comes back, the SP can use the RelayState value and take the authenticated user to the right resource.