Accessing the ID Vault

The encryption and decryption of documents requires access to the ID Vault to retrieve the secret keys of the active user. These transactions require the name of the ID Vault server as well a user name and password for access to the vault.

This user name and password is not necessarily the same as the Domino® directory user ID used to log into the XPages application. Clearly, it would not be efficient for the user to be constantly prompted for this information so a utility object is provided as part of the XPages runtime to smoothly manage this process. This object is known as the dominoIDVaultBean.

The dominoIDVaultBean is a managed bean that is automatically instantiated on behalf of each user by the XPages runtime. Its job is to maintain the ID Vault access details on behalf of each user - namely the user name, password and ID Vault server name.

For each encrypt and decrypt operation the XPages runtime asks the dominoIDVaultBean for the previously mentioned vault access properties. If the default properties are not applicable due to the particular Domino® configuration then the application developer must ensure that the dominoIDVaultBean has the correct properties set in order for encryption to work. This can be achieved, for example, by using an extended login screen which would prompt the user for the ID Vault access properties when the application is first loaded. The dominoIDVaultBean will maintain this data for the duration of the user’s session and discard it once the session ends.

This sample SSJS snippet demonstrates this:

dominoIDVaultBean.setUserName("Jane Doe/ACME");
dominoIDVaultBean.setUserPassword("BlueN0te");
dominoIDVaultBean.setServerName("BigIron/IBM");
var userId = dominoIDVaultBean.getUserID();
if (userId != null){
	print(userId.getEncryptionKeys().toString());
}

The output of the print statement might look like this, where each element represents the name of a secret key in Jane Doe’s user id:

[HR, Finance, ProjectBlooper, Sales, JanesKey]

Problems that may arise, for example, bad credentials for ID Vault access, would result in this error being reported:

The user ID for Jane Doe could not be retrieved from the ID vault server on BigIron/Acme

A bad password could also result in extra errors being sent to the Domino® server console:

Server BigIron/Acme reported the following problem causing authentication to fail: Wrong Password.
(Passwords are case sensitive - be sure to use correct upper and lower case.)

More information on dominoIDVaultBean is provided in a separate topic available in this section of the XPages User Guide.