Red Hat Training

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

Chapter 3. Additional Use Cases for SSO with Red Hat JBoss Enterprise Application Platform

In addition to the out-of-the-box functionality, JBoss EAP supports additional use cases for SSO, including SAML for browser-based SSO, desktop-based SSO, and SSO via a secure token service.

3.1. Browser-Based SSO Using SAML

In a browser-based SSO scenario, one or more web applications, known as service providers, are connected to a centralized identity provider in a hub-and-spoke architecture. The identity provider (IDP) acts as the central source, or hub, for identity and role information to all the service providers, or spokes. When an unauthenticated user attempts to access one of the service providers, that user is redirected to an IDP to perform the authentication. The IDP authenticates the user, issues a SAML token specifying the role of the principal, and redirects them to the requested service provider. From there, that SAML token is used across all of the associated service providers to determine the user’s identity and access. This specific method of using SSO starting at the service providers is known as a service provider-initiated flow.

Like many SSO systems, JBoss EAP uses IDPs and SPs. Both of these components are enabled to be run within JBoss EAP instances and work in conjunction with the JBoss EAP security subsystem. SAML v2, FORM-based web application security, and HTTP/POST and HTTP/Redirect Bindings are also used to implement SSO.

To create an identity provider, create a security domain, for example idp-domain, in a JBoss EAP instance that defines an authentication and authorization mechanism, for example LDAP or a database, to serve as the identity store. A web application, for example IDP.war, is configured to use additional modules, org.picketlink, required for running an IDP in conjunction with idp-domain and is deployed to that same JBoss EAP instance. IDP.war will serve as an identity provider. To create a service provider, a security domain is created, for example sp-domain, that uses SAML2LoginModule as an authentication mechanism. A web application, for example SP.war, is configured to use additional modules, org.picketlink, and contains a service provider valve that uses sp-domain. SP.war is deployed to an JBoss EAP instance where sp-domain is configured and is now a service provider. This process can be replicated for one or more SPs, for example SP2.war, SP3.war, and so on, and across one or more JBoss EAP instances.

3.1.1. Identity Provider Initiated Flow

In most SSO scenarios, the SP starts the flow by sending an authentication request to the IDP, which sends a SAML response to SP with a valid assertion. This is known as a SP-initiated flow. The SAML 2.0 specifications define another flow, one called IDP-initiated or Unsolicited Response flow. In this scenario, the service provider does not initiate the authentication flow to receive a SAML response from the IDP. The flow starts on the IDP side. Once authenticated, the user can choose a specific SP from a list and get redirected to the SP’s URL. No special configuration is necessary to enable this flow.


  1. User accesses the IDP.
  2. The IDP, seeing that there is neither a SAML request nor a response, assumes an IDP-initiated flow scenario using SAML.
  3. The IDP challenges the user to authenticate.
  4. Upon authentication, the IDP shows the hosted section where the user gets a page that links to all the SP applications.
  5. The user chooses an SP application.
  6. The IDP redirects the user to the SP with a SAML assertion in the query parameter, SAML response.
  7. The SP checks the SAML assertion and provides access.

3.1.2. Global Logout

A Global Logout initiated at one SP logs out the user from the IDP and all the SPs. If a user attempts to access secured portions of any SP or IDP after performing a global logout, they must reauthenticate.

3.2. Desktop-Based SSO

A desktop-based SSO scenario enables a principal to be shared across the desktop, usually governed by an Active Directory or Kerberos server, and a set of web applications which are the SPs. In this case, the desktop IDP serves as the IDP for the web applications.

In a typical setup, the user logs in to a desktop governed by the Active Directory domain. The user accesses a web application via a web browser configured with JBoss Negotiation and hosted on the JBoss EAP. The web browser transfers the sign-on information from the local machine of the user to the web application. JBoss EAP uses background GSS messages with the Active Directory or any Kerberos Server to validate the user. This enables the user to achieve a seamless SSO into the web application.

To set up a desktop-based SSO as an IDP for a web application, a security domain is created that connects to the IDP server. A NegotiationAuthenticator is added as a valve to the desired web application, and JBoss Negotiation is added to the SP container’s class path. Alternatively, an IDP can be set up similarly to the browser-based SSO scenario but using the desktop-based SSO provider as an identity store.

3.3. SSO Using STS

JBoss EAP offers several login modules for SPs to connect to an STS. It can also run an STS (PicketLinkSTS). More specifically, the PicketLinkSTS defines several interfaces to other security token services and provides extension points. Implementations can be plugged in by using configuration, and the default values can be specified for some properties via configuration. This means that the PicketLinkSTS generates and manages the security tokens but does not issue tokens of a specific type. Instead, it defines generic interfaces that allow multiple token providers to be plugged in. As a result, it can be configured to deal with various types of token, as long as a token provider exists for each token type. It also specifies the format of the security token request and response messages.

The following steps are the order that the security token requests are processed when using the JBoss EAP STS.

  1. A client sends a security token request to PicketLinkSTS.
  2. PicketLinkSTS parses the request message and generates a JAXB object model.
  3. PicketLinkSTS reads the configuration file and creates the STSConfiguration object, if needed. It obtains a reference to the WSTrustRequestHandler from the configuration and delegates the request processing to the handler instance.
  4. The request handler uses the STSConfiguration to set default values when needed, for example when the request does not specify a token lifetime value.
  5. The WSTrustRequestHandler creates the WSTrustRequestContext and sets the JAXB request object and the caller principal it received from PicketLinkSTS.
  6. The WSTrustRequestHandler uses the STSConfiguration to get the SecurityTokenProvider that must be used to process the request based on the type of the token that is being requested. It invokes the provider and passes the constructed WSTrustRequestContext as a parameter.
  7. The SecurityTokenProvider instance processes the token request and stores the issued token in the request context.
  8. The WSTrustRequestHandler obtains the token from the context, encrypts it, if needed, and constructs the WS-Trust response object containing the security token.
  9. PicketLinkSTS dictates the response generated by the request handler and returns it to the client.

An STS login module, for example STSIssuingLoginModule, STSValidatingLoginModule, SAML2STSLoginModule, and so on, is typically configured as part of the security setup of a JEE container to use an STS for authenticating users. The STS may be collocated on the same container as the Login Module or be accessed remotely through web service calls or another technology.