Trust associations

 

+

Search Tips   |   Advanced Search

 

WebSphere Application Server (WAS) supports Single Sign On (SSO) with perimeter authentication services such as reverse proxies through "Trust Associations". When trust associations are enabled WAS is not required to authenticate a user if a request arrives via a trusted source that has already performed authentication.

The perimeter authentication service is expected to:

  1. Establish "trust" with WAS
  2. Perform user authentication
  3. Insert user credential information into HTTP requests
The module in WAS which handles the trust association is the Trust Association Interceptor (TAI). It is a "pluggable" module whose responsibilities are:

  1. Validation of trust with the perimeter authentication service
  2. Extraction of credential information from the request

Trust associations have been supported since WAS 3.5 but were able to provide only the userid to the WAS runtime. After the TAI was invoked further user registry searches were required to create the various credentials required for authorization (even if this information was already contained in the request). The TAI interface has been extended in WAS 5.1.1 and WAS 6.0 to support the return of complete credential information. This means that no additional user registry searches are required after the TAI invocation. Be aware that if the WAS server participates in a cluster or makes downstream EJB calls, credential propagation must be enabled in WAS.

A Tivoli Access Manager (TAM) implementation of the new TAI interface is being shipped with both WAS 5.1.1 and WAS 6.0. The configuration steps have changed and are described in more detail later in the article.

In this setup, the WAS is used as a back-end server to further exploit its fine-grained access control. The reverse proxy server passes the HTTP request to the WAS that includes the credentials of the authenticated user. WAS then uses these credentials to authorize the request.

 

Trust association model

The idea that WAS can support trust association implies that WAS security recognizes and processes HTTP requests received from a reverse proxy server. WAS and the proxy server engage in a contract in which WAS gives its full trust to the proxy server and the proxy server applies its authentication policies on every Web request that is dispatched to WAS. This trust is validated by the interceptors that reside in WAS environment for every request received. The method of validation is agreed upon by the proxy server and the interceptor.

Run in trust association mode does not prohibit WAS from accepting requests that did not pass through the proxy server. In this case, no interceptor is needed for validating trust. It is possible, however, to configure WAS to strictly require that all HTTP requests go through a reverse proxy server. In this case, all requests that do not come from a proxy server are immediately denied by WAS.

The flow can be described as follows:

  1. The user hits WebSEAL (possibly via other proxies) and is prompted to authenticate.

  2. WebSEAL authenticates the user, acquires credentials for the user from the user registry and possibly authorizes the request.

  3. WebSEAL augments the request with an additional HTTP header (iv-creds) that contains the user's credentials.

    The password contained in the Basic Authentication header is changed so it matches a configured SSO user. This request is sent to WAS.

  4. WAS receives the request and calls a TAI method to determine whether the request is from a perimeter authentication service that has already authenticated the user.

  5. WAS calls a TAI method to establish trust with the perimeter authentication server and retrieve the credentials.

    This method establishes trust with WebSEAL by checking the BA header contains the correct password for the configured SSO user. The TAM authorization server is contacted to make this decision. The TAI is transport agnostic and processes HTTP and HTTPS requests in an identical manner.

    Trust between WebSEAL and WAS cannot be established using mutually authenticated SSL sessions and can only be established by verifying the SSO password. No checking of certificates is performed by the TAI.

    The iv-creds header is then extracted from the request and used to construct a PDPrincipal object. A credential object containing user and group information is constructed from information contained in the PDPrincipal. The Principal and the Credential objects are inserted into a JAAS Subject which is returned from the call. At this point WAS has valid credentials that it can use for making authorization decisions in the usual J2EE manner. In addition, the Subject now contains the PDPrincipal object which application code can access if needed.

  6. If a remote call is made to an EJB on a downstream server.

    The credential information (that was initially extracted in the TAI) is serialized and sent to the downstream server. In addition, if a cluster is in place, the serialized Subject is also replicated horizontally using the WAS propagation framework.

 

Supported Interfaces

WAS supports the following trust association interceptor (TAI) interfaces:

com.ibm.ws.security.web.WebSealTrustAssociationInterceptor

Implements WAS TAI interface. Provided to support WebSEAL V4.1.

com.ibm.ws.security.web.TAMTrustAssociationInterceptorPlus

Implements the new WAS interface. Supports WAS V5.1.1 and later. Does not support WebSEAL V4.1.

The new TAI does not directly contact LDAP unlike the previous TAI. It instead contacts the TAM Authorization Server which validates the SSO password to establish trust with WebSEAL . This means that additional configuration is required on the WAS side to ensure that the TAI can reach the TAM Authorization Server.

 

IBM WAS: WebSEAL Integration

The integration of WebSEAL and WAS security is achieved by placing the WebSEAL server at the front-end as a reverse proxy server. From a WebSEAL management perspective, a junction is created with WebSEAL on one end, and WAS Web server on the other end. A junction is a logical connection created to establish a path from the WebSEAL server to another server.

In this setup, a request for Web resources stored in a protected domain of WAS is submitted to the WebSEAL server where it is authenticated against the WebSEAL security realm. If the requesting user has access to the junction, the request is transmitted to the WAS HTTP server through the junction, and then to the application server.

Meanwhile, the WAS validates every request that comes through the junction to ensure that the source is a trusted party. This process is referenced as validating the trust and it is performed by a WebSEAL product-designated interceptor. If the validation is successful, the WAS authorizes the request by checking whether the client user has the required permissions to access the Web resource. If so, the Web resource is delivered to the WebSEAL server, through the Web server, which then gives it to the client user.

 

WebSEAL server

The policy director delegates all of the Web requests to its Web component, the WebSEAL server. One of the major functions of the server is to perform authentication of the requesting user. The WebSEAL server consults a LDAP directory. It can also map the original user ID to another user ID, such as when global single signon (GSO) is used.

For successful authentication, the server plays the role of a client to WAS when channeling the request. The server needs its own user ID and password to identify itself to WAS. This identity must be valid in the security realm of WAS. The WebSEAL server replaces the basic authentication information in the HTTP request with its own user ID and password. In addition, WAS must determine the credentials of the requesting client so that the application server has an identity to use as a basis for its authorization decisions. This information is transmitted through the HTTP request by creating a header called iv-creds with the Tivoli Access Manager user credentials as its value.

 

HTTP server

The junction created in the WebSEAL server must get to the HTTP server that serves as WAS front end. However, the HTTP server is shielded from knowing that trust association is used. As far as it is concerned, the WebSEAL product is just another HTTP client, and as part of its normal routines, it sends the HTTP request to WAS. The only requirement on the HTTP server is a SSL configuration using server authentication only. This requirement protects the requests that flow within the junction.

 

Web collaborator

When trust association is enabled, the Web collaborator manages the interceptors that are configured in the system. It loads and initializes these interceptors when you restart your servers. When a request is passed to WAS by the Web server, the Web collaborator eventually receives the request for a security check. Two actions must take place:

  1. The request must be authenticated.
  2. The request must be authorized.

The Web authenticator is called to authenticate the request by passing the HTTP request. If successful, a good credential record is returned by the authenticator, which the Web collaborator uses to base its authorization for the requested resource. If the authorization succeeds, the Web collaborator indicates to WAS that the security check has succeeded and that the requested resource can be served.

 

Web authenticator

The Web authenticator is asked by the Web collaborator to authenticate a given HTTP request. Knowing that trust association is enabled, the task of the Web authenticator is to find the appropriate trust association interceptor to direct the request for processing. The Web authenticator queries every available interceptor. If no target interceptor is found, the Web authenticator processes the request as though trust association is not enabled.

For an HTTP request sent by the WebSEAL server, the WebSEAL trust association interceptor replies with a positive response to the Web authenticator. Subsequently, the interceptor is asked to validate its trust association with the WebSEAL server and retrieve the Subject, using the new trust association interceptor (TAI) interface, or user ID, using the old TAI interface, of the original user client.

Note: The new Trust Association Interceptor (TAI) interface, com.ibm.wsspi.security.tai.TrustAssociationInterceptor, supports several new features and is different from the existing com.ibm.websphere.security.TrustAssociationInterceptor interface. Although the existing interface is still supported, it is being deprecated in a future release.

WAS V4 through WAS V5.x support the com.ibm.websphere.security.TrustAssociationInterceptor.java interface. WAS V6 supports the com.ibm.wsspi.security.tai.TrustAssociationInterceptor interface

For more information, see Trust association interceptor support for Subject creation .

 

Trust association interceptor interface

The intent of the trust association interceptor interface is to have reverse proxy security servers (RPSS) exist as the exposed entry points to perform authentication and coarse-grained authorization, while the WAS enforces further fine-grained access control. Trust associations improve security by reducing the scope and risk of exposure.

In a typical e-business infrastructure, the distributed environment of a company consists of Web application servers, Web servers, legacy systems, and one or more RPSS, such as the Tivoli WebSEAL product. Such reverse proxy servers, front-end security servers, or security plug-ins registered within Web servers, guard the HTTP access requests to the Web servers and the Web application servers. While protecting access to the Uniform Resource Identifiers (URIs), these RPSS perform authentication, coarse-grained authorization, and request routing to the target application server.

 

Using the trust association interceptor feature

The following points further describe the benefits of the trust association interceptor (TAI) feature:

  • RPSS can authenticate WAS users up front and send credential information about the authenticated user to WAS so that WAS can trust the RPSS to perform authentication and not prompt the end user for authentication data later. The strength of the trust relationship between RPSS and WAS is based on the criteria of trust association that is particular to a RPSS and enforced through the TAI implementation. This level of trust might need relaxing based on the environment. Be aware of the vulnerabilities in cases where the RPSS is not trusted, based on a security technology.

  • The end user credentials most likely are sent in a special format as part of the Hypertext Transfer Protocol (HTTP) headers as in the case of RPSS authentication. The credentials can be a special header or a cookie. The data that passes is implementation specific, and the TAI feature considers this fact and accommodates the idea. The TAI implementation works with the credential data and returns a Subject, using the new TAI interface, or a user ID, using the old TAI interface, that represents the end user. WAS uses the information to enforce security policies.

 

Configuration procedure

     

  1. TAM Configuration

    2. A user needs to be created in TAM that will be the WebSEAL trusted user, or Single sign-on user, used by the TAI as part of trust establishment.

    For example...

    user create sso cn=sso,o=ibm,c=au sso sso ssopwd
    user modify ssouser account-valid yes

     

  2. WebSEAL Configuration

    3. A junction needs to be created between the WebSEAL instance and WAS ensuring that the iv-creds and the HTTP Basic Authentication headers are passed in the request. The Basic Authentication header should contain the password for the WebSEAL trusted user (i.e. the Single sign-on user). The username in the Basic Authentication header is incidental and the value does not matter. The TAI will use the login id property value configured in WAS as the user to authenticate with the password in the Basic Authentication header.

    For example...

    server task "webseal_instance_name" create -b supply -c iv-creds -t tcp -h "websphere_hostname" -p "websphere_app_port_number" "junction_name"

    The -b supply option ensures that the WebSEAL server passes the HTTP Basic Authentication header in the request

    The -c iv-creds option ensures that the WebSEAL server passes the iv-creds header in the request

     

  3. TAM Web Plug-ins Configuration

    4. When configuring the Plug-in for Web Servers, ensure that the iv-creds and the Basic Authentication headers are being passed in the request. Also ensure that the Basic Authentication header contains the password for the Single sign-on user.

    For example... 

    [common-modules]
authentication = BA
session = session-cookie
post-authzn = BA
post-authzn = iv-headers

[iv-headers]
accept = all
generate = iv-creds

[BA]
strip-hdr = always
add-hdr = supply
supply-password = "sso_user_password"

     

  4. WAS Configuration

    5. The TAI must validate the credential information passed in the iv-creds header with TAM. Therefore it must be ensured that the Tivoli Access Manager Java runtime environment has been configured and that server SSL configuration has been performed. If the configuration is to occur across multiple WAS servers in a ND then it is required that the properties file generated during server SSL configuration is in the same location on all servers. This location need only be the same relative to the WebSphere install directory if the ${WAS_INSTALL_ROOT} variable is used.

    If AMWAS for WAS 5.11 or the AM JACC provider for WAS 6.0 has not been configured.

    • Configure AMJrte.

      java -Djava.ext.dirs -Dpd.home="%WAS_HOME%\java\jre\PolicyDirector" com.tivoli.pd.jcfg.PDJrteCfg -action config -was -host "policy_server_host"

    • Run server SSL configuration

      java com.tivoli.pd.jcfg.SvrSslCfg -action config -admin_id "TAM_admin_user" -admin_id_pwd "TAM_admin_user_password" -appsvr_id "app_server_name" -port "app_server_port" -mode remote -policysvr "host:port:rank" -authzsvr "host:port:rank" -cfg_file "cfg_prop_file_to_create" -key_file "cert_and_key_file_to_create"

     

  5. Ensure that LTPA is the active authentication mechanism.

    6. From the WAS console, go to...

    Security | Global Security

    ...and ensure that the Active authentication mechanism is set to Lightweight Third Party Authentication (LTPA)

    If not LTPA choose LTPA in the dropdown box, click apply and then save the changes

     

  6. Enable trust association

    7. From the WAS console, go to...

    Security | Global Security | Authentication Mechanisms | LTPA | Trust Association

    Set the check box in enable trust association, click apply, and then save the changes

     

  7. Create the WebSEAL trust association interceptor properties

    8. From the WAS console, go to...

    Security | Global Security | Authentication Mechanisms | LTPA | Trust Association | Interceptors | com.ibm.ws.security.web.TAMTrustAssociationInterceptorPlus | Custom properties | New

    Create the configuration properties, ensuring that apply is pressed between properties.

    • com.ibm.websphere.security.webseal.checkViaHeader

      true/false

      The TAI can be configured so that the via header can be ignored when validating trust for a request. If the check via header property is set to false then none of the hosts in the via header need to be trusted. This also means that the trusted hostnames and host port properties do not need to be set in WebSphere. Therefore the only mandatory property when check via header is false is...

      com.ibm.websphere.security.webseal.loginId

      The default value of the check via header property is false.

    • com.ibm.websphere.security.webseal.loginId

      string

      Username of the WebSEAL trusted user. This is the Single sign-on user that will be authenticated using the password in the Basic Authentication header inserted by WebSEAL in the request. The format of the username is the short name representation.

      This is a mandatory property. If it is not set in WAS then TAI initialization will fail.

    • com.ibm.websphere.security.webseal.id

      comma separated list of strings

      The TAI can be configured to ensure that specified headers exist in the request. If not all of the configured headers exist in the request then trust can not be established.

      The default value for the id property is iv-creds. Any other values set in WebSphere are added to the list along with iv-creds.

    • com.ibm.websphere.security.webseal.hostnames

      comma separated list of strings

      Any hosts that are trusted need to be listed in this property. If a host is not listed in this property then requests arriving via that host may not be trusted. This depends upon the value of the via depth and the ignore proxy properties.

      If the checkViaHeader property is not set or is set to false then the trusted hostnames property has no influence. If the checkViaHeader property is set to true and the trusted hostnames property is not set in WAS then TAI initialization will fail.

    • com.ibm.websphere.security.webseal.ports

      comma separated list of integers

      Any hosts that are trusted need to have their ports listed in this property. If a port is not listed in this property then requests arriving from that port may not be trusted. This depends upon the value of the via depth and the ignore proxy properties.

      If the checkViaHeader property is not set or is set to false then the trusted host ports property has no influence.

      If the checkViaHeader property is set to true and the trusted host ports property is not set in WebSphere then TAI initialization will fail.

    • com.ibm.websphere.security.webseal.viaDepth

      positive integer

      The TAI can be configured to check only a specified number of source hosts in the via header to ensure that those hosts are trusted sources. By default every host in the via header is checked for trust and if any of the hosts are not trusted then trust cannot be established. If not all hosts in the via header are required to be trusted then the via depth property can be set to indicate the number of hosts that are required to be trusted.

      For example...

      Via: HTTP/1.1 webseal1:7002, 1.1 webseal2:7001

      If the via depth property is not set, is set to 2 or is set to 0, and a request with the above via header is received then both webseal1:7002 and webseal2:7001 need to be trusted.

      com.ibm.websphere.security.webseal.hostnames = webseal1,webseal2

      com.ibm.websphere.security.webseal.ports = 7002,7001

      If the via depth property is set to 1 and the above request is received then only the last host in the via header needs to be trusted.

      com.ibm.websphere.security.webseal.hostnames = webseal2

      com.ibm.websphere.security.webseal.ports = 7001

      If the via depth property is set to 0 then all hosts in the via header will be checked for trust.

      If the via depth property is set to a negative value and the check via header property is set to true then the TAI initialization will fail.

      The default value for the via depth property is 0.

    • com.ibm.websphere.security.webseal.ssoPwdExpiry

      positive integer

      Once trust has been established for a request the password for the Single sign-on user is cached for subsequent trust validation of requests. This saves the TAI from having to re-authenticate the Single sign-on user with Tivoli Access Manager for every request therefore increasing performance. The cache timeout period can be modified by setting the Single sign-on password expiry property to the required time in seconds. If the password expiry property is set to 0, the cached password will never expire.

      If the password expiry is set to a negative value then the TAI initialization will fail.

      The default value for the password expiry property is 600.

      com.ibm.websphere.security.webseal.ignoreProxy

      true/false

      The TAI can be configured so that any hosts in the via header that are proxies do not need to be trusted hosts. It works by checking the comments field of the hosts entry in the via header to see if that host is a proxy. This is not a fail safe method because not all proxies insert comments in the via header indicating that they are proxies. The default value of the ignore proxy property is false.

      If the check via header property is set to false then the ignore proxy property has no influence in establishing trust.

    • com.ibm.websphere.security.webseal.configURL

      URL

      For the TAI to be able to establish trust for a request it requires that SvrSslCfg has been run for the WebSphere Java Virtual Machine resulting in a properties file being created. This properties file is used by the TAI to create a context so that the SSO password can be validated by TAM.

      If the configuration is to occur across multiple WAS servers in a ND then it is required that the properties file generated during server SSL configuration is in the same location on all servers. This location need only be the same relative to the WebSphere install directory if the ${WAS_INSTALL_ROOT} variable is used.

      Example...

      com.ibm.websphere.security.webseal.configURL = ${WAS_INSTALL_ROOT}/java/jre/PdPerm.properties

      Using the above property in a ND environment the properties file generated during server SSL configuration must be located in the java\jre location relative to the WebSphere installation directory on all servers.

      If this properties file is not at the default url...

      file://java.home/PdPerm.properties

      ...then the correct url of the properties file must be set in the config URL property. If this property is not set and the SvrSslCfg generated properties file is not in the default location, the TAI initialization will fail.

      The default value for the config URL property is file://java.home/PdPerm.properties

      Save the changes and then restart WebSphere to activate.

 

See Also


Trust association interceptor support for Subject creation