Configure IBM Security Access Manager for authentication only

Configure IBM Security Access Manager for authentication only | HCL DX

HCL DX and IBM WebSphere Application Server support the Trust Association Interceptors (TAI) that IBM Security Access Manager provides. If we use ISAM for authorization, we must also use ISAM for authentication. Using ISAM only for authorization is not supported. We use the pdadmin utility to support ISAM administrative functions within HCL DX. For more info on pdamin, see the WebSEAL Administration Guide.
The junctions defined in the following instructions are configured for routing...
WebSEAL > HTTP server > HCL DX

If there is no HTTP server, modify the junction target host name and port values to enable direct communication from WebSEAL to HCL DX.
The following examples do not show any load balancing or other performance-related request features in WebSEAL.
We can also generate WebSEAL LTPA Tokens in WebSEAL for SSO to WebSphere Application Server.
For clustered environments, complete the validate-pdadmin-connection task on all nodes in the cluster. Complete all other steps on the primary node only.

Configure ISAM for authentication only

Start the ISAM policy and authorization servers, which are mandatory for successful configuration and for single sign-on (SSO) to occur.

Create the virtual host TCP junction on the WebSEAL server...

Open a pdadmin command from any node that has a ISAM run time component installed. We can use the ISAM Server node, WebSEAL node, or the HCL DX node.

Create a virtual host junction...

pdadmin> server task host-webseald-host virtualhost create -t type -h hostname [options] vhost-label

Mandatory parameters:

instance-webseald-host

WebSEAL instance, for example, web1
The literal string -websealed-
host name, for example, webseal.myco.com

The resulting combination would be...
web1-websealed-webseal.myco.com

We can use the pdadmin server list command to display the correct format of the server name.
vhost-label Name for the virtual host junction. Junctions are mounted at the root of the WebSEAL protected object space. The junction label must be unique within each instance of WebSEAL. The label name must not contain the forward slash character (/).
-t type Whether the junction is encrypted (-t ssl) or not encrypted (-t tcp). See the WebSEAL Administration Guide for other possible values.
-h hostname Backend server to which the junction connects. In most situations, the host name is the HTTP server that sits in front of HCL DX.

Optional parameters:

-p port Port number for the backend server to which the junction connects. If not specified, the default value is 80 for HTTP or 443 for HTTPS. It is best to specify this valu explicitly in the junction creation command even if the default values are in use.
-v vhost[:port] Virtual host name and port number that defines the junction. WebSEAL maps incoming requests to this host name and port to this junction. Name must be mapped in DNS to the WebSEAL server. If not specified, the values default to the -h hostname and -p port values.
-c header_type Insert the ISAM client identity in HTTP headers across the junction. The header_type argument can include any combination of the following ISAM HTTP header types:

{iv_user|iv_user-l}
iv_groups
iv_creds
all

The header types must be comma-separated, and cannot have a space between the types. For example: -c iv_user,iv_groups. Specifying -c all is the same as specifying -c iv_user,iv_groups,iv_creds. This parameter is valid for all junctions except for the type of local. The setting here depends on how we want the TAI running within WebSphere Application Server to operate. In certain modes, the TAI might be looking for the presence of one or more of these headers. The TAI looks for these headers to know that it must claim the request when interrogated by WebSphere Application Server security. This setting must be set to match what the TAI is looking for.
-b Controls how WebSEAL passes authentication information to the backend server. Usually this setting depends on how we want the TAI to be configured in WebSphere to validate a trust relationship with WebSEAL. The usual option that is chosen is -b supply. For more information, see the WebSEAL Administration Guide or the ETAI installation and configuration documentation.
-k Controls whether WebSEAL includes its own session cookie in the request to the backend server. In some situations, sending the WebSEAL session cookie to the backend server is necessary. This action is necessary to support single sign-on from HCL DX to other backend services where WebSEAL also protects those backend services.
-q Junctions to HCL DX whether direct or through an HTTP server does not support the -q option the query_contents function. Query_contents is not possible on HCL DX.

The following is a sample command to create a virtual host TCP junction, on the web1 WebSEAL instance that is running on a host webseal.myco.com, for the virtual host name portalvhost.myco.com running on port 80 that requires a TAI in WebSphere Application Server. The virtual host junction is labeled vhost_junction_portal_1. The portal or http server is running on host portal.myco.com and is using port 8080:
pdadmin> server task web1-webseald-webseal.myco.com virtualhost create -t tcp -v portalvhost.myco.com:80 -h portal.myco.com -p 8080 -c all -k -b supply vhost_junction_portal_1

Optional: To use an SSL junction, set up a key and truststore with certificates. Follow the instructions in steps 1-3 of the topic about configuring SSL. Then, complete the following steps to create the virtual host junction:

Use the IBM Key Management utility to load the web server certificate into the key ring for the appropriate instance of WebSEAL. See the HTTP Server documentation for more details.

Restart WebSEAL.

Follow the steps mentioned earlier to create the junction. But change the -t value to ssl and add the appropriate set of options from the Mutually Authenticated SSL junctions portion of the WebSEAL Administration Guide: -B, -D, -K, -U, and -W.

Enter the following tasks on the pdadmin command to create the trusted user account:
This step is mandatory for TAI junctions only. Skip this step if we created an LTPA junction. An LTPA junction is created when you use the -A parameter. Refer to the ISAM for e-business documentation for this advanced configuration.
The trusted user account in the ISAM user registry must be the same as the one that the TAI within WebSphere Application Server is configured to use. It is the ID that WebSEAL uses to identify itself to WebSphere Application Server by using the -b supply option, and it is one of the underlying TAI security requirements.
To prevent potential vulnerabilities, do not use the sec_master or wpsadmin users for the trusted user account. The trusted user account must be a dedicated user account for the purposes of communication between WebSEAL and the TAI.

pdadmin> user create webseal_userid webseal_userid_DN firstname surname password

pdadmin> user modify webseal_userid account-valid yes

Clustered environments: Complete this step on all nodes. Run the following task in the wp_profile_root/ConfigEngine directory to validate that the PdPerm.properties file is correct and that communication between HCL Portal and the ISAM server works:
Run validate-pdadmin-connection on the HCL DX node or on each node in a clustered environment. In a clustered environment, WasPassword is the dmgr administrator password. The wp.ac.impl.PDAdminPwd is the ISAM administrative user password.
./ConfigEngine.sh validate-pdadmin-connection -DWasPassword=foo -Dwp.ac.impl.PDAdminPwd=foo

If the task does not run successfully: Run the run-svrssl-config task to create the properties file. For information, refer to Create the PdPerm.properties file. Then, run the validate-pdadmin-connection task again. If the task is not successful after a second attempt, do not proceed with any subsequent steps. The fact that the task does not run successfully indicates that the portal cannot connect to the ISAM server. Troubleshoot the connectivity issue between the portal instance and the ISAM server.

If you are using junctions that require a Trust Association Interceptor in WebSphere Application Server, we must install and configure the TAI if it was not already set up. To configure the ISAM Trust Association Interceptor (TAI++), complete the following steps:

Edit...
wp_profile_root/ConfigEngine/properties/wkplc_comp.properties file

Enter the following parameters under the WebSphere Application Server WebSEAL TAI parameters heading:

TAMTAIName=com.ibm.ws.security.web.TAMTrustAssociationInterceptorPlus

For wp.ac.impl.TAICreds, type the headers that are inserted by WebSEAL that the TAI uses to identify the request as originating from WebSEAL. Refer to the values entered for the -c header_type parameter. For example, if you entered -c iv-user, then set...
wp.ac.impl.TAICreds=iv-user

If you entered -c all, then set...
wp.ac.impl.TAICreds=iv-user,iv-groups,iv-creds

Important: Never specify a header name for wp.ac.impl.TAICreds that the WebSEAL server is not sending over the junction.

For wp.ac.impl.hostnames, enter the fully qualified URL for HCL DX. This value must match the -h and -p parameters from the junction creation command.

For wp.ac.impl.ports, enter the port number used to access the host server that is identified in wp.ac.impl.hostnames. This value must match the -p parameter from the junction creation command.

For wp.ac.impl.loginId, enter the reverse proxy identity used when we create a TCP junction. This value must match the trusted user account.

For wp.ac.impl.BaUserName, enter the reverse proxy identity used when we create an SSL junction.

For wp.ac.impl.BaPassword, enter the password for the SSL junction reverse proxy ID.

Save the changes to the properties file.

Run the following task to configure TAI for ISAM:
Clustered environments: The WasPassword is the dmgr administrative password. The wp.ac.impl.PDAdminPWD is the Security Access Manager administrative password.
./ConfigEngine.sh enable-tam-tai -DWasPassword=foo -Dwp.ac.impl.PDAdminPwd=foo

Optional: Enable user provisioning.
You must do this task only if you are using HCL DX to create and provision new users directly in LDAP, and you need these users to also be recognized by ISAM. In an enterprise deployment of HCL DX this task would be unusual, as most large deployments have a separate user provisioning process, perhaps by using IBM Security Identity Manager. HCL DX reads from LDAP but does not create new users. For more information, see the related links section.

If you are using ISAM integrated with HCL DX in a stand-alone environment that does not include a web server between WebSEAL and Portal, complete the following steps:

Log on to the WebSphere Integrated Solutions Console and go to...
Servers > Server Types > Web application servers > HCL DX > > Web container settings > Web Container > Additional Properties > Custom properties > New

Set com.ibm.ws.webcontainer.extracthostheaderport=true

Click OK.

Click New and add the trusthostheaderport custom property with a value of true.

Click OK.

Click Save to save the changes.

Log out of the WebSphere Integrated Solutions Console.

Stop and restart the appropriate servers to propagate the changes. For specific instructions, see Start and stop servers, deployment managers, and node agents.

Go to the WebSEAL node and edit the webseald-instance.conf file for the appropriate WebSEAL instance. An example is webseald-default.conf. This file sets the basicauth-dummy-passwd value to the password for the ID that WebSEAL uses to identify itself to WebSphere Application Server. This password is the trusted user ID and password that were created in an earlier step. Stop and start the WebSEAL server before you continue.

If the WebSEAL instance is on the Windows operating system, limit the length of the generated URLs. Edit the webseald-instance.conf file and change the process-root-requests property value to filter to avoid problems with WebSEAL processing.

Import HCL DX users and groups into ISAM. Enter the following commands on the ISAM administrative command, where wpsadmin is the user ID for the administrator, and wpsadmins is the administrators group name. The fully distinguished names of the user and group IDs vary depending on the LDAP settings.

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

Some functions of HCL DX require the use of the PUT, and DELETE HTTP method. By default, WebSEAL does not allow these requests. You must either allow this method at the applicable WebSEAL ACL and web server, or change the HTTP methods in the x-method-override configuration in the WebSEAL config file webseald-instance.conf.

-p port	Port number for the backend server to which the junction connects. If not specified, the default value is 80 for HTTP or 443 for HTTPS. It is best to specify this valu explicitly in the junction creation command even if the default values are in use.
-v vhost[:port]	Virtual host name and port number that defines the junction. WebSEAL maps incoming requests to this host name and port to this junction. Name must be mapped in DNS to the WebSEAL server. If not specified, the values default to the -h hostname and -p port values.
-c header_type	Insert the ISAM client identity in HTTP headers across the junction. The header_type argument can include any combination of the following ISAM HTTP header types: {iv_user\|iv_user-l} iv_groups iv_creds all The header types must be comma-separated, and cannot have a space between the types. For example: -c iv_user,iv_groups. Specifying -c all is the same as specifying -c iv_user,iv_groups,iv_creds. This parameter is valid for all junctions except for the type of local. The setting here depends on how we want the TAI running within WebSphere Application Server to operate. In certain modes, the TAI might be looking for the presence of one or more of these headers. The TAI looks for these headers to know that it must claim the request when interrogated by WebSphere Application Server security. This setting must be set to match what the TAI is looking for.
-b	Controls how WebSEAL passes authentication information to the backend server. Usually this setting depends on how we want the TAI to be configured in WebSphere to validate a trust relationship with WebSEAL. The usual option that is chosen is -b supply. For more information, see the WebSEAL Administration Guide or the ETAI installation and configuration documentation.
-k	Controls whether WebSEAL includes its own session cookie in the request to the backend server. In some situations, sending the WebSEAL session cookie to the backend server is necessary. This action is necessary to support single sign-on from HCL DX to other backend services where WebSEAL also protects those backend services.
-q	Junctions to HCL DX whether direct or through an HTTP server does not support the -q option the query_contents function. Query_contents is not possible on HCL DX.