Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

Chapter 1. SSO with SAMLv2 Deeper Dive

The basics of SSO and SAML are covered in the Security Architecture for Red Hat JBoss Enterprise Application Platform. This section takes a deeper dive into the components involved in SAML v2 and SSO.

1.1. What is SAML v2?

Security Assertion Markup Language (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 (containing assertions) which 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 and with multiple service providers allows SAML v2 facilitate browser-based SSO.

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 entites: subject, identity provider, and service provider.

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.

The service provider (SP) requires proof (i.e. an assertion) of the subject’s identity, which it needs from the identity provider.

The identity provider (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 specified method at a specific point in time. An authentication context containing other information about the authenticated subject may 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 messages (requests and responses) 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 SSO, Single Logout, and Assertion Query.

1.2. How Does SAML v2 Work with SSO

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

1.2.1. Web Browser SSO Profile

The Web Browser SSO profile specifies the way an identity provider (IDP), service provider (SP), and principal (in the form a browser agent) handle browser-based SSO. Both the SP and IDP have several bindings each that can be used in the Web Browser SSO 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 Red Hat JBoss Enterprise Application Platform 6 Security Architecture document. SAML assertions being pushed from the IDP utilizes HTTP POST messages or HTTP redirects. SAML assertions that are pulled by SPs involve sending an artifact to the receiver which is then dereferenced in order to obtain the assertions.

The basic flow of the Web Browser SSO profile is as follows:

  1. Principal HTTP request to SP: The principal first attempts to access a secured resource at the SP via an HTTP User Agent (e.g. 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 (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 are may vary between implementations.
  3. Authentication Request issued from SP to IDP via principal: Once the SP determines the IDP location and endpoint, the SP issues an Authentication Request (<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 via the user agent.
  4. IDP identifies principal: Once 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 SSO profile and may be accomplished in a number of ways (e.g. authentication via FORM, using existing session information, kerberos authentication, etc)
  5. IDP issues Response to SP: Once the principal is identified, the IDP issues a Response (<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 be used to indicate errors as well. 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 (e.g. 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), deny access, or do its own error handling.
Note

JBoss EAP 6 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 paramaters 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 via 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 principal attempts to access any secured resources 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 may be logged out of sessions individually using various means, or they may 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 6 does not support the SAML artifact binding.

As with the Web Browser SSO profile fiow, 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 (i.e. Service Providers or other relying parties) terminates its own session with the principal and sends a Logout Request (<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 (i.e. browser) 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 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 (<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 (<LogoutResponse> message) back to the IDP. As with the Logout Request, the response may 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 have been received from the relying parties, the IDP sends a new Logout Response (<LogoutResponse> message) back to original session participant who requested the logout. As with the other parts of this flow, this response may 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 IDP-initiated portion of the Global Logout Profile is not supported in JBoss EAP 6.

Note

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

1.2.3. Multiple IDPs and the Identity Discovery Profile

Browser-base SSO via SAML v2 also supports having multiple IDPs and can be used in both the Web Browser SSO profile as as well as the Global Logout profile. In cases where multiple-IDP’s 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 please see the official SAML 2.0 specification.