IBM Tivoli Federated Identity Manager, Version 6.2.2

Configuring a Web server plug-in

The Web server plug-in is required to be installed on your Web server only if that server is a supported server other than WebSphere® Application Server. The primary function of the plug-in is to extract the user identity information from the LTPA cookie in a Web request and make the identity information available to the target application that is hosted by the Web server using either HTTP headers or server variables (if supported by the Web server).

Web request processing

To ensure that you can properly configure the Web server plug-in and integrate your application with the plug-in, it is helpful to understand how Web requests are processed by the plug-in.

When a request to a Web application is received by the server, it is passed to the plug-in for processing and the plug-in performs the following actions:
  1. Retrieves the Web request URL.
  2. Retrieves the LTPA token cookie from the request, if there is one.
  3. Checks its configuration to see if the plug-in functionality is enabled. If it is not enabled, processing ends. If it is enabled, the following actions occur:
    1. Checks whether the URL in the request matches any of the URLs that are configured in the plug-in configuration file. This capability enables you to apply specific processing to specific applications.
    2. Identifies the list of HTTP headers to strip from the request. The plug-in configuration file identifies the HTTP headers to strip and prevents attacks in which fake headers are added by the client.
    3. The LTPA token cookie is examined and one of the following actions occurs:
      • If the request does not contain a valid LTPA token cookie, the plug-in identifies the list of session cookies, if any, to strip from the request based on the configuration specified in the plug-in configuration file.

        Cookies are stripped only if the LTPA token cookie is missing, expired, or improperly encoded. Session cookies are present only after a federated single sign-on, which is indicated by the presence of an LTPA token cookie.

        A session cookie without a valid LTPA token cookie implies that the session cookie is no longer applicable. Processing ends.

      • If the request contains a valid LTPA token cookie, the cookie is decoded.

        If the decoding fails or if the LTPA token has expired, no further processing occurs. The request is passed to the Web application without the addition of HTTP headers and the application is left to handle the condition.

        If the LTPA token is decoded successfully, processing continues and the plug-in creates a list of HTTP headers to set in the request. It creates a list by using the configuration specified in the plug-in configuration file and the LTPA attribute values in the token. For information about the LTPA attribute to HTTP header mapping process, see LTPA-attribute-to-HTTP-header mapping.

        Note: Decoded LTPA tokens are saved in an in-memory cache until their expiration time. When a request is received, the plug-in checks the cache to see if a valid token is in the cache. If so, it is reused. If not, the token is decoded and added to the cache. The cache is limited in size, which is specified in number of cache entries. You can configure the size when you configure the plug-in configuration file.
    4. In the final processing step, the plug-in creates a list of server variables and values, if they are present and supported by the Web server.
      Note: The use of server variables is not supported in an IIS environment.
  4. The completed Web request is then sent to the Web application to handle.

LTPA-attribute-to-HTTP-header mapping

To map the LTPA cookie information to an HTTP header, the plug-in relies on a special configuration file, itfimwebpi.xml, which creates and then modifies or strips (removes) the HTTP headers into the final HTTP request that is sent to the target application.

The following figure shows how the content of the configuration file is used to determine the final HTTP request. Note that the figure shows only an example. LTPA attributes and headers are specific to each application that is used in an environment.
Figure 1. Example of LTPA attribute to HTTP header mapping
  1. The input HTTP request in the preceding figure contains:
    • The LTPA cookie that was created by the service provider that is configured in Tivoli® Federated Identity Manager
    • Two HTTP headers: 'Header-mail' and 'Other.'
  2. The plug-in configuration file instructions the plug-in to map the LTPA attributes as follows:
    • LTPA attribute 'tagvalue_email' → Header-mail (strip if not in LTPA)
    • LTPA attribute 'tagvalue_name' → Header-Name (strip if not in LTPA)
    • LTPA attribute 'LTPA_Other' → Hdr-Other (strip if not in LTPA)

    For all the headers, if the corresponding LTPA attribute does not exist, any Header with the configured name should be stripped.

    For example, in the figure, the LTPA value 'LTPA_Other' is not present, so the input HTTP header 'Hdr-Other' is stripped (removed). The LTPA value 'tagvalue_email' is present, so the existing header 'Header_mail' is modified to contain the value from the LTPA cookie: "user@example.com." The LTPA value 'tagvalue_name' is present, so the header 'Header_Name' is created with the value from the LTPA cookie: "User_Name."

    Headers that are not listed in the configuration file remain unchanged. If an LTPA cookie is not present, then all headers with "strip=yes" are removed.

The plug-in also has the ability to strip cookies if the LTPA cookie is not presented and the ability to map LTPA attributes to server variables. However, these scenarios are not shown in the figure.

For information about configuring your service provider environment, including the plug-in configuration file, see Configuring service provider components.

Parent topic: Configuring

Feedback