IBM Security Access Manager Adapter

for IBM Security Identity Manager and IBM Security

Identity Governance and Intelligence

—
Antti Merihaara, Darren Pond, David Lounton, Gianluca Gargaro

Europe & MEA Technical Support for Security Identity and Access Management products
Goal of Session

Share information on how to use and troubleshoot IBM Security Access Manager Adapter (also
known as the ISAM Combo Adapter) with the latest level of the ISAM, ISIG and ISIM

IBM Security / © 2019 IBM Corporation 2

Agenda

What is going to be covered:

• Architecture and scope

• ISAM Java Direct API

• ISIM ISAM Adapter

• Troubleshooting

IBM Security / © 2019 IBM Corporation 3

Architecture and scope

GIANLUCA GARGARO

• Adapter Architecture
• History of ISAM API
• ISAM Java Admin and Authzn API – Traditional
• ISAM Java Admin and Authzn and Registry Direct API - Combined
• ISAM Registry Direct API – Stand-alone
• Integration Architecture

IBM Security / © 2019 IBM Corporation 4

Adapter Architecture

ISIM Appliance

ISAM Appliance
RMI
Dispatcher Service
ISAM API
ISIG Appliance ADAPTER

LDAP
Server
History of ISAM JAVA API

• Java Admin and Authnz API have been introduced first replicating C API.
• Registry Direct API was introduced later in Tivoli Access Manager version 6.1.1 along with User Self Care./
• One of the benefits of Registry Direct API compared to traditional Access Manager API was the improved
performance when handling access manager users ldap objects.

• Another benefit of Registry Direct API was the removal of a single point of failure with the Policy Server.
ISAM Java Admin and Authzn API -Traditional
ISAM Node
JAVA APP
ISAM Authzn Server
ISAM Java Runtime Policy DB
Replica
ISAM Admin API Classes ISAM Authzn API Classes LDAP Client

ISAM Admin Client ISAM Authzn Client

ISAM Policy Server ISAM Authzn Server

LDAP Client LDAP Server

LDAP Server

Policy DB

ISAM Primary Master

ISAM Java Admin and Authzn and Registry Direct API - Combined

JAVA APP ISAM Node

ISAM Authzn Server

ISAM Java Runtime
Policy DB
Replica
ISAM Admin API Classes ISAM Authzn API Classes ISAM RDAPI Classes LDAP Client

ISAM Admin Client ISAM Authzn Client ISAM LDAP Client

ISAM Policy Server ISAM Authzn Server

LDAP Client LDAP Server

LDAP Server

Policy DB

ISAM Primary Master

ISAM Java Registry Direct API – Stand-alone

JAVA APP
ISAM Java Runtime

ISAM RDAPI Classes

ISAM LDAP Client

ISAM Runtime
LDAP LDAP
Server Server
LDAP Client
LDAP LDAP
Server Server

Policy DB

ISAM Appliance
ISAM Java Registry Direct API – Docker

JAVA APP
ISAM Java Runtime

ISAM RDAPI Classes

ISAM LDAP Client

(443+444)
Runtime
Full LMI
(9443)

Proxy

(443)
(443)

DSC
LDAP LDAP
Server Server

LDAP LDAP
Ports Server Server

Config AAC
WRP DSC
Container Runtime
Container Container
Container
Used in AAC runtime for USC

AAC Runtime

USC Authentication Policies

OTP services Email services SCIM Conf Services INFOMAP Auth Mech

reCaptcha Services SCIM Services

ISAM RDAPI Classes

Server Connection
Server Connection
Server Connection

LDAP LDAP
Server Server

LDAP LDAP
Server Server
Integration Architecture

LDAP LDAP
ISAM Adapter Server Server ISAM Adapter
ITDI ITDI
LDAP LDAP
Server Server

Federated Registry

ISIM ISIG
Runtime Runtime
ISAM Runtime
ISIM Appliance ISIG Appliance

ISAM appliance

ISAM WRP

End user Browser

ISAM Java Direct API

ANTTI MERIHAARA

• Requirements

• Preparation

• Configuration

• Properties file

IBM Security / © 2019 IBM Corporation 13

Requirements

• Currently supported user registries are listed under subject "Supported registries" of the IBM Security
Access Manager documentation.
https://www.ibm.com/support/knowledgecenter/SSPREK_9.0.6/com.ibm.isam.doc/config_web/concept/con
_sup_reg.html

• IBM Security Directory Server

• IBM Security Directory Server for z/OS

• Microsoft Active Directory

• Microsoft Active Directory Lightweight Directory Service (ADLDS)

• Sun Java System Directory Server

• Novell eDirectory
Requirements

• Supported Java runtimes are documented in “Setting up an Access Manager Runtime for Java system”
https://www.ibm.com/support/knowledgecenter/SSPREK_9.0.6/com.ibm.isam.doc/config_web/concept/c
on_sup_reg.html

• IBM® Java Runtime

• The JRE provided with WebSphere® Application Server

Preparation
Environment preparation prior configuring the Registry Direct API:

1. Set up an Access Manager environment and at minimum configure Access Manager runtime i.e.
Policy Server.

2. Review the latest instructions under "Installing IBM Security Access Manager Runtime for Java" in
the ISAM documentation.
https://www.ibm.com/support/knowledgecenter/SSPREK_9.0.6/com.ibm.isam.doc/adk/task/tsk_jrtep
gk_install.html

3. Get the file pdjrte-9.x.x.x.zip ( Access Manager Runtime for Java files ) from the Access Manager
appliance https://<isam appliance>/isam/downloads.

4. Copy ISAM runtime for java files into a server where the Registry Direct API access is required and
extract package.
Pdjrte download from ISAM Appliance
Preparation
Environment preparation prior configuring the Registry Direct API:

1. Set PATH and JAVA_HOME environment variables to include Java runtime.

1. Example:
2. export PATH=/opt/IBM/WebSphere/AppServer/java/jre/bin:$PATH
3. export JAVA_HOME=/opt/IBM/WebSphere/AppServer/java

2. Get signer certificate from an user registry when planning to use secure connection between the
Registry Direct API and an user registry.

3. Set up a key store for the Registry Direct API to connect user registry over the secure connection.
Configuration
Configuration can be achieved either with SvrSslCfg or RgyConfig Java tools.

In this presentation we are concentrating to the RgyConfig tool.

Following is the syntax of the RgyConfig tool:

java -cp pdjrte/java/export/rgy/com.tivoli.pd.rgy.jar com.tivoli.pd.rgy.util.RgyConfig
Usage:
java com.tivoli.pd.rgy.util.RgyConfig [-server <serverid>] <file> <command> [options]
<file> configuration properties file path name
<command> is one of:
create <mgmt_domain> <local_domain> <ldap.svrs> <ldap.bind_dn> <ldap.bind_pwd> [<ldap.ssl_truststore> <ldap.ssl_truststore_pwd>]
load <input properties file>
set <name> <value>
remove <name>
get <name>
list
Configuration
Example of RgyConfig command for creating configuration for the Registry Direct API:

java -cp pdjrte/java/export/rgy/com.tivoli.pd.rgy.jar com.tivoli.pd.rgy.util.RgyConfig

/root/Desktop/ISAM9050_dev/testrgyapi.properties create Default Default
"192.168.10.105:636:readwrite:5" "cn=root,secAuthority=Default" "passw0rd"
keyStoreForConnectingISAM9050LDAP.jks "Passw0rd"
Configuration
Command presented in the previous slide creates testrgyapi.properties file with following data:

#IBM Security Access Manager

#Tue Jan 15 17:17:36 EET 2019
mgmt_domain=Default
ldap.bind-pwd={obf2}lHJ+EP9sHYkQgSBxdYMv2RbcvjNjbkhAdQncAolWYaU\=
ldap.ssl-enable=true
ldap.bind-dn=cn\=root,secAuthority\=Default
ldap.mgmt=true
ldap.svrs=192.168.10.105\:636\:readwrite\:5;
ldap.mgmt-version=9.0.5
ldap.ssl-truststore-pwd={obf2}lpTOHmJq68WsempLgqdgZONl8IiX5lHXdNfAkTL/7ao\=
local_domain=Default
ldap.ssl-truststore=file\:/root/Desktop/ISAM9050_dev/keyStoreForConnectingISAM9050LDAP.jks
Configuration
Commands adding federated directory to RDAPI configuration file:

java -cp pdjrte/java/export/rgy/com.tivoli.pd.rgy.jar com.tivoli.pd.rgy.util.RgyConfig -server ad_kdc

/root/Desktop/ISAM9050_dev/testrgyapi.properties set "ldap.svrs" "win2008r2dc.ibm.net:389:readwrite:6“

java -cp pdjrte/java/export/rgy/com.tivoli.pd.rgy.jar com.tivoli.pd.rgy.util.RgyConfig -server ad_kdc

/root/Desktop/ISAM9050_dev/testrgyapi.properties set "ldap.bind-dn"
"CN=isambind,CN=Users,DC=ibm,DC=net“

java -cp pdjrte/java/export/rgy/com.tivoli.pd.rgy.jar com.tivoli.pd.rgy.util.RgyConfig -server ad_kdc

/root/Desktop/ISAM9050_dev/testrgyapi.properties set "ldap.bind-pwd" "Passw0rd“

java -cp pdjrte/java/export/rgy/com.tivoli.pd.rgy.jar com.tivoli.pd.rgy.util.RgyConfig -server ad_kdc

/root/Desktop/ISAM9050_dev/testrgyapi.properties set "ldap.suffix" "CN=Users,DC=ibm,DC=net"
Configuration
New key/value pairs in the testrgyapi.properties:

#IBM Security Access Manager

#Wed Jan 16 14:43:50 EET 2019
mgmt_domain=Default
fed-server.ad_kdc.ldap.svrs=win2008r2dc.ibm.net\:389\:readwrite\:6;
ldap.bind-pwd={obf2}lHJ+EP9sHYkQgSBxdYMv2RbcvjNjbkhAdQncAolWYaU\=
ldap.ssl-enable=true
ldap.bind-dn=cn\=root,secAuthority\=Default
fed-server.ad_kdc.ldap.bind-dn=CN\=isambind,CN\=Users,DC\=ibm,DC\=net
fed-server.ad_kdc.ldap.suffix=CN\=Users,DC\=ibm,DC\=net;
ldap.svrs=192.168.10.105\:636\:readwrite\:5;
ldap.mgmt=true
fed-server.ad_kdc.ldap.bind-pwd={obf2}+fDgltY5OrWKicxmx6i9deKrCp6cnjrtJaHzTPWf4II\=
ldap.mgmt-version=9.0.5
ldap.ssl-truststore-pwd={obf2}lpTOHmJq68WsempLgqdgZONl8IiX5lHXdNfAkTL/7ao\=
local_domain=Default
ldap.ssl-truststore=file\:/root/Desktop/ISAM9050_dev/keyStoreForConnectingISAM9050LDAP.jks
Usage of the properties file
Example of using Registry Direct API properties file in a Java code:

...
URL propertiesUrl = null;
try {
propertiesUrl = new URL("file", "", configFile);
}
catch (MalformedURLException e2) {
e2.printStackTrace();
System.exit(1);
}

RgyRegistry registry = null;

try {
registry = LdapRgyRegistryFactory.getRgyRegistryInstance(
propertiesUrl, null);
}
catch (RgyException e2) {
e2.printStackTrace();
System.out
.println("FAILED: Unable to obtain instance of LdapRegistry");
System.exit(1);
}
...
 ISAM Adapter

DAVID LOUNTON

• ISAM Adapter recommended levels

• ISAM adapter install and Configuration

• Confirm working Adapter

IBM Security / © 2019 IBM Corporation 25

ISAM Adapter
IBM Security Identity Adapter V7.1.27 for IBM Security Access Manager

• Adapter Installation Platform Recommend Levels –

• IBM Tivoli Directory Integrator 7.1.1 + FP8 + 7.1.1-TDI-TDI-LA0040 (JRE Level: JRE 7.0 SR10 FP40)

• IBM Security Directory Integrator 7.2 + FP5 + 7.1.1-TDI-TDI-LA0040 (JRE Level: JRE 7.0 SR10
FP40)

• ISIM RMI dispatcher - 7.1.39

Adapter Installation Tasks
1. Install the dispatcher.

2. Install the adapter binaries or connector.

3. Install 3rd party client libraries.

4. Set up the adapter environment.

5. Restart the adapter service.

6. Import the adapter profile.

7. Create an adapter service/target.

8. Install the adapter language package.

9. Verify that the adapter is working correctly.

Download and install Pdjrte (1 of 2)
Download and install Pdjrte (2 of 2)
Define Policy Server and Domain with Common logging
Registry Direct API
Configuring the IBM Security Access Manager Registry Direct API for Java System

Copy the com.tivoli.pd.rgy.jar file from IBM Security Access Manager installation directory to IBM Tivoli
Directory Integrator JRE installation directory.
Configure Java Runtime Environment
Configured Adapter into your IBM Security Access Manager secure domain.
Copy TAMComboUtils.jar to Directory Integrator

Copy TAMComboUtils.jar from the installation package to an appropriate IBM Tivoli Directory Integrator
location and restart dispatcher –

IBM Security / © 2019 IBM Corporation 32

Import Adapter profile
• Import adapter profile into ISIM and test adapter Recon

IBM Security / © 2019 IBM Corporation 33

Add Federated registries

ISAM ldap.conf

Commands to run

Results in the sam.conf

IBM Security / © 2019 IBM Corporation 34

Troubleshooting

DARREN POND

• Common Issues

• Registry Direct Troubleshooting

• ISAM Adapter Troubleshooting

IBM Security / © 2019 IBM Corporation 35

Common Issues
Pdjrtecfg Fails to configure

Caused by incorrect Java Home Environment parameters or Incorrect Version of Java being used

Registry Direct API does not support GSO credentials

Registry Direct API Troubleshooting
Java Logging is used for logging and trace
Example add following lines in to logging.properties file
( /opt/IBM/WebSphere/AppServer/java/jre/lib/logging.properties)

handlers = java.util.logging.FileHandler
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
com.tivoli.pd.rgy.ldap.level = FINEST
java.util.logging.FileHandler.pattern = /root/Desktop/ISAM9050_dev/java%

IBM Security / © 2019 IBM Corporation 37

Registry Direct API Troubleshooting

IBM Security / © 2019 IBM Corporation 38

Registry Direct API Troubleshooting

IBM Security / © 2019 IBM Corporation 39

ISAM Adapter Troubleshooting

Adapter trace from SDI is needed to understand if ISAM or ISIM issue

Edit the log4j.properties file in the SDI ISIM(Dispatcher) solution directory
(example: <TDI_HOME>/timsol/etc),

set the following: log4j.rootCategory=DEBUG, Default

IBM Security / © 2019 IBM Corporation 40

Useful Links
ISAM
ISAM Routing Trace: http://www.ibm.com/support/docview.wss?uid=swg21974925

ISAM Network TCP/IP Trace: http://www.ibm.com/support/docview.wss?uid=swg21960237

ISIM
ISIM support file
:https://www.ibm.com/support/knowledgecenter/en/SSRMWJ_7.0.1.7/com.ibm.isim.doc/admin/tsk/t_managing_support
_files.htm

ISIG
ISIG support file
https://www.ibm.com/support/knowledgecenter/SSGHJR_5.2.3/com.ibm.igi.doc/installing/tsk/t_managing_support_file
s.html

ISAM Adapter installation guide

https://www.ibm.com/support/knowledgecenter/SSRMWJ_7.0.0/com.ibm.itim_pim.doc_7.0/tamcombo/install_config/c_
install_ch.htm

IBM Security / © 2019 IBM Corporation 41

For more information
• Product Forum: https://ibm.biz/IGI-SupportForum
• Security Learning Academy for Identity Governance:
http://ibm.biz/IGI-SecLearnAcademy
• Identity & Access Management group in Security Community:
http://ibm.biz/IAMgroup-SecCommunity
• IBM Knowledge Center:
https://www.ibm.com/support/knowledgecenter/en/SSGHJR/welcome.html
Useful links:
Get started with IBM Security Support IBM Support
Sign up for My Notifications IBM Security Community

Follow us:

www.youtube.com/user/IBMSecuritySupport twitter.com/askibmsecurity http://ibm.biz/ISCS-LinkedIn

IBM Security / © 2019 IBM Corporation 42

Appendix – Getting signer cert from embedded
user registry
Following is an example of getting signer certificate of the ISAM appliance embedded user registry.
Connect to ISAM appliance Local Management Interface ( LMI ) SSL Certificates page https://<isam
appliance>/isam/ssl_certificates

Select embedded_ldap_keys database and go to Manage > Edit SSL Certificates Database
Appendix – Getting signer cert from embedded
user registry cont.

On the "Edit SSL Certificate Database" window

select "Personal Certificates" tab, select
"server" certificate and browse to Manage >
Export

Rename file to something meaningful ja save the

signer certificate on the disk for the next step.
Appendix – Getting signer cert from external
user registry
Following are an example steps of getting signer certificate of an external user registry:
Connect to ISAM appliance Local Management Interface ( LMI ) SSL Certificates page https://<isam
appliance>/isam/ssl_certificates

Select one of existing key databases ( or create a new ) and go to Manage > Edit SSL Certificates Database.

On the "Edit SSL Certificate Database" window select "Signer Certificates" tab and browse to Manage > Load.
On the "Load Signer Certificate" window fill in details for connecting external user registry and click Load.
With successful connection signer certificate is pulled from external user registry and placed to the key database.

Back on the "Edit SSL Certificate Database" window select newly loaded signer certificate and browse to Manage
> Export.

Save the signer certificate on the disk for the next step.

Notice! Addition to above steps intermediate certificates may need to be fetched from an user registry.
Appendix – Setup Java Key Store
Following are an example steps to create a Java Key Store ( JKS ) and adding a signer
certificate of an user registry to the key store. Certificate in the created Java Key Store is used
by the Registry Direct API to successfully connect user registry over the secure connection.

WebSphere Application Server ( WAS ) provides

ikeyman tool for handling certificates in Java
Key Stores

On the WAS server start ikeyman tool by

executing command: ikeyman

Once the ikeyman tool is started browse to "Key

Database File" > "New..." to create a new key
store
Appendix – Setup Java Key Store continues
In the pop-up window to create a new Java
key store select JKS for "Key database
type", provide name for key store file, set
location for the file and click OK.

In the next pop-up window provide

password for the key store file.
Appendix – Prepare Java Key Store continues
Once the key store file is created add signer
certificate to the key store:

1. In the "Key database content" drop down

select "Signer Certificates".

2. Click "Add...".

3. In the pop-up window click "Browse" to

open file system browser.

4. Browse to signer certificate file location

and select the file ( e.g.
EmbeddedLDAP9050.cer ).

5. Click "Open".
Appendix – Prepare Java Key Store continues
Signer certificate is now added to the key
store file and the ikeyman tool can be
closed.

Notice! Similarly add also any intermediate

certificates of an user registry to the ”Signer
Certificates” section if an user registry uses
certificate chain instead of just a root
certificate. Simply follow the steps in the
previous slide.
Thank you

Follow us on:
securitylearningacademy.com © Copyright IBM Corporation 2019. All rights reserved. The information contained in these materials is provided for
informational purposes only, and is provided AS IS without warranty of any kind, express or implied. Any statement of
LinkedIn - IBM Security Client Success direction represents IBM’s current intent, is subject to change or withdrawal, and represent only goals and objectives.
IBM, the IBM logo, and other IBM products and services are trademarks of the International Business Machines
Corporation, in the United States, other countries or both. Other company, product, or service names may be trademarks
youtube/user/ibmsecuritysupport or service marks of others.

twitter.com/AskIBMSecurity All names and references for organizations and other business institutions used in this deliverable’s scenarios are
fictional. Any match with real organizations or institutions is coincidental.
securityintelligence.com
Statement of Good Security Practices: IT system security involves protecting systems and information through prevention,
xforce.ibmcloud.com detection and response to improper access from within and outside your enterprise. Improper access can result in
information being altered, destroyed, misappropriated or misused or can result in damage to or misuse of your systems,
including for use in attacks on others. No IT system or product should be considered completely secure and no single
IBM Security Community product, service or security measure can be completely effective in preventing improper use or access. IBM systems,
products and services are designed to be part of a lawful, comprehensive security approach, which will necessarily
involve additional operational procedures, and may require other systems, products or services to be most effective. IBM
does not warrant that any systems, products or services are immune from, or will make your enterprise immune from, the
malicious or illegal conduct of any party.