Problem to Solve

The most common use case for which SAML is used is cross-domain single sign-on, in our experience. 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 might create.

SAML was designed as an “XML-based framework for describing and exchanging security information between on-line 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 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 used by the user in each system. We’ll see more about how these features work in the following sections, but first, we need to specify 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 on the authentication event and the authenticated 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 information contains information such as URL endpoints and certificates with which to validate digitally signed messages. This data enables the two parties to exchange messages. 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 redirects them 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 a sample of 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 depicts a scenario where the user does not have an existing authentication session at the identity provider and therefore has to authenticate.)

1. 1.

   User visits a service provider (application).

    
2. 2.

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

    
3. 3.

   Identity provider interacts with user for authentication.

    
4. 4.

   User authenticates. Identity provider validates credentials.

    
5. 5.

   Identity provider redirects 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 is useful 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.)

1. 1.

   User visits a corporate portal.

    
2. 2.

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

    
3. 3.

   Identity provider interacts with user for authentication.

    
4. 4.

   User authenticates. Identity provider validates credentials.

    
5. 5.

   Identity provider redirects user’s browser back to portal with a SAML response for the portal (response #1) containing an authentication assertion. User is logged into portal which displays content to 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.

    

Identity Federation

With SAML, identity federation establishes an agreed-upon identifier 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).

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 using “ann”.

The link between an identity at a service provider and 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, but this can be problematic 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 side to the user’s profile. Use of a unique identifier for each federation is privacy-friendly and prevents correlation of user activity, but isn’t common in practice. The approach to use is set up when the two parties exchange metadata and configure their infrastructure to establish the relationship (often called a federation in practice) between 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. 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 implement 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.0 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.

If you elect not to use an authentication broker, we recommend at least using a SAML library rather than attempting to implement SAML yourself as it is a complex protocol to implement.

Configuration

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.

Summary

SAML 2.0 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.0 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, yet still support customers who require 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