Chapter 1. Single Sign-On with SAML v2 Deeper Dive

The basics of Single Sign-On and SAML are covered in the JBoss EAP Security Architecture guide. This section takes a deeper dive into the components involved in SAML v2 and Single Sign-On.

1.1. What is SAML v2?

Security Assertion Markup Language, or SAML, is a data format and protocol that allows two parties, usually an identity provider and a service provider, to exchange authentication and authorization information. This information is exchanged in the form of SAML tokens that contain assertions, and are issued by Identity Providers to subjects for authenticating with Service Providers. The ability for subjects to use and reuse SAML tokens issued from an identity provider with multiple service providers allow SAML v2 to facilitate browser-based Single Sign-On.

1.1.1. Building Blocks

The most important concept to keep in mind with SAML is that its all about passing security assertions between entities. SAML has several components it uses to accomplish this task.

1.1.1.1. Entities

Entities are all parties involved in creating and passing assertions. SAML has the concept of three distinct entities:

subject
The subject, also referred to as the principal, which is the user in most cases, is requesting access to a resource on a service provider, which is secured by SAML.
service provider
The service provider, or SP, requires proof, as an assertion, of the subject 's identity, which it needs from the identity provider.
identity provider
The identity provider, or IDP, provides a set of assertions, in the form of a token about a subject, that can be used in authentication and authorization decisions by service providers.

In summary, subjects get issued assertions, identity providers issue those assertions, and service providers use those assertions to authenticate and authorize subjects.

1.1.1.2. Security Assertions

A security assertion is a set of statements issued by an identity provider about a subject. Service providers use these assertions to make access-control decisions about a subject. Statements can take the following forms:

Authentication
Authentication assertions assert that a subject successfully authenticated using a specified method at a specific point in time. An authentication context containing other information about the authenticated subject can also be specified in an authentication statement.
Attribute
Attribute assertions assert that a subject has certain attributes.
Authorization Decision
Authorization Decision assertions assert a response, accept or deny, to an authorization request for a subject on a resource.

Example

This user logged in as Sarah at 9:30 using a username and password.  Sarah is a member of the Managers group.  Sarah is accepted to access the Employee Information resource.

  • The statement This user logged in as Sarah at 9:30 using a username and password is an Authentication assertion.
  • The statement Sarah is a member of the Managers group is an Attribute assertion.
  • The statement Sarah is accepted to access the Employee Information resource is an Authorization Decision assertion.

Assertions are packaged as SAML tokens and transported using SAML protocols.

1.1.1.3. Protocols

A SAML protocol describes how assertions are packaged, usually in the form of a request and response, as well as the rules on the correct way to process them. These rules must be followed by both the producers and consumers of the requests and responses. A request can ask for specific, known assertions or query identity providers for authentication, attribute, or authorization decisions. The request and response messages, which include security assertions, are formatted in XML and adhere to a specified schema.

1.1.1.4. Bindings

SAML bindings specify how SAML protocols map to other standard protocols used for transport and messaging. Some examples include:

  • A SAML binding that maps to an HTTP redirect.
  • A SAML binding that maps to an HTTP POST.
  • A SAML binding that maps SAML requests/responses to SOAP requests and responses.

1.1.1.5. Profiles

SAML profiles use assertions, protocols, and bindings to support specific use cases, such as Web Browser Single Sign-On, Single Logout, and Assertion Query.

1.2. How Does SAML v2 Work with Single Sign-On

The basics of browser-based Single Sign-On with SAML v2 are covered in the JBoss EAP Security Architecture guide, specifically in the Browser-Based Single Sign-On Using SAML and Multiple Red Hat JBoss Enterprise Application Platform Instances and Multiple Applications Using Browser-Based Single Sign-On with SAML sections. This section gives a more in-depth explanation regarding the SAML profiles and bindings related to browser-based Single Sign-On with SAML v2.

1.2.1. Web Browser Single Sign-On Profile

The Web Browser Single Sign-On profile specifies the way an IDP, SP, and principal, in the form of a browser agent, handle browser-based Single Sign-On. Both the SP and IDP have several bindings that each can be used in the Web Browser Single Sign-On profile, allowing many possible flows. Additionally, this profile supports message flows initiated from either the IDP or SP. This profile also supports the IDP pushing the SAML assertion to the SP, or the SP pulling the assertion from the IDP. Flows initiated from either the SP or IDP are explained at a high level in the JBoss EAP Security Architecture guide. SAML assertions pushed from the IDP utilize HTTP POST messages or HTTP redirects. SAML assertions that are pulled by SPs involve sending an artifact to the receiver, which is then dereferenced to obtain the assertions.

The basic flow of the Web Browser Single Sign-On profile is as follows:

  1. Principal HTTP request to SP.

    The principal first attempts to access a secured resource at the SP using an HTTP User Agent, for example a browser. If the principal has already been issued a SAML token with a valid security context, the SP will allow or decline the principal. This is the last step. Otherwise, the SP will attempt to locate the IDP for the authentication request.

  2. SP determines IDP.

    The SP locates the IDP and its endpoint that supports the SP’s preferred binding. This allows the SP to send an authentication request to the IDP. The specific means of this process can vary between implementations.

  3. Authentication Request issued from SP to IDP using the principal.

    Once the SP determines the IDP location and endpoint, the SP issues an Authentication Request in the form of an <AuthnRequest> message, which will be delivered by the user agent, principal to the IDP. The HTTP Redirect, HTTP POST, or HTTP Artifact SAML bindings can be used to transfer the message to the IDP using the user agent.

  4. IDP identifies principal.

    Once the Authentication Request is delivered to the IDP by the principal, the principal will be identified by the IDP. The identification method is not specifically defined by the Web Browser Single Sign-On profile and may be accomplished in a number of ways, for example authentication using FORM, using existing session information, kerberos authentication, etc.

  5. IDP issues Response to SP.

    Once the principal is identified, the IDP issues a Response in the form of a <Response> message, to be delivered back to the SP for granting or declining access by the principal using the user agent. This message will contain at least one authentication assertion and can also be used to indicate errors. HTTP POST or HTTP Artifacts can be used to transfer this message, but HTTP Redirect cannot be used due to URL length constraints with most user agents. If the user agent initiated an IDP-based flow, for example by attempting to access the IDP directly instead of an SP, the process would begin at this step. If successful, the HTTP POST or HTTP Artifact will be sent to a location, which is pre-configured in the IDP.

  6. SP allows or declines access to principal.

    Once the SP receives the Response, it may grant access for the requested resource to the principal by creating a security context, or it may deny access, or do its own error handling.

Note

JBoss EAP does not support the SAML artifact binding.

HTTP Redirect vs. POST Bindings

HTTP Redirect bindings make use of HTTP GET requests and the URL query parameters to transmit protocol messages. Messages sent in this manner are also URL and Base-64 encoded before being sent and decoded by the receiver. HTTP POST bindings send messages using form data, and also do a base-64 encode/decode on the message. Both SPs and IDPs can transmit and receive messages using redirect or POST bindings. Due to the limitation of URL lengths in certain scenarios, HTTP Redirect is usually used when passing short messages, and HTTP POST is used when passing longer messages.

1.2.2. Global Logout Profile

The Global Logout Profile allows a principal, who has authenticated with a set of IDPs and SPs, to log out and have that assertion be propagated to one or more associated IDPs and SPs.

When a principal authenticates with an IDP, the principal and IDP have established an authentication session. The IDP may then issue assertions to various SPs, or relying parties, based on that authentication. From there if the principal attempts to access a secured resource within those SPs, the SPs may choose to establish additional sessions with the principal based on that assertion issued from the IDP, hence relying on the IDP.

Once a session or set of sessions is created, a principal might be logged out of sessions individually using various means, or they can use the Global Logout Profile to logout of all sessions and from all SPs and IDPs at once. The Global Logout Profile can use the HTTP Redirect, HTTP POST or HTTP Artifact bindings in its flow. It can also use SOAP binding in certain cases which are not in the scope of this document.

Note

Single Logout Profile can be used as a synonym to Global Logout Profile.

Note

JBoss EAP does not support the SAML artifact binding.

As with the Web Browser Single Sign-On profile flow, the Global Logout Profile flow may be initiated either at the IDP or the SP.

The basic flow of the Global Logout Profile is as follows:

  1. Logout issued to IDP by Session Participant.

    A session participant, such as Service Providers or other relying parties, terminates its own session with the principal and sends a Logout Request, in the form of a <LogoutRequest> message, to the IDP that initially issued the security assertion for the principal. This request can be sent directly between the IDP and relying party, or indirectly by using the principal’s user agent as a pass through.

  2. IDP identifies Session Participant.

    Once the IDP receives the Logout Request, it uses that request to determine what sessions to terminate with which relying parties, including any sessions the IDP owns as a session authority or session participant. For each session, the IDP issues a Logout Request to the relying party and waits for a Logout Response from each party before issuing a new Logout Response back to the original session participant. In cases where the Global Logout Profile flow was initiated at the IDP, the flow begins at this step, and some other mechanism is used to determine the sessions and SPs.

  3. Logout issued by IDP.

    Once the IDP determines all of the sessions and associated relying parties, it sends a Logout Request, in the form of a <LogoutRequest> message, to each relying party and awaits a Logout Response. These requests may be sent directly between the IDP and the relying parties, or indirectly through the principal’s user agent.

  4. Logout response issued by Session Participant or Authority.

    Each relying party, including the IDP itself in some cases, attempts to terminate the session as directed by the IDP in the Logout Request, and returns a Logout Response in the form of a <LogoutResponse> message, back to the IDP. As with the Logout Request, the response can be issued directly between the relying party and the IDP, or indirectly through the principal’s user agent.

  5. IDP issues Logout response to original Session Participant.

    Once all the Logout Responses has been received from the relying parties, the IDP sends a new Logout Response, in the form of a <LogoutResponse> message, back to original session participant who requested the logout. As with the other parts of this flow, this response can be passed directly between the IDP and the session participant, or indirectly through the principal’s user agent. In cases where the Logout Request was initiated at the IDP, this step is omitted.

Note

The direct communication between the IDP and SP portion of the Global Logout Profile is not supported in JBoss EAP.

1.2.3. Multiple IDPs and the Identity Discovery Profile

Browser-based Single Sign-On using SAML v2 also supports having multiple IDPs, and can be used in both the Web Browser Single Sign-On profile as well as the Global Logout profile. In cases where multiple IDPs are configured, the Identity Discovery SAML profile is used to determine which IDP a principal uses. This is accomplished by reading and writing cookies with domain information and a list of IDPs.

1.3. Further Reading

For full details on the SAML v2, see the official SAML 2.0 specification.