SAML SSO initiation and flow on WebSphere Application Server

In all SAML web SSO profile flows, the binding defines the mechanism that is used to send information through assertions between the identity provider (IdP) and the service provider (SP). For Universal Access, the SAML response by HTTP POSTs is interpreted and controlled by logic in the IBM® Universal Access Responsive Web Application.

WebSphere® Application Server supports HTTP POST binding for sending web SSO profiles. The browser sends an HTTP POST request, whose POST body contains a SAML response document. The SAML response document is an XML document that contains certain data about the user and the assertion, some of which is optional.

Browser-based single sign-on (SSO) through SAML v2.0 works well with many web applications where the SAML flow is controlled by HTTP redirects between the identity provider (IdP) and the service provider (SP). The user is guided seamlessly from login screens to SP landing pages by HTTP redirects and hidden forms that use the browser to POST received information to either the IdP or the SP.

In a single-page application such as the IBM Universal Access Responsive Web Application, all screens are contained in the application and dynamic content is expected to be passed only in JSON messages through XMLHttpRequests. Therefore, the rendering of HTML content for login pages and the automatic posting of hidden forms in HTML content is more difficult. If the SP processes the content in the same way, it would be necessary to leave the application and hand back control to either the user agent or the browser, in which case the application state would be lost.

IdP-initiated use case

The IdP can send an assertion request to the service provider ACS in one of two ways:
  • The IdP sends a URL link in a response to a successful authentication request. The user must click the URL link to post the SAML response to the service provider ACS.
  • The IdP sends an auto-submit form to the browser that automatically posts the SAML response to the service provider ACS.

The ACS then validates the assertion, creates a JAAS subject, and redirects the user to the SP resource.

SP-initiated use case

When an unauthenticated user first accesses an application through an SP, the SP directs the user's browser to the IdP to authenticate. To be SAML specification compliant, the flow requires the generation of a SAML AuthnRequest from the SP to the IdP. The IdP receives the AuthnRequest, validates that the request comes from a registered SP, and then authenticates the user. After the user is authenticated, the IdP directs the browser to the Assertion Consumer Service (ACS) application that is specified in the AuthnRequest that was received from the SP.

Assertions and the SAML Response document

To prove the authenticity of the information, the assertion in the SAML response is almost always digitally signed. To protect the confidentiality of parts of the assertion, the payload can be digitally encrypted. A typical SAML response contains information that can be sent only through a login by a POST parameter. After login, an alternative mechanism is typically used to maintain the logged-in security context. Most systems use some cookie-based, server-specific mechanism, such as a specific security cookie, or the server’s cookie tied to the user’s HTTP session.

IdP-initiated flow for Universal Access in WebSphere Application Server

When Universal Access is configured with an IdP initiated web SSO flow, any attempt to connect to a protected resource without first authenticating through IdP results in a 403 HTTP response from IBM Cúram Social Program Management web API. Any authentication requests that are initiated through SP result in a 403 HTTP response, and the application redirects the user to the login page in Universal Access.

The following figure illustrates the IdP-initiated flow that is supported by Universal Access in a default installation.
Figure 1. IdP-initiated flow for Universal Access in WebSphere Application Server

The IdP initiated flow is outlined in the following list, with cross-references to the image.
  1. A user browses to the HTTP server that contains Universal Access.
  2. The user can browse as normal by interacting with IBM Cúram Social Program Management as either a public or a generated user (which is not shown in the diagram). The user then opens the login page to access protected content, which triggers an initial request to the IdP endpoint.
  3. In most IdP configurations, an HTML login form responds to the request. Universal Access ignores the response.
  4. To authenticate, the user completes the login form and clicks Submit. The form submission triggers an HTTP POST request that contains login credentials to the IdP.
  5. After successful validation of the user credentials at the IdP, the IdP populates the SAML Response and returns it in an HTML form that contains hidden input fields. Several redirects might occur before the 200 OK HTTP response that contains the SAML information is received. Universal Access does not respond to the redirects.
  6. Universal Access extracts the RelayState and SAMLResponse values, and inserts them in a new POST request to the application server Assertion Consumer Service (ACS).
  7. The application server ACS validates the signature that is contained in the SAML Response. WebSphere Application Server also ensures that the originator is a Trusted Authentication Realm. If the validation is successful, the ACS sends an HTTP redirect that points to the configured IBM Cúram Social Program Management target landing page, along with an LTPA2 Cookie that will be used in any subsequent communication.
  8. Universal Access begins its standard user setup by requesting account and profile information from the relevant web API endpoints.

SP-initiated flow for Universal Access in WebSphere Application Server

When Universal Access is configured with an SP-initiated web SSO flow, any attempt to connect to a protected resource without first authenticating results in a 401 HTTP response from the application server Assertion Consumer Service’s Trust Association Interceptor, and the generation of the SAML AuthnRequest message to be sent to the IdP.

Figure 2. SP-initiated flow for Universal Access in WebSphere Application Server

The SP initiated flow is outlined in the following list, with cross-references to the image.
  1. A user browses to the HTTP server that contains Universal Access.
  2. The user can browse as normal by interacting with IBM Cúram Social Program Management as either a public or a generated user (which is not shown in the diagram). The user then accesses protected content in the application, which is intercepted by the Assertion Consumer Service Trust Association Interceptor (TAI).
  3. The TAI triggers an 401 HTTP response with the SAML request message to be sent to the IdP.
  4. Universal Access then directs the SAML Request to the IdP SAML endpoint.
  5. In most IdP configurations, an HTML login form responds to the request. Universal Access extracts a hidden authentication token in the login form if present, ignoring the rest of the response.
  6. To authenticate, the user completes the login form and clicks Submit. The form submission triggers an HTTP POST request that contains login credentials to the IdP, along with the token extracted in the previous step if present.
  7. After successful validation of the user credentials at the IdP, the IdP populates the SAML Response and returns it in an HTML form that contains hidden input fields. Several redirects might occur before the 200 OK HTTP response that contains the SAML information is received. Universal Access does not respond to the redirects.
  8. Universal Access extracts the RelayState and SAMLResponse values, and inserts them in a new POST request to the application server Assertion Consumer Service (ACS).
  9. The application server ACS validates the signature that is contained in the SAML Response. WebSphere Application Server also ensures that the originator is a Trusted Authentication Realm. If the validation is successful, the ACS sends an HTTP redirect that points to the configured IBM Cúram Social Program Management target landing page, along with an LTPA2 Cookie that will be used in any subsequent communication.
  10. The browser automatically sends a new request to the target URL, but Universal Access does not respond to the request. Universal Access begins its standard user setup by requesting account and profile information from the relevant web API endpoints.