Configure IBM Security Verify Access for authentication, authorization, and the Credential Vault

Configure IBM Security Verify Access (ISAM) for authentication, authorization, and the Credential Vault

We can used one task to configure IBM Security Verify Access (aka ISAM) with HCL WebSphere Portal (DX).

Create PdPerm.properties

Start the ISVA policy and authorization servers.

Create the junctions on the WebSEAL server.
Create a virtual host TCP junction:

Open a pdadmin command from any node that has a Security Access Manager run time component installed. Use the Security Access Manager Server node, WebSEAL node, or the HCL WebSphere Portal node.

The general format for the pdadmin command to create a virtual host junction is
pdadmin> server task WebSEAL-instance-webseald-WebSEAL-host virtualhost create -t type -h hostname [options] vhost-label

Mandatory parameters

WebSEAL-instance The configured name of a single WebSEAL instance, for example web1
webseald The literal string -websealed-
WebSEAL-Host The host name, for example, webseal.myco.com. The resulting combination would be...
web1-websealed-webseal.myco.com

Use the pdadmin server list command to display the correct format of the server name.
vhost-label Name for the virtual host junction. Virtual host junctions are always mounted at the root of the WebSEAL object space. We can refer to a junction in the pdadmin utility with this label. The virtual host junction label must be unique within each instance of WebSEAL. Because the label represents virtual host junctions in the protected object space, the label name must not contain the forward slash character (/).
-t type Whether the junction is encrypted (-t ssl) or not encrypted (-t tcp). This parameter is mandatory when creating a virtual host junction. See the WebSEAL Administration Guide.
-h hostname Defines the backend server to which the junction connects. In most situations, the host name is the HTTP server that sits in front of HCL WebSphere Portal. This parameter is mandatory when creating a virtual host junction.

Optional parameters [options]

-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 value 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. If not specified, the values default to the -h hostname and -p port values.
-c header_type Insert the ISVA client identity in HTTP headers across the junction. The header_type argument can include any combination of the following ISVA 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. 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. Consult the WebSphere system administrator if we are in doubt as to how the TAI is configured.
-b This option 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 chosen is -b supply.
-k This option 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 WebSphere Portal to other backend services where WebSEAL also protects those backend services.

Junctions to HCL WebSphere Portal whether direct or through an HTTP server does not support the -q option the query_contents function. Query_contents is not possible on HCL WebSphere Portal

The following information is a sample command to create a virtual host TCP junction, on the web1 WebSEAL instance 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 virtual host junction host name must be mapped in DNS to the WebSEAL server. 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, more steps are needed before we can create the junction. The necessary key and truststore must be set up with the correct certificates to enable SSL. 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.

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 we use the -A parameter. Refer to the Security Access Manager for e-business documentation for this advanced configuration. The trusted user account in the Security Access Manager user registry must be the same as the one the TAI within WebSphere Application Server is configured to use. It is the ID that WebSEAL uses to identify itself to WebSphere Application Server 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

On all nodes validate PdPerm.properties is correct and that communication between HCL WebSphere Portal and the Security Access Manager server works:
cd WP_PROFILE/ConfigEngine
./ConfigEngine.sh validate-pdadmin-connection -DWasPassword=foo -Dwp.ac.impl.PDAdminPwd=foo

wp.ac.impl.PDAdminPwd is the Security Access Manager administrative user password.
If the task does not run successfully: Run the run-svrssl-config task to create the properties file. For information, refer to Create PdPerm.properties. 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 the task does not run successfully indicates the portal cannot connect to the Security Access Manager server. Troubleshoot the connectivity issue between the portal instance and the Security Access Manager server.

Edit wkplc_comp.properties file in the following directory:
WP_PROFILE/ConfigEngine/properties

Complete this step on all nodes.

Update properties in the wkplc_comp.properties.

Update the Namespace management parameters in wkplc_comp.properties for Advanced Security Configuration using External Security Managers

wp.ac.impl.EACserverName Namespace context to distinguish externalized portal role names from other role names in the namespace. If set, wp.ac.impl.EACcellName and wp.ac.impl.EACappname must also be set. All three parameters must be set or none of them.
wp.ac.impl.EACcellName Namespace context to distinguish externalized portal role names from other role names in the namespace. If set, wp.ac.impl.EACserverName and wp.ac.impl.EACappname must also be set.
wp.ac.impl.EACappname Namespace context to distinguish externalized portal role names from other role names in the namespace. If set, wp.ac.impl.EACcellName and wp.ac.impl.EACserverName must also be set.
wp.ac.impl.reorderRoles Set false to keep the role order or true to reorder the roles by resource type first.

PDJrteCfg command and file system parameters

wp.ac.impl.TamHost Security Access Manager Policy Server used when we run PDJrteCfg.

WebSphere Application Server WebSEAL TAI parameters
Cluster note: Complete this step on all nodes in the cluster. The following parameters must match on all nodes in the clustered environment. The one exception is the wp.ac.impl.PDServerName parameter.

wp.ac.impl.TAICreds Headers that are inserted by WebSEAL the TAI uses to identify the request as originating from WebSEAL.
Optional: wp.ac.impl.hostnames Host name that sets the WebSEAL TAI's host name parameter. This value must match the -h and -p parameters from the junction creation command.
Optional: For wp.ac.impl.ports Port used to set the WebSEAL TAI's ports parameter. This value must match the -p parameter from the junction creation command.
wp.ac.impl.loginId Reverse proxy identity used when creating a TCP junction. This value must match the trusted user account.

Update the following parameters in wkplc_comp.properties; go to the Portal authorization parameters heading:

wp.ac.impl.PDRoot Root object space name in the Security Access Manager namespace for the resource entries for this portal. All Portal roles are installed with this entry. For multiple profiles and portal instances that all share a common Security Access Manager instance, choose a unique name for each root object space entry. This unique name helps to easily distinguish the resources for different instances. Or use a common PDRoot value for all Portal instances so that all Portal roles from any instance have a common parent. We can then use the EACappname parameter to distinguish between instances. If it better suits the administration models, we can also mix these two approaches, using a common PDRoot value for some instances, and unique PDRoot values for others.
wp.ac.impl.PDAction Custom Action created by the Security Access Manager external authorization plug-in. The combination of the action group and the action determines the Security Access Manager permission string. The permission string is used to assign membership to externalized portal roles. We might want to check with the Security Access Manager administrator to determine what they want the PDActionGroup and PDAction values to be.
wp.ac.impl.PDActionGroup Custom Action group created by the Security Access Manager external authorization plug-in. The combination of the action group and the action determines the Security Access Manager permission string. The permission string is used to assign membership to externalized portal roles.
wp.ac.impl.PDCreateAcl Set the value to true to automatically create and attach a Security Access Manager ACL when HCL WebSphere Portal externalizes the roles for a resource. Set the value to false to not create and attach a Security Access Manager ACL when HCL WebSphere Portal externalizes the roles for a resource. In this case, the Security Access Manager Administrator must manually create and attach ACLs to the object space entries for the externalized portal resources and roles. Any ACLs created manually in this way, must use the PDAction and PDActionGroup values in order for the permissions to be found.

Enter the following parameters in wkplc_comp.properties; go to the Portal vault parameters heading:
Cluster note: Complete this step on all nodes in the cluster. The following parameters must match on all nodes in the clustered environment. The one exception is the wp.ac.impl.PDServerName parameter.

wp.ac.impl.vaultType New vault type identifier representing the Tivoli GSO lockbox vault.
wp.ac.impl.vaultProperties File used to configure the vault with Security Access Manager specific user and SSL connection information.
wp.ac.impl.manageResources true if the credential vault or any custom portlets are allowed to create new resource objects in Security Access Manager. Or type false to allow only the Security Access Manager administrator to define the accessible resources to associate users with from the command line or graphical user interface.
wp.ac.impl.readOnly true to allow credential vault or any custom portlets to modify the secrets stored in Security Access Manager. Or type false to allow only the Security Access Manager administrator to modify the secrets from the command line or graphical user interface.

Save changes to the properties file.

The new TAI implementation version is only available as a download and must be added to the system. See the related links section to download the Extended Security Access Manager Trust Association Interceptor Plus (ETAI) and add the binary files to the environment. WebSphere Application Server deprecated the TAI implementation available with HCL WebSphere Portal.

Optional: If we have the deprecated TAI implementation:

Open wkplc_comp.properties.

Add the ISAMTAIName parameter to the WAS WebSEAL TAI section.

Enter com.ibm.ws.security.web.ISAMTrustAssociationInterceptorPlus as the value.

The HCL WebSphere Portal ConfigEngine tasks used to configure TAIs in previous releases, are no longer supported by the new ETAI, and cannot be used to configure the new ETAI. Follow the directions in the documentation that accompanies the download. Install and configure the Extended TAI implementation into WebSphere Application Server, including specifying the necessary custom properties that control the operation of the ETAI.

Enable ISVA authentication, authorization, and the credential vault:
cd WP_PROFILE/ConfigEngine
./ConfigEngine.sh enable-tam-all -DWasPassword=foo

Complete this step on all nodes.
If the task does not run successfully: Ensure the values specified in wkplc_comp.properties are valid.

To set the value for the systemcred.dn property:
The systemcred.dn property defines the distinguished name of the vault administrative user. All system credentials are stored under the user account. For Security Access Manager, this user must be an existing Security Access Manager user. The Security Access Manager adapter checks if the user exists in Security Access Manager before the slots are accessed.

Log on to the WAS admin console and go to...
Resources | Resource Environment | Resource Environment Providers | WP CredentialVaultService | Additional Properties | Custom properties

Edit the systemcred.dn property. Set the value to an existing Security Access Manager user.

Optional: Go to Enable user provisioning to enable user provisioning.

If we are using Security Access Manager integrated with HCL WebSphere Portal in a stand-alone environment that does not include a web server between WebSEAL and Portal:

Log on to the WAS admin console.

Go to...
Servers | Server Types | Web application servers | WebSphere_Portal | Web container settings | Web Container | Additional Properties | Custom properties | New

Add custom property...
com.ibm.ws.webcontainer.extracthostheaderport custom property = 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 WAS admin console.

Stop and restart the appropriate servers to propagate the changes.

Go to the WebSEAL node and edit webseald-instance.conf 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 continuing.

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

Some functions of HCL WebSphere Portal require the use of the PUT, and DELETE HTTP method.
By default, WebSEAL does not allow these requests. 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.

Parent Configure IBM Security Verify Access
Related:
Migrate Security Access Manager
Create PdPerm.properties
Set up SSL
Extended Security Access Manager Trust Association Interceptor Plus (ETAI)
Administer WebSEAL
WebSEAL Administration Guide
ETAI Download

WebSEAL-instance	The configured name of a single WebSEAL instance, for example web1
webseald	The literal string -websealed-
WebSEAL-Host	The host name, for example, webseal.myco.com. The resulting combination would be... web1-websealed-webseal.myco.com Use the pdadmin server list command to display the correct format of the server name.
vhost-label	Name for the virtual host junction. Virtual host junctions are always mounted at the root of the WebSEAL object space. We can refer to a junction in the pdadmin utility with this label. The virtual host junction label must be unique within each instance of WebSEAL. Because the label represents virtual host junctions in the protected object space, the label name must not contain the forward slash character (/).
-t type	Whether the junction is encrypted (-t ssl) or not encrypted (-t tcp). This parameter is mandatory when creating a virtual host junction. See the WebSEAL Administration Guide.
-h hostname	Defines the backend server to which the junction connects. In most situations, the host name is the HTTP server that sits in front of HCL WebSphere Portal. This parameter is mandatory when creating a virtual host junction.

-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 value 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. If not specified, the values default to the -h hostname and -p port values.
-c header_type	Insert the ISVA client identity in HTTP headers across the junction. The header_type argument can include any combination of the following ISVA 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. 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. Consult the WebSphere system administrator if we are in doubt as to how the TAI is configured.
-b	This option 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 chosen is -b supply.
-k	This option 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 WebSphere Portal to other backend services where WebSEAL also protects those backend services.

wp.ac.impl.EACserverName	Namespace context to distinguish externalized portal role names from other role names in the namespace. If set, wp.ac.impl.EACcellName and wp.ac.impl.EACappname must also be set. All three parameters must be set or none of them.
wp.ac.impl.EACcellName	Namespace context to distinguish externalized portal role names from other role names in the namespace. If set, wp.ac.impl.EACserverName and wp.ac.impl.EACappname must also be set.
wp.ac.impl.EACappname	Namespace context to distinguish externalized portal role names from other role names in the namespace. If set, wp.ac.impl.EACcellName and wp.ac.impl.EACserverName must also be set.
wp.ac.impl.reorderRoles	Set false to keep the role order or true to reorder the roles by resource type first.

wp.ac.impl.TAICreds	Headers that are inserted by WebSEAL the TAI uses to identify the request as originating from WebSEAL.
Optional: wp.ac.impl.hostnames	Host name that sets the WebSEAL TAI's host name parameter. This value must match the -h and -p parameters from the junction creation command.
Optional: For wp.ac.impl.ports	Port used to set the WebSEAL TAI's ports parameter. This value must match the -p parameter from the junction creation command.
wp.ac.impl.loginId	Reverse proxy identity used when creating a TCP junction. This value must match the trusted user account.

wp.ac.impl.PDRoot	Root object space name in the Security Access Manager namespace for the resource entries for this portal. All Portal roles are installed with this entry. For multiple profiles and portal instances that all share a common Security Access Manager instance, choose a unique name for each root object space entry. This unique name helps to easily distinguish the resources for different instances. Or use a common PDRoot value for all Portal instances so that all Portal roles from any instance have a common parent. We can then use the EACappname parameter to distinguish between instances. If it better suits the administration models, we can also mix these two approaches, using a common PDRoot value for some instances, and unique PDRoot values for others.
wp.ac.impl.PDAction	Custom Action created by the Security Access Manager external authorization plug-in. The combination of the action group and the action determines the Security Access Manager permission string. The permission string is used to assign membership to externalized portal roles. We might want to check with the Security Access Manager administrator to determine what they want the PDActionGroup and PDAction values to be.
wp.ac.impl.PDActionGroup	Custom Action group created by the Security Access Manager external authorization plug-in. The combination of the action group and the action determines the Security Access Manager permission string. The permission string is used to assign membership to externalized portal roles.
wp.ac.impl.PDCreateAcl	Set the value to true to automatically create and attach a Security Access Manager ACL when HCL WebSphere Portal externalizes the roles for a resource. Set the value to false to not create and attach a Security Access Manager ACL when HCL WebSphere Portal externalizes the roles for a resource. In this case, the Security Access Manager Administrator must manually create and attach ACLs to the object space entries for the externalized portal resources and roles. Any ACLs created manually in this way, must use the PDAction and PDActionGroup values in order for the permissions to be found.

wp.ac.impl.vaultType	New vault type identifier representing the Tivoli GSO lockbox vault.
wp.ac.impl.vaultProperties	File used to configure the vault with Security Access Manager specific user and SSL connection information.
wp.ac.impl.manageResources	true if the credential vault or any custom portlets are allowed to create new resource objects in Security Access Manager. Or type false to allow only the Security Access Manager administrator to define the accessible resources to associate users with from the command line or graphical user interface.
wp.ac.impl.readOnly	true to allow credential vault or any custom portlets to modify the secrets stored in Security Access Manager. Or type false to allow only the Security Access Manager administrator to modify the secrets from the command line or graphical user interface.