Credential vault user exit

The Content Manager API includes the infrastructure to provide a credential vault user exit to map a credential vault userid and password to the actual database userid and password that are used by IBM® Content Manager.

The credential vault user exit must:

implement the com.ibm.mm.sdk.common.dkCredentialVaultUserExitICM Content Manager API interface
create a .jar file that contains the credential vault user exit
add this .jar file to the classpath.

The credential vault user exit maps a server identifier and a credential vault userid 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 the connect string.

When calling a 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.
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.

Setting up the credential vault exit

Implement the com.ibm.mm.sdk.common.dkCredentialVaultUserExitICM interface for the credential vault user exit class (that is, com.mycomp.MyCredVaultUserExitEX).
Create a .jar file that contains the implemented credential vault user exit class
Add the .jar file and the associated .jar files that are needed by the exit to the classpath.
Update the cmbicmsrvs.ini file with the following settings for each server where the user exit needs to be applied:
```
ICMCREDVAULT=TRUE
ICMCREDVAULTSERVERID=serverId
ICMCREDVAULTUSEREXITCLASSNAME=com.mycomp.CredentialVaultUserExit
```
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 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 and password.

Example scenarios

The following example scenarios use these userids and passwords:

IBM Content Manager userids and passwords for the IBM Content Manager database (icmnlsdb)	Credential vault userids and passwords for serverid (serverid1)
`icmadmin`/`password1` (system id/database id)	`cvaultadmin`/`password5`
`icmconct`/ `password2` (system id/database id)	`cvaultconct`/ `password6`
`user1`/`password3`
`user2`/`password4`

Credential vault mapping in vault
Serverid1	`cvaultadmin`/`password5`	`icmadmin`/`password1`
Serverid1	`cvaultconct`/`password6`	`icmconct`/`password2`

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 cvaultconct and password password6). The user logs in by using cvaultadmin and password5 when the user wants to login for icmadmin/password1.

Scenario 1

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=Serverid1
ICMCREDVAULTUSEREXITCLASSNAME=com.mycomp.MyCredVaultUserExitEX

DKDatastoreICM connects to icmnlsdb by using cvaultadmin/password5.
The datastore tries to get the database userid and password from the credential vault user exit (that is, com.mycomp.MyCredVaultUserExitEX) by using serverid Serverid1.
The exit returns the database userid and password (that is, icmadmin and password1).
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

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

DKDatastoreICM connects to icmnlsdb by using user1/password3b.
The datastore tries to gets the database userid and password from the credential vault user exit (com.mycomp.MyCredVaultUserExitEX) by using serverid Serverid1.
The exit does not return any items because user1 is not in the credential vault.
The datastore logs into the database by using the input userid and password (that is, user1 and password3). This fails.
The datastore reads the credential vault connect userid and password from the cmbicmenv.ini file (that is, cvaultconnect and password6).
The datastore tries to get the database userid and password from the credential vault user exit (that is, com.mycomp.MyCredVaultUserExitEX) by using serverid Serverid1.
The exit returns the database userid and password (that is, icmconct and password2).
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

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=Serverid1
ICMCREDVAULTUSEREXITCLASSNAME=com.mycomp.MyCredVaultUserExitEX

DKDatastoreICM connects to icmnlsdb by using cvaultadmin/password5.
It reads the credential vault connect userid and password from the cmbicmenv.ini file (that is, cvaultconnect and password6).
The datastore tries to get the database userid and password from the credential vault user exit (com.mycomp.MyCredVaultUserExitEX) by using serverid Serverid1.
The exit returns the database userid and password (that is, icmconct and password2).
The datastore logs into the database by using the database userid and password.
The datastore gets the database userid and password from the credential vault user exit (com.mycomp.MyCredVaultUserExitEX) by using serverid Serverid1 for cvaultadmin/password5.
The exit returns the database userid and password (that is, icmadmin and password1).
The datastore passes the database userid and password (that is, icmadmin and password1) to the library server login stored procedure. This fails.
The datastore logs off from the database.
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

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

DKDatastoreICM connects to icmnlsdb by using user1 and password3.
The datastore reads the credential vault connect userid and password from the cmbicmenv.ini file (that is, cvaultconnect and password6).
The datastore tries to get the database userid and password from the credential vault user exit (com.mycomp.MyCredVaultUserExitEX) by using serverid Serverid1.
The exit returns the database userid and password (that is, icmconct and password2).
The datastore logs into the database with the database userid and password.
The datastore tries to get the database userid and password from the credential vault user exit (com.mycomp.MyCredVaultUserExitEX) by using serverid Serverid1 for user1 and password3.
The exit does not return any items because user1 is not in the credential vault.
The datastore passes the IBM Content Manager userid and password (that is, user1 and password3) to the library server login stored procedure.