+

Search Tips   |   Advanced Search

Configure IBM Security Access Manager with portal

We can configure IBM Security Access Manager (ISAM) for authentication, authorization, and the vault adapter with one task.


Procedure

  1. Start the ISAM policy and authorization servers.

  2. Install the ISAM run time component. Install on either the ISAM server, WebSEAL server, or the HCL Portal server.

  3. Create the junctions on the WebSEAL server.

    1. Open a pdadmin command from any node that has a ISAM run time component installed.

    2. The general format for the pdadmin command to create a virtual host junction is

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

      Mandatory parameters:

      • instance-webseald-host For example:

          web1-websealed-webseal.myco.com

        -host is the virtual host label (vhost-label) which is the name for the virtual host junction. Virtual host junctions are always mounted at the root (/junction) 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). Mandatory when we create a virtual host junction.

      • -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 Digital Experience. Mandatory when we create a virtual host junction.

      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 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 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 WAS 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 WAS 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.
        -k 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 Portal to other backend services where WebSEAL also protects those backend services.
        -q Query_contents function. Junctions to HCL Portal, whether direct or through an HTTP server, do not support the -q option. Query_contents is not possible on HCL Digital Experience.

      To create a virtual host TCP junction, on the web1 WebSEAL instance running on a host webseal.myco.com, for the virtual host name vhost.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 vhost.myco.com:80 -h portal.myco.com -p 8080 -c all -k -b supply vhost_junction_portal_1

      The URL to a web resource would look like:

        https://host.myco.com/web1/path/to/resource

  4. Set up SSL (Optional).

    Choose relevant SSL options when following 1-3, then create a keystore and a truststore with relevant certificates. Then, complete the following steps to create the virtual host junction:

    1. 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.

    2. Restart WebSEAL.

    3. 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.

  5. 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.

    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

  6. Validate that the PdPerm.properties file is correct and that communication between HCL Portal and the ISAM server works. For a clustered environments, complete this step on all nodes. WasPassword is the dmgr administrator password. The wp.ac.impl.PDAdminPwd is the ISAM administrative user password.

      cd wp_profile_root/ConfigEngine directory
      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. Troubleshoot the connectivity issue with ISAM.

  7. Edit...

    Clustered environments: Complete this step on all nodes.

  8. Update properties in the wkplc_comp.properties.

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

        wp.ac.impl.EACserverName Namespace context information to further 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 information to further 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 information to further 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.

  9. PDJrteCfg command and file system parameters

    1. For wp.ac.impl.TamHost under the SvrSslCfg command parameter heading in wkplc_comp.properties, type the ISAM Policy Server used when you run PDJrteCfg.

  10. WebSphere Application Server WebSEAL TAI parameters

    1. Enter the following parameter in wkplc_comp.properties; go to the WebSEAL junction parameters heading. For a cluster, 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.

      • 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.

    2. Enter the following parameters in wkplc_comp.properties; go to the WebSEAL TAI parameters heading. For a cluster, 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.

      • Optional: For wp.ac.impl.hostnames, type the 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, type the port used to set the WebSEAL TAI's ports parameter. This value must match the -p parameter from the junction creation command.

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

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

    1. For wp.ac.impl.PDRoot, type the root object space name in the ISAM 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 ISAM 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, by using a common PDRoot value for some instances, and unique PDRoot values for others.

    2. For wp.ac.impl.PDAction, type the Custom Action created by the ISAM external authorization plug-in. The combination of the action group and the action determines the ISAM permission string. The permission string is used to assign membership to externalized portal roles. You might want to check with your ISAM administrator to determine what they want the PDActionGroup and PDAction values to be.

    3. For wp.ac.impl.PDActionGroup, type the Custom Action group that is created by the ISAM external authorization plug-in. The combination of the action group and the action determines the ISAM permission string. The permission string is used to assign membership to externalized portal roles.

    4. For wp.ac.impl.PDCreateAcl, set the value to true to automatically create and attach a ISAM ACL when HCL Portal externalizes the roles for a resource. Set the value to false to not create and attach a ISAM ACL when HCL Portal externalizes the roles for a resource. In this case, the ISAM 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.

  12. Enter the following parameters in wkplc_comp.properties; go to the Portal vault parameters heading. For a cluster, 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.

    1. For wp.ac.impl.vaultType, type the new vault type identifier that represents the Tivoli GSO lockbox vault.

    2. For wp.ac.impl.vaultProperties, type the file used to configure the vault with ISAM specific user and SSL connection information.

    3. For wp.ac.impl.manageResources, type true if the credential vault or any custom portlets are allowed to create new resource objects in ISAM. Or type false to allow only the ISAM administrator to define the accessible resources to associate users with from the command line or graphical user interface.

    4. For wp.ac.impl.readOnly, type true to allow credential vault or any custom portlets to modify the secrets that are stored in ISAM. Or type false to allow only the ISAM administrator to modify the secrets from the command line or graphical user interface.

  13. Save the changes to the properties file.

  14. Enable ISAM authentication, authorization, and the credential vault:

      cd wp_profile_root/ConfigEngine
      ./ConfigEngine.sh enable-tam-all -DWasPassword=foo

    Clustered environments:

    • Complete this step on all nodes.
    • WasPassword is the dmgr administrative password.

    If the task does not run successfully: Verify the values that you specified in wkplc_comp.properties are valid.

  15. 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 ISAM, this user must be an existing ISAM user. The ISAM adapter checks if the user exists in ISAM before the slots are accessed.

    1. Log on to the WebSphere Integrated Solutions Console and go to....

        Resources > Resource Environment > Resource Environment Providers > WP CredentialVaultService > Additional Properties > Custom properties.

    2. Edit the systemcred.dn property. Set the value to an existing ISAM user.

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

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

    1. Log on to the WebSphere Integrated Solutions Console and go to...

        Servers > Server Types > Web application servers > HCL Digital Experience > Web container settings > Web Container > Additional Properties > Custom properties

    2. Click New and then add the com.ibm.ws.webcontainer.extracthostheaderport custom property with a value of true.

    3. Click OK.

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

    5. Click OK.

    6. Click Save to save the changes.

    7. Log out of the WebSphere Integrated Solutions Console.

  18. Stop and restart the appropriate servers to propagate the changes.

  19. 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.

  20. 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.

  21. Some functions of HCL Digital Experience 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.