External authentication interface process flow

The following diagram illustrates the process flow for external authentication interface (EAI) authentication. Components include:

Process:

  1. Authentication process is initiated.

    1. An unauthenticated user requests a protected resource.

    2. WebSEAL intercepts the request and redirects to a login.html page.

    3. The user provides login information (user name and password) on the form and clicks the submit link to send the data to the EAA.

    Other examples of initiating the authentication process can include:

    • Manually typing an appropriate link to the EAA.
    • Signon requirement in a CDSSO environment.
    • Cached page.
    • Federation Runtime scenario. User redirected to the EAA from a service provider, with the goal of having an identity provided for that user.

    A hidden configuration option enables us to give priority to an EAI header to redirect a successful login to a URL. To enable, add the following to the [eai] stanza:

      eai-redir-url-priority = yes

  2. Authentication request and response exchange between the EAA and the client.

    Exchanges are streamed through (not intercepted) by WebSEAL. The final authenticating request to the EAA must be directed to a distinct URL. This URL could, for example, include a query string that indicates the login task, such as state=perform-login. This URL is specified in the WebSEAL configuration file as the trigger URL. WebSEAL examines each request for this trigger URL.

    If the trigger URL is detected, WebSEAL examines the corresponding response for authentication data located in HTTP headers (specified in the WebSEAL configuration file).

    WebSEAL supports EAI logout. An HTTP header returned from the EAI enables it to instruct WebSEAL to log out a session. The header emulates the pdadmin server task command line input, and therefore is analogous to the hidden WebSEAL pdadmin command of the same name. The syntax for the header is...

      am-eai-server-task: terminate session <user-sess-id>

    ...where terminate session is a non-translatable keyword pair, and <user-sess-id> is a user session ID of the same format and contents as that used to perform the terminate session command using pdadmin.

    An EAI application can also return a header to log out all sessions for a specified user. The syntax for this header is am-eai-server-task:

    ...where terminate all_session is a non-translatable keyword pair, and <user-name> is the ID of the user to terminate all sessions for.

    Example exchange 1:

    • The user clicks a submit link on a custom login page. This link is the trigger URL.
    • The recognition of the trigger URL in the request causes WebSEAL to look for authentication data in the corresponding response.
    • The external authentication application authenticates the user and, in its response, populates the special HTTP headers with authentication data.

    Example exchange 2:

    • The EAA requires several exchanges with the user to receive the required login information.
    • Each request to the EAA uses the trigger URL. Therefore, for each response, WebSEAL looks for authentication data.
    • WebSEAL examines each corresponding response for authentication data returned from the external authentication interface in HTTP headers.
    • When no authentication takes place, these headers are empty in each response. WebSEAL continues streaming the requests and responses without taking any action.
    • After several exchanges, the EAA receives all the login information it needs. The EAA authenticates the user and, in its final response, populates the special HTTP headers with authentication data.

    Example exchange 3:

    • The EAA requires several exchanges with the user to receive the required login information.
    • Each request to the EAA uses a URL that does not match the trigger URL. Therefore, for each corresponding response, WebSEAL does not look for authentication data
    • WebSEAL streams the requests and responses without taking any action.
    • The final request to the EAA uses the trigger URL.
    • The recognition of the trigger URL in this final request causes WebSEAL to look for authentication data in the corresponding response.
    • The external authentication authenticates the user and, in its final response, populates the special HTTP headers with authentication data.

  3. Authentication response.

    WebSEAL examines the corresponding response and finds the authentication data in the HTTP headers.

  4. WebSEAL uses the authentication data to build a credential for the user.

  5. WebSEAL sends a response to the user using the following precedence:

    1. If automatic redirection is enabled, the user is redirected to the location specified in the WebSEAL configuration file.
    2. If the response from the EAA contains the streaming flag, WebSEAL streams the original response to the client.
    3. If the initial request was cached, the request is reprocessed for the user.
    4. If the response from the EAA contains a redirection URL header, the user is redirected to the location specified by that URL.
    5. Otherwise, WebSEAL responds with the standard login_success.html page.

Parent topic: External authentication interface

Related concepts