IBM® SECURITY PRIVILEGED IDENTITY
MANAGER
Integration with IBM Security Access Manager (ISAM) for One-time Password
(OTP)
Version 2.0
Configuration Cookbook
Page | 2
Contents 1. Introduction 5
2. Requirements for IBM® Security Access Manager 5
2.1. Roadmap for ISAM Configuration 5
2.1.1. Configuring IBM® Security Access Manager Fronting 5
3. Two-factor authentication support for IBM® Security Privileged Identity Manager web consoles 7
3.1. Two-factor authentication for web consoles 9
3.2. Login workflow when ISAM is enabled 9
3.2.1. Enter valid ISPIM user and password 9
3.2.2. Select a one-time password delivery method 10
3.2.3. Enter the one-time password that you received 10
3.2.4. Logged in to Service Center 11
3.2.5. Single Sign-On to other ISPIM web consoles 11
3.2.6. Click the logout button (pkmslogout) for any web console 12
3.3. IBM® Security Privileged Identity Manager - IBM® Security Access Manager deployment architecture 13
3.4. High Availability configuration with IBM® Security Access Manager 13
4. Configuring IBM® Security Access Manager Fronting 14
4.1. IBM® Security Privileged Identity Manager – WebSEAL connection 14
4.2. IBM® Security Access Manager virtual appliance (ISAM VA): Create and configure WebSEAL instance to
front IBM® Security Privileged Identity Manager virtual appliance (ISPIM VA) 15
4.2.1. Create a WebSEAL instance 15
4.2.2. Import the ISPIM VA root signer certificate 17
4.2.3. Adding a host file 19
4.2.4. Create WebSEAL junctions for ISPIM 20
4.2.5. Create Access Control Lists (ACLs) for ISPIM junctions 25
4.3. WebSEAL – Advanced Access Control (AAC) connection 27
Page | 3
4.3.1. IBM® Security Access Manager virtual appliance (ISAM VA): Configure WebSEAL instance as the
point-of-contact for AAC 27
4.3.2. IBM® Security Access Manager virtual appliance (ISAM VA): Configure AAC for 2-factor (2FA)
authentication 30
5. Troubleshooting and support 43
5.1. Ensure that entities are configured 44
5.2. Ensure that integration is setup after configuring ISPIM – WebSEAL settings 44
5.3. Enabling the ISAM built-in Diagnostic Tool for troubleshooting 44
5.3.1. Configure tool settings with environment setup 45
5.3.2. Example of the ISAM Credential value 46
5.3.3. Example of the HTTP Headers value 47
Page | 4
Document History
Version Updates Developer/IDD Date
1.0 Created cookbook. Cindy Evelyn Kurniawan
Haan-Ming Lim
January 2016
2.0 Updated commands and screenshots
in “Configure the WebSEAL instance
as a Point-of-Contact server for AAC".
Updated EAI key and value table in
“Configure AAC advanced
configuration settings: Set the ISAM
External Authentication Interface
(EAI) header name to use the external
user authentication”.
Haan-Ming Lim June 2017
Page | 5
1. Introduction This cookbook describes the steps to integrate the IBM® Security Privileged Identity Manager (ISPIM)
with IBM® Security Access Manager (ISAM) for One-time Passwords (OTP).
2. Requirements for IBM® Security Access Manager Additional
IBM® Security Access Manager Version 9 with Fix Pack 1 or later.
You must have the following installed
or configured: • IBM® Security Access Manager Platform
IBM® Security Access Manager (ISAM) Platform is
equivalent to the IBM® Security Access Manager for Web
offering in earlier releases. The ISAM reverse proxy will
be referred as WebSEAL/Reverse Proxy in this cookbook.
• Advanced Access Control Module (AAC)
This module is equivalent to the unique capabilities of
IBM® Security Access Manager (ISAM) for Mobile in
earlier releases, and was also known as Federated
Identity Manager (FIM). It will be referred to as AAC in this
cookbook.
Verify that your system meets the
version requirements before you
configure ISAM as a reverse proxy.
2.1. Roadmap for ISAM Configuration
2.1.1. Configuring IBM® Security Access Manager Fronting
Procedure Reference
1
Configure the IBM® Security
Privileged Identity Manager –
WebSEAL connection.
See IBM® Security Privileged Identity Manager – WebSEAL
connection
2
For IBM® Security Access
Manager virtual appliance
(ISAM VA):
Create and configure
WebSEAL instance to front
IBM® Security Privileged
Identity Manager virtual
appliance (ISPIM VA)
See the following topics:
1. Create a WebSEAL instance
2. Import the ISPIM VA root signer certificate
3. Adding a host file
4. Create WebSEAL junctions for ISPIM
Page | 6
5. Create Access Control Lists (ACLs) for ISPIM junctions
• Types of ACLs for ISPIM junctions
• Edit the WebSEAL instance’s Advanced Configuration
File
• List of required parameter values to modify
3
Configure WebSEAL –
Advanced Access Control
(AAC) connection
See the following topics:
IBM® Security Access Manager virtual appliance (ISAM VA):
Configure WebSEAL instance as the point-of-contact for AAC
1. Configure AAC Listening Interfaces
2. Set the password for External Authorization Service
(EAS) User in AAC internal user registry
3. Test that the Authorization Service provided by AAC is
listening on the appropriate interface
4. Configure the WebSEAL instance as a Point-of-Contact
server for AAC
IBM® Security Access Manager virtual appliance (ISAM VA):
Configure AAC for 2-factor (2FA) authentication
1. ISPIM external authentication configuration
• Import ISPIM VA root signer certificate
• Import ISPIM custom authentication plug-in
• Create a new Authentication Mechanism for the ISPIM
custom authentication plug-in
• Create a new Authentication Policy for the ISPIM
authentication mechanism
• Configure AAC advanced configuration settings: Set
the ISAM External Authentication Interface (EAI) header
name to use the external user authentication
• Import ISPIM custom login pages
2. Configuring AAC built-in email and SMS One-Time
Password
• (Optional) Configuration of AAC built-in Mobile Active
Code One-Time Password (MAC OTP) provider
Page | 7
• Configure the Simple Mail Transfer Protocol (SMTP)
Server information for email delivery
• Configure the SMS Gateway information for SMS
delivery
• Modify mapping rules to retrieve email address and
mobile number fetched from ISPIM user registry by the
ISPIM custom authentication plug-in
• Define an Access Control Policy to protect ISPIM
junctions with SMS or Email OTP
• Attach the Access Control Policy to the ISPIM
authenticated junctions
• Adding ISPIM authenticated junctions
3. Two-factor authentication support for IBM® Security
Privileged Identity Manager web consoles IBM® Security Privileged Identity Manager integrates with IBM® Security Access Manager to support
two-factor (2FA), or strong authentication mechanisms.
IBM® Security Privileged Identity Manager virtual appliance is configured with the IBM® Security Access
Manager Extended Trust Association Interceptor (ETAI) to create authentication tokens for authenticated
requests from WebSEAL.
Suggestion Additional
You can use the authentication
tokens to single sign-on to the
following consoles:
• Administrative console
/itim/console
• Self-service console
/itim/self
• Service Center
/itim/ui
• AccessAdmin
/admin
• Session Recording Playback Console
/recorder/ui
Page | 8
The suggested configuration is to use
the IBM® Security Privileged Identity
Manager (ISPIM) custom
authentication mechanism.
It is a JAR file that is imported to the Advanced Access Control
Module (AAC) that delegates the password check back to
ISPIM.
User repository reconciliation is not
required.
Things to note
• When the WebSEAL front proxy feature is enabled, single sign-on tokens are accepted by all
the consoles.
• The WebSEAL front proxy feature cannot be enabled or disabled on individual consoles.
• The AccessAgent and App ID Client is not affected when the WebSEAL front proxy feature is
enabled.
• The preferred user ID of the IBM® Security Privileged Identity Manager user must not contain
any spaces. Otherwise, the following consoles- administrative console, self-service console,
and Service Center, will not accept the single sign-on token.
• This is a limitation between WebSEAL and IBM® Security Privileged Identity
Manager.
• Single sign-on is not applicable to requests from:
• AccessAgent, Session Recording Agent, App ID Toolkit (including Service
Management Agent), Virtual Appliance console
Page | 9
3.1. Two-factor authentication for web consoles
IBM® Security Privileged Identity Manager (ISPIM) supports two-factor authentication (2FA) to application
web consoles through IBM® Security Access Manager (ISAM) integration. Password check is delegated
to the ISPIM virtual appliance. You are not required to reconcile user repositories between ISPIM and
ISAM.
3.2. Login workflow when ISAM is enabled When IBM® Security Access Manager (ISAM) is enabled, you cannot login directly through the web
console. You login through the ISAM WebSEAL URL instead of the IBM® Security Privileged Identity
Manager (ISPIM) URL.
In the following example, you access the ISPIM Service Center with ISAM Fronting enabled.
3.2.1. Enter valid ISPIM user and password
Access: https://<WebSEAL_URL:WebSEAL_port>/ispim/ui.
You are prompted to enter login details for the ISPIM custom login page in WebSEAL.
Page | 10
3.2.2. Select a one-time password delivery method
After you enter a valid ISPIM username and password, you are prompted to select a one-time password
(OTP) delivery option. In this example, you choose email.
3.2.3. Enter the one-time password that you received
You selected email as the delivery option. The OTP is sent to the user’s email address that is specified in
the ISPIM repository.
You are then required to enter the correct OTP.
Page | 11
3.2.4. Logged in to Service Center
When the OTP is entered correctly, you are logged on to the ISPIM Service Center.
3.2.5. Single Sign-On to other ISPIM web consoles
You can navigate through other ISPIM web consoles, such as the Administrative Console, Self-Service
UI, AccessAdmin, and Session Recording Playback Console, without the need to re-login.
Page | 12
3.2.6. Click the logout button (pkmslogout) for any web console
When you log off from any of the ISPIM web consoles, you are redirected to the custom logoff page. You
are no longer able to Single Sign-on (SSO) to any of the ISPIM web consoles.
When ISAM Fronting is enabled, all of the ISPIM web consoles log off buttons will call ISAM pkmslogout
to log off properly and clear the SSO token.
Page | 13
3.3. IBM® Security Privileged Identity Manager - IBM® Security
Access Manager deployment architecture The IBM® Security Access Manager (ISAM) Reverse Proxy does not support session affinity across
junctions or active/passive High Availability (HA) setup. A separate Load Balancer (LB) is required.
The Load Balancer must monitor response codes from an unauthenticated junction. For example,
/ispim/rest/systeminfoto determines if the IBM® Security Privileged Identity Manager (ISPIM) is
available. If ISPIM is not available, the ISAM reverse proxy will respond with a 500 error code.
3.4. High Availability configuration with IBM® Security Access
Manager Plan for a high availability deployment with IBM® Security Access Manager (ISAM) reverse proxy
instances.
If there are multiple back-end servers, you can only configure session affinity in ISAM for the same
junction.
To achieve high availability when ISAM is fronting IBM® Security Privileged Identity Manager (ISPIM), all
subsequent requests across the different junctions from an ISPIM client during the same session must be
forwarded to the same ISPIM virtual appliance (VA).
To set up High Availability, you must have the following elements:
• 1 IBM® Security Access Manager (ISAM) Reverse Proxy fronting 1 IBM® Security Privileged
Identity Manager (ISPIM) virtual appliance.
• 1 IBM® Security Access Manager virtual appliance (ISAM VA) can have more than 1 IBM®
Security Access (ISAM) Reverse Proxy depending on the virtual appliance capacity.
Page | 14
• A Load Balancer (LB) with session affinity enabled to manage the IBM® Security Access
Manager (ISAM) Reverse Proxies. LB is placed in front of the ISAM Reverse Proxy instances.
• In the IBM® Security Privileged Identity Manager virtual appliance (ISPIM VA) Load Balancer
Configuration, set the Load Balancer DNS to point to the Load Balancer mentioned above.
Note: When there is only 1 Reverse Proxy fronting ISPIM VA and there is no separate Load Balancer, configure the
ISPIM VA Load Balancer to point to the Reverse Proxy.
Note: The ISPIM preferred user ID must not contain any spaces for the Administrative Console, Self-Service UI, and
Service Center.
This is an IBM® Security Access Manager Extended Trust Association Interceptor (ISAM ETAI) limitation.
4. Configuring IBM® Security Access Manager Fronting
4.1. IBM® Security Privileged Identity Manager – WebSEAL
connection On the IBM® Security Privileged Identity Manager virtual appliance (ISPIM VA), configure WebSEAL by
performing the following steps:
1. Create a user in the ISPIM Admin Console for a WebSEAL login ID. For example, etaiuser.
Note: ISPIM uses the IBM® Security Access Manager Extended Trust Association Interceptor (ISAM ETAI) to achieve
Single Sign-on (SSO). Unlike TAI++, ETAI does not make any callbacks to IBM® Security Access Manager (ISAM), but
uses Basic Authentication to verify the authenticity of the ISAM server.
If you use an external user registry (AD), create the user in Active Directory.
2. Enable WebSEAL fronting. Specify the WebSEAL login ID. Note that the password will be
specified in ISAM configuration later.
3. Restart the following services:
Page | 15
• Identity service
• Single Sign-On service
• Session Recording service
4.2. IBM® Security Access Manager virtual appliance (ISAM VA):
Create and configure WebSEAL instance to front IBM® Security
Privileged Identity Manager virtual appliance (ISPIM VA)
Before you begin: Set up WebSEAL Runtime Component
On the IBM® Security Privileged Identity Manager virtual appliance (ISPIM VA), configure WebSEAL by
performing the following steps:
Note: You can configure and use a local Policy Server as well as local User Registry.
To configure the local Policy Server:
Enter any password for Administrator Password and repeat for Confirm Administrator Password. This will be the
password of the default “sec_master” user for Policy Administration. Leave the rest as the default value.
To configure the local User Registry (LDAP):
Enter Password as “passw0rd”. This is the default ISAM password. Leave the rest as the default value.
For any other configuration for WebSEAL Runtime Component, see IBM Security Access Manager Product
documentation
4.2.1. Create a WebSEAL instance
1. Go to Secure Web Settings > Reverse Proxy.
2. Click the New icon.
3. On the Instance tab, enter the required fields:
• Instance Name
Enter a name for the Reverse Proxy instance.
• Hostname
Enter in the IBM® Security Access Manager virtual appliance (ISAM VA) hostname.
• Listening Port
Specifies the listening port of the ISAM Policy Server. If you configure ISAM to use local
policy server and local user registry, you do not need to change this value.
• IP Address for the Primary Interface
Specifies the IP address of the Reverse Proxy instance. You can specify multiple network
interfaces in the Manage System Settings for the Reverse Proxy to choose from.
Page | 16
4. On the IBM Security Access Manager tab, enter the required fields:
• Administrator Name
Note that sec_master is the default administrator name.
• Administrator Password
Complete the password of sec_master that you specified earlier when you configured
the ISAM Runtime Component.
• Domain
ISAM management domain. You do not have to change this parameter if you are not
going to create another domain.
5. On the Transport tab, enter the required parameters:
• Enable HTTPS
Select enable HTTPS.
• HTTPS Port
Reverse Proxy Port. Specify port 443 as the Reverse Proxy port.
Page | 17
If you specify any port other than 443, note that you must explicitly specify the port when
you are making a request to the Reverse Proxy.
4.2.2. Import the ISPIM VA root signer certificate
1. Go to Manage System Settings > SSL Certificates.
2. In the table, select the option pdsrv.
3.
4. Click the Manager tab, and from the dropdown list, select Import. Import the ISPIM root signer
certificate.
Page | 18
Page | 19
5. Deploy the changes and restart WebSEAL.
4.2.3. Adding a host file
1 Go to Manage System Settings > Network Settings > Hosts File.
2 Click New and add the host file.
Page | 20
3 Deploy the changes.
4.2.4. Create WebSEAL junctions for ISPIM
Consider the following factors before you proceed to create WebSEAL junctions for ISPIM.
• All ISPIM junctions must be defined.
This is because WebSEAL will map incoming requests based on the path specified in the URL to
the back-end ISPIM server.
• You should be aware that there are 2 types of junctions for ISPIM.
They are namely the authenticated junctions to ISPIM consoles (ispim/ui, itim/console etc.) and
the unauthenticated Passthrough junctions to the client APIs (ispim/rest, itim/services etc.).
• Each junction is defined by Access Control Lists (ACLs).
• The recommended configuration is to use Standard, SSL and transparent path junctions.
Without the Lightweight Third Party Authentication Single Sign-On (LTPA SSO).
• ISPIM accepts the principal provided by WebSEAL in the “IV_USER” header. To ensure its
acceptance, ISPIM must trust WebSEAL. This trust can be established through HTTP basic
authentication by WebSEAL to ISPIM by using the WebSEAL login ID.
The trusted WebSEAL login ID must be provisioned as a user in the ISPIM user registry (Security
Directory Server or Active Directory). The basic authentication header is only required for
junctions that have authenticated ACLs attached. You must include session cookies and insert
the client IP address in the HTTP header setting for those junctions.
Page | 21
Junctions for Privileged Credential Manager (PCM)
The following table provides a list of junctions that are required for Privileged Credential Manager.
Path Purpose ACL
/itim/console Admin Console Authenticated
/itim/self Self-Service UI Authenticated
/ispim/ui Service Center Authenticated
/itim/services SOAP web services (used
by AA)
Passthrough-SOAP
/ispim/rest REST web services Passthrough-REST
/ispim/restlogin REST web services login Passthrough-REST
/ispim/uihelp Service Center Page Help Passthrough-static
/itim/consolehelp Admin Console Page Help Passthrough-static
/itim/selfhelp Self-Service UI Page Help Passthrough-static
/itim/messagehelp TMS Message Details Passthrough-static
Junctions for IBM Security Access Manager for Enterprise Single Sign-On (ISAM
ESSO)
The following table provides a list of junctions that are required for IBM Security Access Manager for
Enterprise Single Sign-On.
Path Purpose ACL
/admin AccessAdmin Authenticated
/static UI resources (used by
AccessAdmin)
Passthrough-static
/ims/services IMS SOAP APIs (used by
AA)
Passthrough-SOAP
Junctions for Privileged Session Recorder (PSR)
The following table provides a list of junctions that are required for Privileged Session Recorder.
Path Purpose ACL
Page | 22
/recorder/ui PSR Console Authenticated
/recorder/player Retriever for REST web
services
Passthrough-REST
/recorder/collector Uploader for REST web
services
Passthrough-REST
1. Go to Secure Web Settings > Reverse Proxy.
2. Click the Manage tab, then select Junction Management in the list.
3. On Junction Management page, click the New tab. Then select Standard Junction from the
list.
4. On the Junction tab, enter the required fields:
• Junction Point Name
Fill in the ISPIM junction path
• Create Transparent Path Junction
Select the empty box beside Create Transparent Path Junction.
• Junction Type
Select SSL from the list.
Page | 23
5. On the Servers tab, enter the required fields:
• Hostname
ISPIM server hostname.
• TCP or SSL Port
The ISPIM VA only accepts SSL connection on port 443.
Page | 24
6. For the Authenticated Junctions, enter the required fields:
On the Identity tab, enter the required fields and click Save.
• HTTP Basic Authentication Header
Select Supply. It must be present for authenticated junctions
• HTTP Header Identity Information
Tick the empty box beside IV_USER header. ISPIM accepts the principal provided in the
IV_USER header.
• Include session cookie
Tick the empty box beside Include session cookie.
• Insert client IP address
Tick the empty box beside Insert client IP address.
Page | 25
7. For the Unauthenticated (Passthrough) Junctions, enter the required fields:
On the Identity tab, fill in the required fields and click Save.
• HTTP Basic Authentication Header
Select Ignore. No HTTP basic authentication is performed for unauthenticated junctions.
4.2.5. Create Access Control Lists (ACLs) for ISPIM junctions
1. Go to Secure Web Settings > Policy Administration.
2. Login with “sec_master” and the password.
3. Create the required ACLs for ISPIM junctions.
Optional: You can search for ACL default-webseal. Then clone it, and modify to create a
new one. See Types of ACLs for ISPIM junctions for the modification details.
4. After creating all the required ACLs, attach each ISPIM junctions to the appropriate ACL as
listed in the junction table in 4.2.3 Create WebSEAL junctions for ISPIM.
4.2.5.1. Types of ACLs for ISPIM junctions
The following table contains the types of ACLs for ISPIM junctions.
• T: traverse
• m: modify
• d: delete
Page | 26
• r: read
• x: execute
ACL Any-other Unauthenticated
Authenticated Trx T
Passthrough-REST Tmdrx Tmdrx
Passthrough-SOAP Trx Trx
Passthrough-static Tr Tr
4.2.5.2. Edit the WebSEAL instance’s Advanced Configuration File
1. Go to Secure Web Settings > Reverse Proxy.
2. Select the WebSEAL instance
3. Click on the Manage tab, and select Configuration then Edit Configuration File from the
dropdown list.
4. You are to modify all the required parameters values. You can refer to 5.2.4.3 List of required
parameter values to modify for more details.
Tip: You can use ‘Ctrl+F’ to find the parameter key.
5. When you have edited all the required parameters, click Save.
6. Finally, deploy changes and Restart the WebSEAL instance.
4.2.5.3. List of required parameter values to modify
1. Specify the password of the WebSEAL login ID for HTTP basic authentication to ISPIM.
2. Enable HTTP method PUT and DELETE.
3. Client IP Forwarding for ISAM ESSO audit logging and PSR fingerprint authentication.
[junction]
basicauth-dummy-passwd = <the-WebSEAL-login-ID-password>
[server]
# Remove PUT, DELETE
http-method-disabled-remote = TRACE, CONNECT
[header-name]
client-ip-v4 = X-Forwarded-For
Page | 27
4. Reset cookies on user session logout.
5. Disable HTTP only cookies.
4.3. WebSEAL – Advanced Access Control (AAC) connection
4.3.1. IBM® Security Access Manager virtual appliance (ISAM VA):
Configure WebSEAL instance as the point-of-contact for AAC
4.3.1.1. Configure AAC Listening Interfaces
Requirement
The Advance Access Control (AAC) runtime listens on port 80 and 443 on Local Interface by default.
You must configure AAC to listen on only one appliance interface IP address so that it does not clash with
WebSEAL, which usually also listens on these ports.
1. Go to Secure Access Control > Runtime Parameters.
2. Select each interface and click the Edit icon. Note that we will only use SSL connections to
set up the connection with WebSEAL later.
3. Deploy the changes. The following example uses the same IP address as the WebSEAL
instance so the port is set to 1443. Ideally, use a different address.
[junction]
reset-cookies-list = JSESS*, Ltpa*
[server]
use-http-only-cookies = no
Page | 28
4.3.1.2. Set the password for External Authorization Service (EAS) User in AAC
internal user registry
The initial configuration of Advanced Access Control (AAC) creates a default user “easuser” in its internal
user registry to be used for authentication of connections to its appliance interface.
1. Go to Secure Access Control > User Registry.
2. Select easuser. Then click the Set Password icon to enter your password.
3. Deploy the changes. The following example uses the same IP address as the WebSEAL
instance, so the port is set to 1443. Ideally, you should use a different IP address.
4.3.1.3. Test that the Authorization Service provided by AAC is listening on the
appropriate interface
Test that the Authorization Service provided by Advanced Access Control (AAC) is listening on the
appropriate interface.
1. Go to the URL: https://<AAC_interface>:<AAC_port>/rtss/authz/services/AuthzService
2. Enter easuser and its password when the Basic Authentication prompt is displayed. The
default screen for an HTTP GET to a Web Service application hosted by WebSphere
Application Server will be shown.
Page | 29
4.3.1.4. Configure the WebSEAL instance as a Point-of-Contact server for AAC
Complete the following steps to configure the WebSEAL instance as a Point-of-Contact server for
Advanced Access Control (AAC).
1. Run the IBM® Security Access Manager (ISAM) Auto-configuration Tool using the ISAM
virtual appliance command-line tool with SSH.
2. Type the following commands:
• isam
• aac
• config
To proceed to the next prompt, you can press “Enter” without entering anything.
3. Enter the Advanced Access Control Local Management Interface hostname.
To proceed to the next prompt, you can press “Enter” without entering anything.
You can use default prompts by pressing “Enter”
4. Proceed with the configuration by follow the instructions in the command line interface (CLI).
5. At this stage, enter [2] as your choice.
6. Enter easuser and the password as the Advanced Access control runtime listening interface
user ID and password.
Page | 30
7. Enter [1] to reuse the POP.
8. Use default prompts by pressing “Enter”
9. Enable the /mga junction.
10. Once the configuration starts, you see the following message:
11. Once the configuration is completed, you see the following message:
4.3.2. IBM® Security Access Manager virtual appliance (ISAM VA):
Configure AAC for 2-factor (2FA) authentication
By default, when users attempt to access an authenticated junction, WebSEAL authenticates users
against its configured user registry. If more advanced authentication methods are desired, WebSEAL can
delegate authentication of users to Advanced Access Control (AAC).
Recommendation: To avoid provisioning IBM® Security Privileged Identity Manager (ISPIM) users into WebSEAL
user registry, it is recommended to use the ISPIM external authentication by importing the ISPIM custom
authentication plug-in into AAC. This delegates the password check back to ISPIM.
IBM® Security Access Manager (ISAM) AAC supports an array of different authentication methods. For
our purposes, we focus on the following authentication workflow:
• External authentication against the ISPIM user registry by using the ISPIM custom
authentication plug-in (JAR file).
• 2-factor authentication (2FA) in the form of One-Time Passwords (OTP) delivered by SMS or
email by using the AAC built-in OTP provider. This configuration includes the scenario where
you are prompted to choose the OTP delivery options (SMS or Email). Take note that both
email address and mobile number must be present for each user in the ISPIM user registry.
Page | 31
When the above configuration is combined, mobile numbers, or email addresses from the ISPIM user
registry are passed on seamlessly to the OTP SMS Gateway or Simple Mail Transfer Protocol (SMTP)
server to be used in OTP delivery, providing a smooth 2FA-secured user experience.
4.3.2.1. ISPIM external authentication configuration
Configure the IBM® Security Privileged Identity Manager (ISPIM) external authentication to delegate the
password check back to ISPIM users to be provisioned into the WebSEAL registry.
4.3.2.1.1. Import ISPIM VA root signer certificate
Import the IBM® Security Privileged Identity Manager virtual appliance (ISPIM VA) root signer certificate
to IBM® Security Access Manager (ISAM) Access Control.
1. In the ISAM VA console, click Manage System Settings > SSL Certificates
2. Select rt_profile_keys.
3. Click Manage > Edit SSl Certficate Database.
4. In the Edit SSL Certificate Database- rt_profile_keys window, under the Signer Certficates
tab, click Manage > Import to import the ISPIM root signer certificate.
5. Deploy the changes.
6. Restart the Runtime Server. In the ISAM VA console, click Secure Access Control >
Runtime Parameters. Under the Runtime Status tab, click Restart Local Runtime and wait
until the server is restarted.
Check that the Runtime Status has changed to Started.
4.3.2.1.2. Import ISPIM custom authentication plug-in
Page | 32
Import the IBM® Security Privileged Identity Manager (ISPIM) custom authentication plug-in.
1. In the IBM® Security Access Manager virtual appliance (ISAM VA) console, click Secure
Access Control > Extensions.
2. Select the ISPIM custom authentication plug-in JAR file and click Import. For example,
com.ibm.ispim.authmech_1.0.0.0.jar.
You can find this file in the ISPIM Clients bundle: ISPIM Authentication Mechanism.zip.
3. Deploy the changes.
4.3.2.1.3. Create a new Authentication Mechanism for the ISPIM custom authentication plug-in
Create a new Authentication Mechanism for the IBM® Security Privileged Identity Manager (ISPIM)
custom authentication plug-in.
1. In the IBM® Security Access Manager virtual appliance (ISAM VA) console, click Secure
Access Control > Authorization.
2. Click the Mechanisms tab.
3. Click the New icon, then select IBM Security Privileged Identity Manager Authentication
Mechanism
4. Enter the information according to the attributes in the General tab.
• Name
Name that identifies this authentication plug-in mechanism.
For example, ISPIM Username Password.
• Identifier
Enter ispim.
Page | 33
5. Enter the information in Properties tab, click Save and deploy changes.
• Email Header
The email header name stores the email address that is fetched from the ISPIM user
registry. This email header is used in the mapping rule or other authentication policy
to retrieve the email address to send the One-Time Password (OTP).
For example, ispim_email.
If this attribute is empty, it is set to emailAddress that is used by the default MAC
Email One-Time Password authentication policy for OTP delivery by email only.
• Group to Assign
Group name in the local ISAM user registry associates the external user for
authentication. To create a new group in Policy Administration, see the ISAM Product
Guide.
If this attribute is empty, by default, it is set to Security Group which is already
predefined in ISAM. It is suggested to create a new group.
• Mobile Header
The mobile header name stores the mobile number that is fetched from the ISPIM
user registry. This mobile header is used in the mapping rule or other authentication
policy to retrieve the mobile number to send the One-Time Password (OTP).
For example, ispim_mobile.
If this attribute is empty, by default, it is set to mobileNumber that is used by the
default MAC SMS One-Time Password authentication policy for OTP delivery by
SMS only.
• Server URLs
The ISPIM hostname for external authentication. Multiple ISPIM servers can be
specified. The entries are used in a failover method.
4.3.2.1.4. Create a new Authentication Policy for the ISPIM authentication mechanism
Page | 34
Create a new Authentication Policy for the IBM® Security Privileged Identity Manager (ISPIM)
authentication mechanism.
1. In the IBM® Security Access Manager virtual appliance (ISAM VA) console, click Secure
Access Control > Authentication.
2. Click the Policies tab.
3. Click the New Authentication Policy icon.
4. Complete the required fields according to the attributes:
• Name
Name that identifies this authentication plug-in mechanism. For example, ISPIM
Username Password.
• Identifier
Enter ispim. Do not change this value. This identifier is used by the ISPIM custom
login page.
• Description
Provide a description for the policy.
• Enabled
To enable the policy, ensure that this checkbox is checked.
Page | 35
5. In Workflow Steps, click Add Step and select ISPIM Username Password or the ISPIM
authentication mechanism name that was created in the previous step.
6. Click Save and deploy the changes.
4.3.2.1.5. Configure AAC advanced configuration settings: Set the ISAM External Authentication
Interface (EAI) header name to use the external user authentication
Complete the following steps to configure the Advanced Access Control (AAC) advanced configuration
settings to use the correct External User External Authentication Interface (EAI) setting. You are required
to set the EAI header name to use the external user authentication.
1. In the IBM® Security Access Manager virtual appliance (ISAM VA) console, select Secure
Federation > Global Settings > Point of Contact.
2. Select Access Manager Credential and click Create Like to clone the profile.
3. In the Create Like Point of Contact Profile- Access Manager Credential window, provide
the following details:
Profile Name: Specify a profile name.
Sign In: Specify the values for the following keys:
Page | 36
Key Value
fim.attributes.response.header.name am-eai-xattrs
fim.cred.response.header.name am-eai-pac (by
default)
fim.groups.response.header.name am-eai-ext-user-
groups
fim.target.response.header.name am-eai-redir-url
fim.user.request.header.name iv-user
fim.user.response.header.name am-eai-ext-user-id
Sign Out: Keep the default key values.
Local ID: Keep the default key values.
Authentication: Keep the default key values.
4. Review the modifications at the Summary tab and click Finish.
5. Select the new profile you created and click Set As Current.
6. Deploy the changes.
4.3.2.1.6. Import ISPIM custom login pages
Import the IBM® Security Privileged Identity Manager custom login pages. Only the English language is
supported in the custom login page in ISPIM 2.0.2.
1. The custom login pages are in the same bundle as the JAR file inside pages/folder from the
ISPIM Clients bundle (ISPIM Authentication Mechanism.zip).
Page | 37
2. You can follow the README.txt inside the folder.
3. Take note that the Access Control List (ACL) is to be attached to “nls.js” and “ispim.css”. You
may re-use the ACL Passthrough-static (created for WebSEAL junctions) for these two files.
4. Deploy the changes and restart.
4.3.2.2. Configuring AAC built-in email and SMS One-Time Password
4.3.2.2.1. (Optional) Configuration of AAC built-in Mobile Active Code One-Time Password (MAC
OTP) provider
This section is optional. Configure the Advance Access Control (AAC) built-in Mobile Active Code (MAC)
One-Time Password (OTP) provider.
1. In the IBM® Security Access Manager virtual appliance (ISAM VA) console, select Secure
Access Control > Authentication.
2. Click the Mechanisms tab.
3. Select MAC One-Time Password.
4. Click the Modify Authentication Mechanism icon to modify MAC One-Time Password. Set
the values for the following properties:
Note: Alternatively, you can also use the default values.
• Password Character Set
• Password Length
• Store Entry Hash Algorithm
• Store Entry Lifetime (seconds)
Page | 38
5. Click Save and deploy the changes
4.3.2.2.2. Configure the Simple Mail Transfer Protocol (SMTP) Server information for email
delivery
Configure the SMTP Server information in the email One-Time Password (OTP) authentication
mechanism.
1. In the IBM® Security Access Manager virtual appliance (ISAM VA) console, select Secure
Access Control > Authentication.
2. Click the Mechanisms tab.
3. Select Email One-Time Password and click the Modify Authentication Mechanism icon.
4. In the Properties tab, specify the SMTP Host Name.
4.3.2.2.3. Configure the SMS Gateway information for SMS delivery
Configure the SMS Gateway information in the SMS One-Time Password authentication mechanism.
1. In the IBM® Security Access Manager virtual appliance (ISAM VA) console, select Secure
Access Control > Authentication.
2. Click Mechanisms.
3. Select SMS One-Time Password and click the Modify Authentication Mechanism icon.
4. In the properties, specify the required values.
Page | 39
4.3.2.2.4. Modify mapping rules to retrieve email address and mobile number fetched from ISPIM
user registry by the ISPIM custom authentication plug-in
Modify the mapping rules to retrieve the email address and mobile number from the IBM® Security
Access Manager (ISAM) credentials after the IBM® Security Privileged Identity Manager (ISPIM) external
authentication.
1. In the ISAM virtual appliance console, select Secure Access Control > Authentication.
2. Click the Advanced tab.
3. Select OTPGetMethods and click the Edit icon.
4. In the Mapping Rules – OTPGetMethods window, modify the content to retrieve the email
address and mobile number from the email and mobile header that you previously set in the
ISPIM external authentication mechanism.
Page | 40
5. Click Save.
6. Select OTPVerify and click the Edit icon.
7. On the Mapping Rules – OTPVerify window, remove all the lines except the first commented
line.
Page | 41
8. Click Save.
9. Deploy the changes.
4.3.2.2.5. Define an Access Control Policy to protect ISPIM junctions with SMS or Email OTP
Define an Access Control Policy to protect IBM® Security Privileged Identity Manager (ISPIM)
authenticated junctions with email or SMS One-Time Password (OTP).
1. In the IBM® Security Access Manager virtual appliance (ISAM VA) console, select Secure
Access Control > Access Control.
2. Click the Policies tab.
3. Click the Create Policy icon.
4. Enter the Name and Description.
Page | 42
5. Add two rules with “Precedence: ‘First’”. If there is more than one rule that evaluates to true,
execute the first one.
• Rule 1
If ISPIM authentication mechanism and MAC OTP authentication mechanism
succeeds, then permit access.
• Rule 2
If only ISPIM authentication mechanism has passed, but not MAC OTP
authentication mechanism, then prompt the user to authenticate with an OTP.
4.3.2.2.6. Attach the Access Control Policy to the ISPIM authenticated junctions
Attach the Access Control Policy to the IBM® Security Privileged Identity Manager (ISPIM) authenticated
junctions.
1. In the IBM® Security Access Manager virtual appliance (ISAM VA) console, select Secure
Access Control > Access Control.
2. Click the Resources tab. Note that if it is the first time you are browsing Resources, you
must log in using sec_master to the Policy Server.
3. Add the ISPIM authenticated junctions as resources to be protected by One-Time Password
(OTP). See 4.3.2.2.6.1 Adding ISPIM authenticated junctions
4. Click Add Resource icon, and select your WebSEAL instance name in the Web container
field.
5. Click Browse, and add the ISPIM authenticated junctions (4.3.2.2.6.1 Adding ISPIM
authenticated junctions) as Resource to be protected by OTP.
Page | 43
4.3.2.2.6.1. Adding ISPIM authenticated junctions
Add the following ISPIM authenticated junctions as resources that are to be protected by the OTP.
Authenticated Junctions Purpose
/admin AccessAdmin
/ispim/ui Service Center
/itim/console Admin Console
/itim/self Self-Service UI
/recorder/ui Privileged Session Recorder console
After adding all the ISPIM authenticated junctions, for each junction:
1. Click the Attach icon, and attach the Access Control Policy. For example, MAC OTP Policy-
Default.
2. Click the Publish All icon.
5. Troubleshooting and support To help you understand, isolate, and resolve problems with your IBM® software, the troubleshooting and
support information contains instructions for using the problem-determination resources that are provided
with your IBM® products.
Page | 44
5.1. Ensure that entities are configured
Since we are working with three different entities (IBM® Security Privileged Identity Manager (ISPIM),
IBM® Security Access Manager (ISAM) WebSEAL and Advanced Access Control (AAC)), it is important
to ensure that each entity is configured and working before configuring the connection between them:
• ISPIM – WebSEAL
• WebSEAL – AAC
• ACC – ISPIM (the ISPIM custom authentication plug-in)
5.2. Ensure that integration is setup after configuring ISPIM –
WebSEAL settings After configuring IBM® Security Privileged Identity Manager (ISPIM) – WebSEAL settings, it is suggested
to make sure the integration is properly setup, before continuing with the rest of the setup.
1. Create a user in the ISPIM user registry.
2. Create the same username and password in WebSEAL user registry through Policy
Administration.
3. Go to the URL: https://<WebSEAL_URL>:<WebSEAL_Port>/<any_ISPIM_web_console_junction>
4. You should be prompted by the default WebSEAL login page.
5. Enter the username and password that you setup in WebSEAL user registry.
6. If the connection between ISPIM - WebSEAL has been configured properly, you will be
logged in to the ISPIM web console that you entered in the URL.
5.3. Enabling the ISAM built-in Diagnostic Tool for troubleshooting
IBM® Security Access Manager (ISAM) has a built-in Diagnostic Tool for Advanced Access Control
(AAC). This tool is useful to troubleshoot the state in between authentication stages. After configuring the
WebSEAL – AAC connection, you can enable this tool by following these steps:
1. Go to Secure Access Control > Advanced Configuration.
2. Edit the value for key live.demos.enabled to true.
3. Go to Secure Web Settings > Policy Administration.
4. Login with sec_master credential.
5. Attach Access Control List (ACL) isam_mobile_anyauth to /mga/mobile-demo of your
WebSEAL instance.
6. To access the tool, go to https://<WebSEAL_URL>:<WebSEAL_Port>/mga/mobile-demo
7. Select the Diagnostics tab.
Page | 45
Expected Results: At any authentication stage, this tool will display all the attributes and value present in the ISAM
credential for the user and the HTTP headers.
Note: If it is not working, just refresh the page after each authentication stage.
5.3.1. Configure tool settings with environment setup
The first time you setup the ISAM built-in Diagnostic Tool for your WebSEAL instance, you have to
configure the tool settings with your environment setup.
1. Enter the required fields:
• Runtime Host and Port
Your AAC host and port number
• Management UI Host and Port
The ISAM VA console hostname and port
• Management UI Username
The ISAM VA console username.
• Management UI Password
The ISAM VA console password.
• Reverse Proxy Host and Port
The WebSEAL instance for this tool to diagnose.
• Attribute Collector Cookie Name
Leave it as the default value “ac.uuid” if you do not change any AAC setting for
Attribute Collector.
Page | 46
5.3.2. Example of the ISAM Credential value
1. Enter the required fields:
• AuthenticationMechanismTypes
AuthenticationMechanismTypes field contains the identifier of the authentication
mechanisms the user has passed successfully. In this example, the user has successfully
authenticated with ISPIM external authentication and MAC OTP authentication. This
attribute is used in the condition of the Access Control Policy.
• ispim_email
Email Header that is set in the ISPIM authentication mechanism and contains the user’s
email address retrieved from the ISPIM user registry. You can use this tool to check if the
properties set in the IPSIM authentication are properly populated and if mapping rules are
set properly to pass the email address to the OTP authentication.
Page | 47
5.3.3. Example of the HTTP Headers value