IBM Support

Sample CyberArk credential vault user exit integration with Content Manager Java Connector API added in version 8.6 Fix Pack 3

White Papers


Abstract

Sample CyberArk credential vault user exit integration with Content Manager Java Connector API. This exit was added in version 8.6 fix pack 3.

Content

The Content Manager API, starting in version 8.6 fix pack 3, includes the infrastructure to provide a credential vault user exit.  This sample implements an exit to map CyberArk login information to the actual database userid and password that are used by IBM® Content Manager.

To use a credential vault user exit you must:

  • implement the com.ibm.mm.sdk.common.dkCredentialVaultUserExitICM Content Manager API interface. Add the
    @CyberArkGetPassword keyword above your class definition for CyberArk hash generation.
  • create a .jar file that contains the credential vault user exit. The exit will be built with a Java JDK, the JavaPasswordSDK.jar from the CyberArk Credential Provider, and the Content Manager Java Connector API.
  • Generate a authentication hash using the CyberArk JavaAIMGetAppInfo utility against the created credential vault user exit .jar file. Add the hash to the CyberArk administration application authentication tab.
  • add this .jar file along with the CyberArk JavaPasswordSDK.jar to the classpath.

The CyberArk credential vault user exit maps a CM server identifier and a CyberArk object and password to a mapped database userid and password that are used by Content Manager. The server identifier, credential vault user exit class, and credential vault indicator are stored in either the cmbicmsrvs.ini file or passed into the CM API in the connect string.

  • When calling a CyberArk credential password vault, the server identifier must be passed, so that it knows what mapped database userid and password should be returned to the Content Manager API.
  • If the credential vault user exit cannot be loaded or throws an exception, the Content Manager API throws a DKUsageError exception to indicate that there is an error in the credential vault user exit.
  • If the credential vault user exit getCredentialData(String,String,String,DKNVPair[]) method returns an empty userid for DKNVPair value of DKConstantICM.DK_ICM_PARM_CRED_VAULT_USERID or an empty password for DKNVPair value of DKConstantICM.DK_ICM_PARM_CRED_VAULT_AUTH, the Content Manager API throws a DKUsageError exception.  With the sample below, this would only happen if CyberArk returns a blank userid or password.
  • If the credential vault exit getCredentialData(String,String,String,DKNVPair[]) method cannot find the credential information for the specified server identifier, it returns a null or empty array to the Content Manager API.  This will cause the API to proceed with database authentication using the userid and password specified by the caller, no mapping is done.

Setting up the CyberArk credential vault exit

  1. Implement the com.ibm.mm.sdk.common.dkCredentialVaultUserExitICM interface for the credential vault user exit class (Example: com.mycomp.MyCyberArkUserExitEX). Add the @CyberArkGetPassword keyword above your class definition for CyberArk hash generation.
  2. Create a .jar file that contains the implemented credential vault user exit class
  3. Generate a authentication hash using the CyberArk JavaAIMGetAppInfo utility against the created credential vault user exit .jar file. Add this hash to the CyberArk application authentication. (Example: Lets say the created credential vault user exit .jar file is called MyCyberArkCM.jar which contains com.mycomp.MyCyberArkUserExitEX class and is located in the C:\cyberarkCM directory. If the user opens a command window, runs cmbenv81.bat, make sure that java is setup in that window and run java -jar C:\PROGRA~2\CyberArk\ApplicationPasswordProvider\Utils\JavaAIMGetAppInfo.jar GetHash /AppExecutablesPattern=c:\cyberarkCM /ClassPath="c:\IBM\db2cmv8\lib;c:\cyberarkCM" /OnlyExecutablesWithAIMAnnotation=yes /OutputDelimiter=";" /LogFileDirectory="C:\cyberarkCM\log" which will generate a CyberArk hash for the class MyCyberArkUserExitEX in the MyCyberArkCM.jar. Add the hash to the CyberArk administration application authentication tab).
  4. Add the exit .jar file and the associated .jar files that are needed by the exit to the classpath.
  5. Update the cmbicmsrvs.ini file with the following settings for each server where the user exit needs to be applied:
    ICMCREDVAULT=TRUE
    ICMCREDVAULTSERVERID=APPID=MyComp-ApplEX1;SAFE=SafeEX1;FOLDER=Root   ICMCREDVAULTUSEREXITCLASSNAME=com.mycomp.MyCyberArkUserExitEX

    Note: APPID, SAFE and FOLDER keywords in the ICMCREDVAULTSERVERID option must be in uppercase.
  6. Create a DKDatastoreICM.
  • To log in by using a system database id (for example, an id that is mapped to icmadmin), connect by using the mapped credential vault userid (CyberArk Object) and password.
  • To login by using a Content Manager id that is not a database id, make sure that the cmbicmenv.ini file contains the mapped credential vault userid (CyberArk Object) and password.

Example scenarios

Sample CyberArk User Exit Example (MyCyberArkUserExitEX.java) is attached to this document. To use this exit, do the following.
Note: To run cmbjavaenv.bat/sh the user should supply the Java SDK or OpenJDK install directory. The user should also supply the Xerces install directory and the Xalan install directory. This file relies on variables IBMCMROOT and ORACLE_HOME to dynamically setup based on installation locations on your particular system, typical defaults are assumed.
To Compile:
  1. Open a command window and make sure the java JDK has been configured for this window.
  2. Run cmbjavaenv c:\jdk1.8.0x64 c:\xerces-2_12_0 c:\xalan-j_2_7_2 (CMv8 Connector setup).
  3. Add CyberArk JavaPasswordSDK.jar to CLASSPATH.
  4. Create a directory to hold the java user exit. C:\CyberArkUserExit\com\mycomp and add C:\CyberArkUserExit to CLASSPATH.
  5. Download MyCyberArkUserExitEX.java into the C:\CyberArkUserExit\com\mycomp directory.
  6. Compile CyberArk user exit (MyCyberArkUserExitEX.java).
  7. Create a temp directory that contains the classfile for the user exit. C:\CyberArkUserExitTmp\com\mycomp\MyCyberArkUserExitEX.class.
  8. Create a jar file for everything under C:\CyberArkUserExitTmp which will contain the user exit.
To Run:
  1. Open a command window and make sure java JDK has been configured for this window.
  2. Run cmbjavaenv c:\jdk1.8.0x64 c:\xerces-2_12_0 c:\xalan-j_2_7_2 (CMv8 Connector setup)
  3. Add CyberArk JavaPasswordSDK.jar to CLASSPATH.
  4. Add CyberArk user exit jar file created above to CLASSPATH.
  5. Once cmbicmsrvs.ini and cmbicmenv.ini are setup you can connect to CyberArk as described in the examples below.
  6. You could use the SConnectDisconnectICM.java sample provided with CM to test this.

The following example scenarios use these userids and passwords:

Note: CyberArk user exit example can use any non empty string for the password passed to the datastore. This user exit example will ignore this value because CyberArk uses a CyberArk object along with the information in the serverid for authentication.

IBM Content Manager userids and passwords for the IBM Content Manager database (icmnlsdb) CyberArk userids (CyberArk Object) and passwords for serverid: APPID=MyComp-ApplEX1;SAFE=SafeEX1;FOLDER=Root
icmadmin/password1 (system id/database id) Application-CyberArk-CM-icmadmin/password5
icmconct/ password2 (system id/database id) Application-CyberArk-CM-icmconct/ password6
user1/password3
user2/password4
Credential vault mapping in vault
Serverid                            CyberArk Object/pw                                                Content Manager userid/pw
APPID=MyComp-ApplEX1;SAFE=SafeEX1;FOLDER=Root Application-CyberArk-CM-icmadmin/password5 icmadmin/password1
APPID=MyComp-ApplEX1;SAFE=SafeEX1;FOLDER=Root Application-CyberArk-CM-icmconct/password6 icmconct/password2
The serverid is made up of the CyberArk application id, safe and folder (ie APPID=MyComp-ApplEX1;SAFE=SafeEX1;FOLDER=Root).
These scenarios assume that the credential vault contains serverids that are associated with all library server database ids for a particular Content Manager server.

The cmbicmenv.ini file contains icmnlsdb (userid Application-CyberArk-CM-icmconct and password password6). The user logs in by using Application-CyberArk-CM-icmadmin and password5 when the user wants to login for icmadmin/password1.

Scenario 1 - admin user with ID stored in the vault - Rep type DB2

This scenario uses a cmbicmsrvs.ini file like this:

ICMSERVER=icmnlsdb
ICMSERVERREPTYPE=DB2
ICMSCHEMA=ICMADMIN
ICMSSO=FALSE
ICMDBAUTH=SERVER
ICMREMOTE=FALSE
ICMHOSTNAME=mufasa
ICMPORT=50000
ICMREMOTEDB=icmnlsdb
…
ICMCREDVAULT=TRUE
ICMCREDVAULTSERVERID=APPID=MyComp-ApplEX1;SAFE=SafeEX1;FOLDER=Root
ICMCREDVAULTUSEREXITCLASSNAME=com.mycomp.MyCyberArkUserExitEX

  1. DKDatastoreICM connects to icmnlsdb by using Application-CyberArk-CM-icmadmin/password5.
  2. The datastore tries to get the database userid and password from the credential vault user exit (that is, com.mycomp.MyCyberArkUserExitEX) by using serverid MyComp-ApplEX1;SAFE=SafeEX1;FOLDER=Root.

    The exit returns the database userid and password (that is, icmadmin and password1).

  3. The datastore logs into the database by using the database userid and password, and then passes the database id (icmadmin/password1) to the library server login stored procedure.

Scenario 2 - non-admin user that uses the CM connect ID - Rep type DB2

This scenario uses the same cmbicmsrvs.ini file as Scenario 1.

  1. DKDatastoreICM connects to icmnlsdb by using user1/password3.
  2. The datastore tries to gets the database userid and password from the credential vault user exit (com.mycomp.MyCyberArkUserExitEX) by using serverid MyComp-ApplEX1;SAFE=SafeEX1;FOLDER=Root.

    The exit does not return any items because user1 is not in the credential vault because this user connects to the database with the CM connect userid.

  3. The datastore logs into the database by using the input userid and password (that is, user1 and password3). This fails.  This logon is tried first because ICMSERVERREPTYPE is set to DB2 and not DB2CON.
  4. The datastore reads the credential vault connect userid and password from the cmbicmenv.ini file (that is, Application-CyberArk-CM-icmconct and password6).
  5. The datastore tries to get the database userid and password from the credential vault user exit (that is, com.mycomp.MyCyberArkUserExitEX) by using serverid MyComp-ApplEX1;SAFE=SafeEX1;FOLDER=Root.

    The exit returns the database userid and password (that is, icmconct and password2).

  6. The datastore logs into the database by using the database userid and password, and then passes the CM userid (that is, user1 and password3) to the library server login stored procedure.

Scenario 3 - admin user with ID stored in the vault - Rep type DB2CON

This scenario uses a cmbicmsrvs.ini file like this:

ICMSERVER=icmnlsdb
ICMSERVERREPTYPE=DB2CON
ICMSCHEMA=ICMADMIN
ICMSSO=FALSE
ICMDBAUTH=SERVER
ICMREMOTE=FALSE
ICMHOSTNAME=mufasa
ICMPORT=50000
ICMREMOTEDB=icmnlsdb
…
ICMCREDVAULT=TRUE
ICMCREDVAULTSERVERID=APPID=MyComp-ApplEX1;SAFE=SafeEX1;FOLDER=Root
ICMCREDVAULTUSEREXITCLASSNAME=com.mycomp.MyCyberArkUserExitEX
  1. DKDatastoreICM connects to icmnlsdb by using Application-CyberArk-CM-icmadmin/password5.
  2. It reads the credential vault connect userid and password from the cmbicmenv.ini file (that is, Application-CyberArk-CM-icmconct and password6).
  3. The datastore tries to get the database userid and password from the credential vault user exit (com.mycomp.MyCyberArkUserExitEX) by using serverid MyComp-ApplEX1;SAFE=SafeEX1;FOLDER=Root.

    The exit returns the database userid and password (that is, icmconct and password2).

  4. The datastore logs into the database by using the database userid and password.
  5. The datastore gets the database userid and password from the credential vault user exit (com.mycomp.MyCyberArkUserExitEX) by using serverid MyComp-ApplEX1;SAFE=SafeEX1;FOLDER=Root for Application-CyberArk-CM-icmadmin/password5.

    The exit returns the database userid and password (that is, icmadmin and password1).

  6. The datastore passes the database userid and password (that is, icmadmin and password1) to the library server login stored procedure. This fails.
  7. The datastore logs off from the database.
  8. The datastore logs into the database by using the database userid and password (that is, icmadmin and password1), and then passes that database userid and password to the library server login stored procedure.

Scenario 4 - non-admin user that uses the CM connect ID - Rep type DB2CON

This scenario uses the same cmbicmsrvs.ini file as Scenario 3.

  1. DKDatastoreICM connects to icmnlsdb by using user1 and password3.
  2. The datastore reads the credential vault connect userid and password from the cmbicmenv.ini file (that is, Application-CyberArk-CM-icmconct and password6).
  3. The datastore tries to get the database userid and password from the credential vault user exit (com.mycomp.MyCyberArkUserExitEX) by using serverid MyComp-ApplEX1;SAFE=SafeEX1;FOLDER=Root.

    The exit returns the database userid and password (that is, icmconct and password2).

  4. The datastore logs into the database with the database userid and password.
  5. The datastore tries to get the database userid and password from the credential vault user exit (com.mycomp.MyCyberArkUserExitEX) by using serverid MyComp-ApplEX1;SAFE=SafeEX1;FOLDER=Root for user1 and password3.

    The exit does not return any items because user1 is not in the credential vault.

  6. The datastore passes the IBM Content Manager userid and password (that is, user1 and password3) to the library server login stored procedure.

Content Manager API CyberArk User Exit Example

[{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSRS7Z","label":"IBM Content Manager Enterprise Edition"},"ARM Category":[{"code":"a8m0z000000cwuaAAA","label":"Content Manager"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"8.6.0","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
01 September 2020

UID

ibm16116272

Page Feedback