IBM® SECURITY PRIVILEGED IDENTITY MANAGER VERSION 2.0 · ISAM. 3.2. Login workflow when ISAM is enabled When IBM® Security Access Manager (ISAM) is enabled, you cannot login directly

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.

http://www.ibm.com/support/knowledgecenter/SSPREK_9.0.0/com.ibm.isam.doc/welcome.html

http://www.ibm.com/support/knowledgecenter/SSPREK_9.0.0/com.ibm.isam.doc/welcome.html

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


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


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.


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.


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.


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.


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.




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.




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.



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.


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


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.


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

Documents

IBM® SECURITY PRIVILEGED IDENTITY MANAGER VERSION 2.0 · ISAM. 3.2. Login workflow when ISAM is enabled When IBM® Security Access Manager (ISAM) is enabled, you cannot login directly