Problem to Solve

The most common use case for which SAML is used in our experience is cross-domain single sign-on. In this scenario, a user needs to access multiple applications which reside in different domains, such as application1.com and application2.com. Without cross-domain single sign-on, a user might have to establish an account in each application and log in to each application individually. This means potentially many different usernames and passwords for a user to remember. If the user is a corporate employee and the applications are SaaS applications, it would be difficult for the enterprise to manage all the SaaS application accounts their employees create.

SAML was designed as an “eXtensible Markup Language (XML)–based framework for describing and exchanging security information between online business partners.”ⁱⁱ SAML enables applications to delegate user authentication to a remote entity known as an identity provider. The identity provider authenticates the user and returns to the application an assertion with information about the authenticated user and authentication event. If the user accesses a second application shortly afterward, which delegates authentication to the same identity provider, the user will be able to access the second application without being prompted again to log in. This capability is single sign-on.

SAML also provides a mechanism for an application and identity provider to use a common shared identifier for a user in order to exchange information about the user. This is known as federated identity. The federated identity can use the same identifier across systems, or it can use an opaque, internal identifier which is mapped to the identifier for the user in each system. We’ll see more about how these features work in the following sections, but, first, we need to explain some terms we’ll use.

Terminology

How It Works

The most common SAML scenario is cross-domain web single sign-on. In this scenario, the subject is a user that wishes to use an application. The application acts as a SAML service provider. The application delegates user authentication to a SAML identity provider that may be in a different security domain. The identity provider authenticates a user and returns a security token, known as a SAML assertion, to the application. A SAML assertion provides information about the authentication event and the authenticated user, known as the subject. We will use the term application along with service provider for consistency across chapters, but should note that an entity acting as an identity provider can also act as a service provider by further delegating authentication to another identity provider.

To establish the ability to do cross-domain web single sign-on, the organizations owning the service provider (application) and identity provider exchange information, known as metadata. The metadata contains information such as URL endpoints and digital certificates. This data enables the two parties to exchange messages that are digitally signed and optionally encrypted. The metadata is used to configure and set up a trust relationship between the service provider and the identity provider and must be done before the identity provider can authenticate users for the service provider (application).

Once mutual configuration of providers is in place, when a user accesses the service provider (application), it redirects the user’s browser over to the identity provider with a SAML authentication request message. The identity provider authenticates the user and issues a redirect back to the application with a SAML authentication response message. The response contains a SAML assertion with information about the user and authentication event, or an error, if an error condition occurred. The identity provider can tailor the identity claims in the assertion as needed for each service provider. Please see Appendix C for sample SAML authentication request and response messages and a description of commonly used elements within each.

SP-Initiated SSO

The simplest form of cross-domain single sign-on is illustrated in Figure 7-1. In this example, the user starts at the service provider (SP) (application) so it is known as the “SP-initiated” flow. (The diagram and accompanying description of steps depict a scenario where the user does not have an existing authentication session at the identity provider and therefore has to authenticate.)

A schematic representation of single sign on. It has 4 blocks for, user, browser, application, and identity provider. The diagram has 6 steps of communication between the blocks for login credentials, S A M L request, and S A M L response.

1. 1.

   The user visits a service provider (application).

    
2. 2.

   The service provider redirects the user’s browser to the identity provider with a SAML authentication request.

    
3. 3.

   The identity provider interacts with the user for authentication.

    
4. 4.

   The user authenticates. The identity provider validates credentials.

    
5. 5.

   The identity provider redirects the user’s browser back to the service provider with a SAML response containing a SAML authentication assertion. The response is sent to the service provider’s Assertion Consumer Service (ACS) URL.

    
6. 6.

   The service provider consumes and validates the SAML response and responds to the user’s original request (assuming the user was successfully authenticated and has sufficient privileges for the request).

    

IdP-Initiated Flow

Figure 7-1 showed an interaction sequence with the user starting at the service provider (application). This is called “SP-initiated” because the user initiates the interaction at the service provider (SP). SAML also defined another flow, known as “IdP-initiated,” where the user starts at the identity provider (IdP), and which is shown in Figure 7-2. In this case, the identity provider redirects the user’s browser to the service provider with a SAML response message without the service provider having sent any authentication request. This flow is found in some enterprise environments where a user accesses applications via a corporate portal.

When the user initially accesses the corporate portal, they are redirected to the corporate identity provider to log in. After logging in, the user is returned to the portal and sees a menu of application links on the portal. Clicking one of these links redirects the user to the identity provider, with the application URL as a parameter. The identity provider detects the user already has an authenticated session and redirects the user’s browser to the application, with a SAML response message as in the SP-initiated case. The IdP-initiated flow does not require a portal, but we’ve chosen to show it as it is a common way this flow is used.

The IdP-initiated flow with a portal has been used in enterprises because it provides single sign-on and ensures users go to the correct URL for each application which reduces the risk of users being phished. The IdP-initiated flow is shown in Figure 7-2. (This diagram assumes the user does not have an existing authentication session.)

A schematic representation of single sign on. It has 5 blocks for, user, browser, application, identity provider, and corporate portal. The diagram has 8 steps of communication between the blocks for login credentials, S A M L request, and S A M L response.

1. 1.

   The user visits a corporate portal.

    
2. 2.

   The portal redirects the user’s browser to the identity provider with a SAML authentication request.

    
3. 3.

   The identity provider interacts with the user for authentication.

    
4. 4.

   The user authenticates. The identity provider validates credentials.

    
5. 5.

   The identity provider redirects the user’s browser back to the portal with a SAML response for the portal (response #1) containing an authentication assertion. The user is logged in to the portal which displays content to the user, including a list of applications.

    
6. 6.

   The user clicks a link in the portal for an application. The link directs the user’s browser to the identity provider with a parameter indicating the desired service provider application. The IdP checks the user’s session. This diagram assumes the user’s session is still valid.

    
7. 7.

   The identity provider redirects the user’s browser to the service provider’s Assertion Consumer Service (ACS) URL, with a new SAML response (response #2) for that service provider (the application).

    
8. 8.

   The service provider (application) consumes the SAML response and authentication assertion and renders an appropriate page for the user, assuming their identity and privileges are sufficient for their request.

    

For more detailed information on the contents of SAML authentication requests and responses, as well as some application validation steps, see Appendix C. In general, with IdP-initiated flows, there are fewer checkpoints with which to validate incoming SAML responses, which may make applications more vulnerable to certain types of replay or injection attacks, especially if IdP-initiated flows can initiate actions within an application. We recommend using a flow that initiates from a Service Provider rather than one that initiates from an Identity Provider.

Identity Federation

With SAML, identity federation establishes an agreed-upon identifier that is used between a service provider (application) and an identity provider to refer to a subject (user). This enables a service provider to delegate authentication of the user to an identity provider and receive back an authentication assertion with identity claims that include an identifier for the authenticated subject that will be recognizable by the service provider.

Figure 7-3 illustrates an example. A user named Ann Smith has an account in two applications, application1 hosted at app1.com and application2 hosted at app2.com. In application1, her account identifier is [email protected], and in application2, her account identifier is “ann.” Ann also has an account at a corporate identity provider where her account identifier is [email protected].

The administrators for application1 and the identity provider exchange metadata about their environments and use it to set up federation information between application1 and the identity provider. The same is done by the administrators of application2 and the identity provider. In practice, the administrators of an identity provider configure it to send assertions to each service provider that contain appropriate identifiers and attributes for the service provider (application).

A 3-block diagram for identity federation. It has an identity provider with account identifier ann at the rate corp.com, app 1 with an account identifier ann at the rate corp dot com, and app 2 with identifier ann.

When Ann accesses application1, it redirects her browser to her employer’s identity provider at “corp.com”. The identity provider authenticates Ann and redirects her browser back to application1 with an authentication assertion containing a naming attribute identifying her as [email protected]. Application1 uses the same identifier for Ann, so it recognizes her based on that identity.

When Ann accesses application2, it redirects her browser to the identity provider which recognizes that she already has a session. If the identity provider returns an authentication assertion identifying her as [email protected], however, application2 will not recognize her as a valid user by that name. The identity provider needs to return an appropriate identifier for each service provider. In this case, when the identity provider delivers the authentication assertion to application2, it needs to identify the subject of the assertion with a naming attribute using “ann.”

The logical link between the identity for a person at a service provider and at an identity provider can be set up in different ways. In practice, a user’s email address is often used as the identifier for a user at both the service provider and identity provider. This can be problematic, however, as a user may need to change their email address, and it can conflict with privacy requirements. The use of a specific identifier attribute can be requested dynamically in a request, or an identity provider can be configured to send a particular identifier to a service provider. It is also possible for an identity provider and service provider to exchange information using an opaque, internal identifier for a user that is mapped on each entity’s side to the user’s profile within that entity. The use of a unique identifier for each federation is privacy-friendly and prevents correlation of user activity across providers, but this has not been widely done in practice. The approach to use is set up when the owners of the service provider and identity provider exchange metadata and configure their servers to establish the trust relationship (often called a federation) between the service provider and identity provider.

Authentication Brokers

Authentication brokers can be used by applications to easily enable support for multiple authentication protocols and mechanisms. If you are building a new application and plan to use OIDC for authentication, you may receive requests to support SAML from business customers who want their users authenticated at their corporate SAML identity provider. SAML is a complex protocol, which would require significant work to implement and support across many customers because each customer’s SAML Identity Provider may be configured differently, resulting in minor differences in the assertions.

Rather than implement SAML directly in your application yourself, you can use an authentication broker to simplify the task of supporting SAML.² An authentication broker allows your application to use a newer identity protocol like OIDC and rely on the authentication broker to communicate via different protocols to a variety of identity providers. Figure 7-4 depicts an application implemented to use OIDC and OAuth 2 with an authentication broker which communicates in turn with several identity providers, each of which uses a different protocol. The use of an authentication broker allows an application team to implement newer identity protocols in their application and focus on the core features of their application instead of spending time to directly implement and support older identity protocols requested by customers.

A block diagram for the role of an authentication broker. It has your application linked to an authentication broker via O I D C, which is further linked to 3 different I D Ps via many protocols.

If you elect not to use an authentication broker, we recommend at least using a SAML library rather than attempting to implement SAML yourself. SAML assertions are lengthy, with many XML elements to parse and validate, making it a complex protocol to implement. Using a SAML library will allow you to spend more time on your application’s core features instead of fiddling around with a lot of XML.

Configuration

Whether you use an authentication broker or a library, Tables 7-1 and 7-2 show the elements that typically need to be configured at the service provider (application) and identity provider and their meaning. The owners of the service provider and identity provider need to exchange the information in these tables to enable the configuration of the federation.

The configuration elements listed in Table 7-1 are set up at the Service Provider for each Identity Provider it will rely upon. Similarly, the configuration elements in Table 7-2 are configured at the Identity Provider for each Service Provider that will rely upon the Identity Provider. The correct configuration of the federation at the Service Provider and Identity Provider is necessary for the Service Provider to redirect users to a trusted Identity Provider and to receive and trust the SAML responses from the Identity Provider.

You’ll need to consult the documentation for the authentication broker or SAML library you’ve chosen for the specific details of where and how to configure the preceding elements. Once both providers are configured and you have attempted a trial authentication, it’s common for authentication to fail the first time. You can debug issues by attempting an authentication, capturing a trace of the SAML request and response message, and examining them. We’ve provided guidance for how to troubleshoot in Chapter 16 and details on what to look for in the SAML request and response messages in Appendix C.

As time passes, the information used to establish the federation may change. The most common change is for the digital certificates or cryptographic keys to expire. These are exchanged during the setup of a federation relationship between providers and used to validate digital signatures on SAML messages and optionally to decrypt encrypted SAML messages. If a certificate or key expires, the identity provider may not be able to consume a SAML request from the service provider, or the service provider will not be able to consume and validate the SAML assertion from the identity provider, and authentication requests will fail. The owners of service providers and identity providers need to notify the other party for each federation when a change is coming and work out an appropriate procedure to make updates without disrupting service. Some providers may facilitate such changes by either dynamically checking for updates at a provider’s discovery URL or allowing the configuration of two values. The latter option requires the provider to try one value, and if it fails, try the second value. These capabilities can save a lot of administrator time and minimize risk of downtime from changes, especially in scenarios where an application must support a lot of different identity providers or an identity provider is used by many service providers.

Another operational requirement is to ensure providers have accurate time. SAML assertions have an expiration, which is often just long enough for the assertion to be transmitted to the recipient and consumed. If the servers for the service provider or identity provider are not synchronized with an accurate time source, their internal clock may slowly drift. This can cause a service provider to receive an assertion that is already expired. Therefore, in addition to the configuration in Tables 7-1 and 7-2, it is imperative for the service provider and identity provider to synchronize their time with an accurate time service such as the Network Time Protocol (NTP).ⁱⁱⁱ

Summary

SAML 2 provides an industry standard solution for web single sign-on and identity federation. These key features enabled enterprises to use cloud applications and still maintain centralized control of identities. The use of SAML eliminates exposure of static password credentials to applications and provides users the convenience of single sign-on. Many enterprises have implemented SAML identity providers and expect SaaS application vendors to support it.

At this point, however, SAML is an older protocol compared to OIDC. Now that OIDC and OAuth 2 exist, modern applications designed around APIs will benefit from implementing these newer protocols, as they provide support for both authentication and API authorization, respectively, and identity providers that support them exist for both consumer- and corporate-facing scenarios.

If you need to support SAML, rather than implementing it in a new application yourself, it is more efficient to use an authentication broker service that can take care of the SAML implementation complexity for you.³ This will enable you to implement your application with newer protocols and still support customers who require a variety of older protocols such as SAML and WS-Fed. Alternatively, you can use a library for your chosen platform to implement such protocols. Once authentication is solved, authorization and policy enforcement are needed to govern what a user can do, and that’s coming up in the very next chapter.

Notes