Configure Tivoli Access Manager to perform authentication only

WebSphere Portal runs on WebSphere Application Server, which can use Trust Association Interceptors (TAIs) to provide third-party authentication. WebSphere Portal and WebSphere Application Server support a TAI that is provided by Tivoli. The following instructions explain how to configure WebSphere Portal to use this TAI. See the WebSphere Application Server documentation for additional information about TAIs.

If you use Tivoli Access Manager to perform authorization for the portal, also also use Tivoli Access Manager to perform authentication for the portal. Using Tivoli Access Manager to perform only authorization is not supported.

 

Plan considerations for WebSEAL junctions

In the configuration described here, the WebSEAL component of Tivoli Access Manager handles the user authentication, and a Trust Association Interceptor (TAI) is used by WebSphere Application Server and WebSphere Portal to accept the identification of the user as asserted by WebSEAL.

To properly secure the WebSphere Application Server and WebSphere Portal system against an attack, the TAI must still authenticate the WebSEAL server, so that only requests that are legitimately presented through that WebSEAL server are accepted. You have a choice of different ways to configure this authentication between WebSEAL and the TAI in WebSphere Application Server, depending on how much effort and performance you wish to put into securing your network. The decisions you make will determine how you set up the junctions between the WebSEAL server and WebSphere Portal.

By default, the XML configuration interface cannot access the portal through a WebSEAL junction. To enable the XML configuration interface to access the portal through a WebSEAL junction, use Tivoli Access Manager to define the configuration URL (/wps/config) within the junction as unprotected. Refer to the WebSEAL documentation for specific instructions about defining separate URLs within the junction and assigning separate ACLs to these URLs. After the configuration URL is defined as unprotected, only WebSphere Portal enforces access control to this URL. Other portal resources that are protected within the WebSEAL junction (for example, the /wps/myportal URL) are still protected by WebSEAL.

 

Nonencrypted junction using Basic Authentication

The identification of the user must be passed to the TAI in a header called iv-user, which is inserted by WebSEAL into the request that is sent from WebSEAL to the WebSphere Application Server and the WebSphere Portal servers. The junction creation option to set this up is -c iv-user. While WebSEAL can be configured to pass the user identity in other ways, the iv-user header is the only one that is supported by the TAI.

 

More advanced junction configurations

For more details and options about how to configure junctions between WebSEAL and WebSphere Application Server and WebSphere Portal, including other options for specifying the WebSEAL server identity, refer to the WebSEAL Administration Guide and to the documentation for the HTTP Server that you are using with WebSphere Application Server.

The junctions between WebSEAL and WebSphere Application Server and WebSphere Portal can be configured to be encrypted or not. Encrypted junctions enhance security by making sure that no one can eavesdrop on information that is flowing between WebSEAL, WebSphere Application Server, and WebSphere Portal. However, encrypted junctions require additional administration to move the necessary signing certificates between the systems, and also have a performance cost. If you are not comfortable that your network between the firewalls is secure against unauthorized access and observation, use encrypted junctions between WebSEAL and WebSphere Application Server/WebSphere Portal. If you are comfortable that your network is secure against unauthorized access and observation, especially for traffic across an inner firewall, you can use unencrypted junctions between WebSEAL and WebSphere Application Server/WebSphere Portal.

Set up the WebSEAL-WebSphere Application Server/WebSphere Portal junction over SSL requires that you configure WebSphere Application Server and the HTTP server that is used by WebSphere Application Server to accept inbound SSL traffic and route this traffic correctly to WebSphere Application Server and WebSphere Portal. This process includes importing the necessary signing certificates into at least the WebSEAL certificate keystore, and possibly also the HTTP server certificate keystore. Some of the steps to do this are briefly discussed in steps 1, 2, and 3 of Set up SSL for WebSphere Portal.

If you choose to use encrypted junctions between WebSEAL and WebSphere Application Server and WebSphere Portal, you can also choose to have WebSEAL identify and authenticate itself to WebSphere Application Server and the TAI using its own client-side certificate. In this case, it is possible to configure the TAI to not do any further validation of the WebSEAL server, relying on the true "mutually-authenticated through certificates" SSL connection to supply a trustable identity for the WebSEAL server.

If you choose not to use client-side certificates to identify the WebSEAL server, or if you choose not to use an SSL junction, you can identify the WebSEAL server to the TAI using a Basic Authentication (BA) header. In this case a password will be placed into the Basic Authentication header, and also configured into the TAI. This represents a "shared secret" that only the TAI and the WebSEAL server know, which allows the TAI to trust that it really is the WebSEAL server that is asserting the user's identity, and the TAI can trust it. In this case, using an SSL junction will provide additional security by protecting this Basic Authentication header from observation, but the TAI will still rely on the Basic Authentication header for identifying the WebSEAL server.

To set up the junction to use the Basic Authentication header to identify the WebSEAL server, use the -b supply option on the junction creation command. This will cause WebSEAL to build the Basic Authentication header using the user's user ID (which is ignored by the TAI, in favor of the iv-user header) and the password that is configured into WebSEAL from the webseald.conf file, on the basicauth-dummy-passwd property. The password in the webseald.conf file must match the password for the ID that is specified on the com.ibm.websphere.security.webseal.loginid property of the TAI startup parameters in the WebSphere Application Server Administrative Console. For example, if you specify com.ibm.websphere.security.webseal.loginid=mistered on the TAI startup parameters, and the password for mistered is wilbur, then specify wilbur on the basicauth-dummy-passwd property in webseald.conf on the WebSEAL server.

 

Configure Tivoli Access Manager to perform authentication for WebSphere Portal

Follow these steps to configure Tivoli Access Manager to perform authentication for WebSphere Portal:

Notes:

  • This procedure requires that you be familiar with WebSEAL administration concepts as presented in the WebSEAL Administrator's Guide. These are not the only options available for configuring WebSEAL with WebSphere Application Server. For complete descriptions of all the options, refer to the Tivoli Access Manager and WebSphere Application Server documentation.

  • This example assumes that IBM HTTP Server is the Web server.

  • The term pdadmin refers to a command line utility that supports Tivoli Access Manager administrative functions.

  • If you experience problems while performing this procedure, enable tracing to help troubleshoot. From the WebSphere Application Server Administrative Console, click Troubleshooting - Logs and Trace - WebSphere Portal - Diagnostic Trace.

  1. Install and configure WebSphere Portal, the database software that will be used with WebSphere Portal, the LDAP Directory, and Tivoli Access Manager. For more information about installing and configuring WebSphere Portal, the database software, and the LDAP directory, see Install. For more information about installing Tivoli Access Manager, see the Tivoli Access Manager Base Installation Guide.

  2. Ensure that the Tivoli Access Manager AMJRTE component on the WebSphere Portal machine is at the V 5.1 fix pack 2 level. This version of the AMJRTE component is automatically installed with WebSphere Application Server V5.1.1.

  3. WebSphere Application Server, WebSphere Portal, and Tivoli Access Manager will share the same LDAP directory. The Tivoli Access Manager configuration tool secures the LDAP namespace by modifying the LDAP Access Control List of all suffixes that are defined. This may include the suffixes that are used by WebSphere Portal to store users and groups.

    To avoid problems when WebSphere Portal searches for users, use the WebSphere Application Server Administrative Console to verify that a Bind DN and Bind DN password exist. This Bind DN and password must have sufficient access rights within the directory (at least under the subtree that is specified by the BaseDN) to do searches in both the user and group subtrees within the directory.

    When the directory is secured, WebSphere Application Server must have an identity that can read from the directory. WebSphere Application Server can use an identity that is already set up with the necessary read permission in the ACL of the directory, or you can add a new identity for WebSphere Application Server to the ACL for the directory. Setting up new identities in the ACL for the directory is a directory-specific task. Consult the directory documentation for specific instructions.

  4. Ensure that security for the portal has been enabled.

  5. If you plan to use an SSL junction, follow the instructions in steps 1-3 of Set up SSL for WebSphere Portal.

  6. Install and configure WebSEAL. Refer to the WebSEAL Installation Guide for more information.

  7. If you plan to use an SSL junction, do the following steps:

    1. Use the IBM Key Management utility to load the Web server certificate into the keyring for the appropriate instance of WebSEAL. See the IBM HTTP Server documentation for more details.

    2. Restart WebSEAL.

  8. Create the trusted user account in Tivoli Access Manager. One of the underlying security requirements of the TAI is the creation of a trusted user account in the Tivoli Access Manager user registry that WebSphere Application Server is configured to use. This is the ID and password that WebSEAL uses to identify itself to WebSphere Application Server.

    To prevent potential vulnerabilities, do not use the sec_master or wpsadmin users for the trusted user account. The trusted user account should be for the TAI only.

    On the Tivoli Access Manager machine, enter the following commands on the pdadmin command line: 

    pdadmin> user create webseal_userid webseal_userid_DN firstname surname password
pdadmin> user modify webseal_userid account-valid yes

  9. Verify connectivity to Tivoli Access Manager by running the validate-pdadmin-connection configuration task.

    1. Find the wp_root/config/wpconfig.properties file and make a backup copy.

    2. Use a text editor to open the wp_root/config/wpconfig.properties file and edit the following values in the Advanced Security Configuration section:

      Note the following:

      • Do not change any settings other than those specified in these steps. For instructions on working with these files, see Configuration properties reference for a complete properties reference, including default values.

      • Use / instead of \ for all platforms.

      • Some values, shown in italics below, might need to be modified to your specific environment.

      Input Description
      PDAdminId The user ID for the administrative TAM user.
      PDAdminPw The password for the administrative TAM user.
      PDPermPath The location of the TAM AMJRTE properties file.

    3. Save the file.

    4. Open a command prompt and change to directory was_root/bin.

    5. Enter the following commands:

      1. startServer server1

      2. stopServer WebSphere_Portal -user was_admin_userID -password was_admin_password

    6. Change to the directory wp_root/config.

    7. Enter the following command to run the appropriate configuration task for your specific operating system:

      If the configuration task fails, validate the values in the wpconfig.properties file.

  10. If the validate-pdadmin-connection task succeeds, skip to step 11. If the validate-pdadmin-connection task fails, do the following:

    1. Use a text editor to open the wp_root/config/wpconfig.properties file and enter the appropriate values in the Advanced Security Configuration section of the file. Do not change any settings other than those specified in these steps.

      Input Description
      PDServerName Unique application name used to create a new Tivoli server in the Access Manager Policy Server.

      If a server with the same name appears in the server list command, the SvrSslCfg command will fail.

      PDAdminId The user ID for the administrative TAM user.
      PDAdminPw The password for the administrative TAM user.
      PDPermPath The location of the TAM AMJRTE properties file.
      SvrSslCfgPort Configuration port for the application name.
      SvrSslCfgMode Configuration mode of the SvrSslCfg command.
      TamHost Defines the TAM Policy Server used when running PDJrteCfg.
      PDPolicyServerList Defines a hostname, port, and priority combinations for your TAM Policy servers used when running SvrSslCfg.
      PDAuthzServerList Defines a hostname, port, and priority combination for your TAM authorization servers.
      PDKeyPath Stores encryption keys used for the SSL communication between AMJRTE and

      Tivoli Access Manager.

    2. Save the file.

    3. Open a command prompt and change to directory was_root/bin.

    4. Enter the following commands:

      1. startServer server1

      2. stopServer WebSphere_Portal -user was_admin_userID -password was_admin_password

    5. Change to the directory wp_root/config.

    6. Enter the following command to run the appropriate configuration task for your specific operating system:

      If the configuration task fails, validate the values in the wpconfig.properties file.

  11. Run the enable-tam-tai configuration task to create a WebSEAL junction. This task can create a TCP or an SSL junction. Options for creating junctions might vary depending on your environment. If you choose to create your own junction, refer to the WebSEAL documentation for more information.

    1. Use a text editor to open the wp_root/config/wpconfig.properties file and enter the appropriate values in the Advanced Security Configuration section of the file. Do not change any settings other than those specified in these steps.

      Input Description
      PDAdminId The user ID for the administrative TAM user.
      JunctionPoint The WebSEAL junction point to the WebSphere Portal instance.
      JunctionType The type of junction to be created in TAM. Accepted values are tcp and ssl.
      PDAdminPw The password for the administrative TAM user.
      PDPermPath The location of the TAM AMJRTE properties file.
      WebSealInstance Specifies the WebSEAL instance used to create the junction.
      TAICreds The headers inserted by WebSEAL that the TAI uses to identify the request as originating from WebSEAL.
      WebSealHost Optional parameter that sets the WebSEAL TAI's hostnames parameter.
      WebSealPort Optional parameter that sets the WebSEAL TAI's ports parameter.
      WpsHostName (set to fully qualified hostname) The fully-qualified URL to WebSphere Portal.
      WpsHostPort The port number used to access the host machine identified by the WpsHostName property.
      WebSealUser (for tcp junctions only) The reverse proxy identity used when you create a TCP junction.
      BaUserName (for ssl junctions only) The reverse proxy identity used when you create an SSL junction.
      BaPassword (for ssl junctions only) When you create an SSL junction, you can provide a password to the identity representing the reverse proxy on every request.

    2. Save the file.

    3. Open a command prompt and change to directory was_root/bin.

    4. Enter the following commands:

      1. startServer server1

      2. stopServer WebSphere_Portal -user was_admin_userID -password was_admin_password

    5. Change to the directory wp_root/config.

    6. Enter the following command to run the appropriate configuration task for your specific operating system:

      • UNIX: ./WPSconfig.sh enable-tam-tai -DSmAdminPw=password -DBaPassword=password

      • Windows: WPSconfig.bat enable-tam-tai -DSmAdminPw=password -DBaPassword=password

      If the configuration task fails, validate the values in the wpconfig.properties file.

  12. If you created a TCP junction in the previous step, go to the WebSEAL machine and edit the webseald.conf file for the appropriate WebSEAL instance to set the basicauth-dummy-passwd value to the password for the ID that WebSEAL uses to identify itself to WebSphere Application Server. This user ID and password were created in step 7. Stop and start the WebSEAL server before continuing.

  13. The length of the generated portal URLs may cause problems if your WebSEAL instance is on the Windows platform. Edit the webseald.conf file and change the process-root-requests property value to filter to avoid problems with WebSEAL processing.

  14. Several portlets, including the Resource Permissions portlet and the productivity components editors, use relative Javascript within the portlet or component. These portlets and components will not function correctly when accessed through a WebSEAL juction.

    For this Javascript to be interpreted and followed correctly, WebSeal must be configured to insert the junction point into the Javascript. One way to accomplish this is through the use of the JMT table function in WebSEAL.

    To enable the JMT table function, define an ASCII text file called jmt.conf. The location of this file is specified in the [junction] stanza of the webseald.conf configuration file: jmt-map = lib/jmt.conf.

    The format for data entry in the table consists of the junction name, a space, and the resource location pattern. You can also use wildcard characters to express the resource location pattern. In the following example of the junction mapping configuration file, two back-end servers are junctioned to WebSEAL at /jctA and /jctB: 

    /jctA /documents/release-notes.html
/jctB /wps/*

    where jctB is the junction for WebSphere Portal.

    See the WebSEAL Administrator's Guide for more information.

  15. Optional If you would like to enable automatic user provisioning to TAM, follow this step.

  16. If you enabled automatic user provisioning to TAM, you have already imported WebSphere Portal users and may skip this step. Import WebSphere Portal users and groups into Tivoli Access Manager by entering the following commands on the Tivoli Access Manager administrative command line, where wpsadmin is the user ID for the portal administrator, and wpsadmins is the portal administrators group name. 
        user import wpsadmin uid=wpsadmin,cn=users,dc=ibm,dc=com
    user modify wpsadmin account-valid yes
    group import wpsadmins cn=wpsadmins,cn=groups,dc=ibm,dc=com

  17. Verify connectivity to Tivoli Access Manager by running the validate-pdadmin-connection configuration task.

    1. Use a text editor to open the wp_root/config/wpconfig.properties file and enter the appropriate values in the Advanced Security Configuration section. Do not change any settings other than those specified in these steps.

      Input Description
      PDAdminId The user ID for the administrative TAM user.
      PDAdminPw The password for the administrative TAM user.
      PDPermPath The location of the TAM AMJRTE properties file.

    2. Save the file.

    3. Open a command prompt and change to directory was_root/bin.

    4. Enter the following commands:

      1. startServer server1

      2. stopServer WebSphere_Portal -user was_admin_userID -password was_admin_password

    5. Change to the directory wp_root/config.

    6. Enter the following command to run the appropriate configuration task for your specific operating system:

      If the configuration task fails, validate the values in the wpconfig.properties file.

  18. Use the WebSphere Application Server Administrative Console to review the updates:

    1. In the WebSphere Application Server Administrative Console, click Security - Authentication mechanisms - LTPA. Click Trust Association under Additional Properties.

    2. Select the Trust Association Enabled check box. Click OK, then click Save.

    3. Click Security - Authentication mechanisms - LTPA. Click Trust Association under Additional Properties. Click Interceptors under Additional Properties.

    4. Click com.ibm.ws.security.web.WebSealTrustAssociationInterceptor.

    5. Click Custom Properties under Additional Properties.

  19. Optional Enable automatic user provisioning to Tivoli Access Manager. There are two ways to create users in WebSphere Portal:

    • Self-registration: This feature is enabled by default.

    • Manage Users and Groups portlet: Administrators can use this portlet to create WebSphere Portal users.

    When users are created in WebSphere Portal, they are not automatically imported into Tivoli Access Manager. Enabling automatic user provisioning to Tivoli Access Manager changes this behavior. Once this feature is enabled, users are automatically imported into Tivoli Access Manager whenever they are created in WebSphere Portal. When user provisioning to Tivoli Access Manager, anyone with access to the public portal URL can become an active user in Tivoli Access Manager as long as the portal's self-registration feature remains enabled.

    Follow these steps to enable user provisioning to Tivoli Access Manager:

    1. Open a command prompt and change to directory was_root/bin.

    2. Enter the following commands:

      1. startServer server1

      2. Check the status of the WebSphere Portal being started by entering this command all on one line:

        serverStatus WebSphere_Portal -user was_admin_userID -password was_admin_password

      3. If not started, start the WebSphere Portal server with the following command for your operating system:

        1. UNIX:./startServer.sh WebSphere_Portal -user was_admin_userID -password was_admin_password

        2. Windows: startServer.bat WebSphere_Portal -user was_admin_userID -password was_admin_password

    3. Change to the directory wp_root/config.

    4. Enter the following command to run the appropriate configuration task for your specific operating system:

  • Proceed to External authentication, where you will verify that the TAI is working properly.

     

    See also

     

    WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

     

    IBM is a trademark of the IBM Corporation in the United States, other countries, or both.

     

    Tivoli is a trademark of the IBM Corporation in the United States, other countries, or both.