User Manager

When the CCM API is used in a remote client, it requires the appropriate authentication and authorization for it to exercise the corresponding functionality.

User Manager Classes

This section lists and briefly describes the classes in User Manager. For more details, refer to the Javadoc.

The UserManagerFactory constructs the desired UserManager. The factory configuration parameters are:

Either:

  • CONFIG_URL—URL of the CredentialManager service in ActivID CMS.

Or both of the following:

  • CONFIG_HOST_NAME—Hostname of the CredentialManager service in ActivID CMS.

  • CONFIG_HOST_PORT—Port number of the CredentialManager service in ActivID CMS.

And:

  • CONNECT_TIMEOUT—Represents the client timeout used when connecting to the ActivID CMS HTTP server hosting the corresponding ActivID CMS service. A value of zero (0) means that there is no client timeout; the client timeout is determined by the server settings. The timeout value is for each connection attempt; the default value is zero (0).

  • CONNECT_RETRY—Represents the number of retry attempts permitted for connecting to the ActivID CMS service host. The default value is 1.

For Java implementations:

  • CONFIG_TRUSTSTORE (optional)—Truststore containing the root or intermediate certificate that issued the server certificate. If not present, the default Java truststore is used.

  • CONFIG_TRUSTSTORE_PWD (optional)—Password to the truststore.

  • CONFIG_KEYSTORE (mandatory)—Keystore which contains client certificate.

  • CONFIG_KEYSTORE_PWD (mandatory)—Password to the keystore.

  • CONFIG_ TRUSTMANAGERS (optional)—TrustManagers containing the root certificate.

  • CONFIG_ KEYMANAGERS (optional)—KeyManagers containing client certificate.SSL

A User object in CCM represents the holder of a SecurityModule such as a card. The createUser method takes a User object as its only parameter. This object contains a UserId attribute and an array of EnrollmentData Identifiers.

When creating a user, the CCM application should populate the EnrollmentData array with the minimum items required to create the user based on the information about the user in the underlying IDMS A collection of systems, processes, procedures, applications, database management systems, and interfaces that work together to manage and protect the identity information of PIV card applicants. The IDMS generally falls within the IDPRS domain. or user data repository.

When a User object is retrieved for an existing user, its EnrollmentData array is populated by ActivID CMS with using data retrieved from the underlying IDMS or user data repository.

The EnrollmentData and EnrollmentDataValue classes are used for conveying all enrollment data (user attributes) to ActivID CMS. The type attribute of the EnrollmentData class can accept the following value:

  • EnrollmentData.ENROLLMENT_DATA_TYPE_STRING

  • EnrollmentData.ENROLLMENT_DATA_ENCODING_NONE

  • EnrollmentData.ENROLLMENT_DATA_ENCODING_BASE64

The identifiers of EnrollmentData are user attribute identifiers. The names of these attributes may be prefixed to indicate whether they are associated with a particular enrollment plug-in An enrollment plug-in is involved every time a user attribute is set or retrieved by ActivID CMS. This makes it possible to map user attributes to repositories other than ActivID CMS’ standard LDAP (for example, such as IDMS, databases, or XML files). or with the ActivID CMS LDAP repository. Therefore:

  • When getEnrollmentData is performed on a prefixed identifier, this invokes the getAttribute method of the relevant server generic (enrollment) plug-in.

  • When addEnrollmentData is performed on a prefixed identifier, this invokes the setAttribute method of the relevant server generic (enrollment) plug-in.

  • Deleting enrollment data where a prefixed attribute is provided triggers setting the data to empty using the setAttributes method of the relevant server generic (enrollment) plug-in.

For more information, read about enrollment plug-ins in Defining a Generic Plug-In.

Behavior with Multi-Valued Attributes

The CCM API supports the LDAP concept of multi-valued attributes. To add initial or additional values to a multi-valued attribute, something similar to the following code example needs to be used:

Copy 
EnrollmentDataValue[] addData = {
new EnrollmentDataValue("favFruit","orange"), new EnrollmentDataValue("favFruit","apple") };
userMgr.addEnrollmentData(userId, addData);

For this example, there are two enrollment attributes that have the same ID, favFruit. In retrieving favFruit using the getEnrollmentData method, there are two entries with the same ID. However, they have different values that would be returned (as shown in this code example).

To delete an individual value from the list of values for favFruit:

Copy 
String delData[] = { "favFruit~apple" };
userMgr.deleteEnrollmentData(userId, delData);

The tilde (~) denotes the value of an EnrollmentDataValue. The left side of the ~ shows the enrollment data ID. The right side of the ~ identifies the value to be removed. The tilde notation can also be used with the addEnrollmentData method, as shown in the following example:

Copy 
EnrollmentDataValue[] addData3 = {
new EnrollmentDataValue("favFruit~lemon","apple") };
userMgr.addEnrollmentData(userId, addData3);

In this example, the ~ is interpreted as a replace. To delete all values from an attribute, treat the multi-valued attribute enrollment data the same as any other normal enrollment data item. An attribute's schema must have been declared as multi-valued before you can use these features. Otherwise, CCM treats it like a normal single-valued attribute.

User Manager Methods

This section lists and briefly describes the methods in User Manager. For more details, refer to the Javadoc.

Note: For related error codes, see Maximum Session Error Codes. For specific error codes, see Communication and Connectivity Error Codes.

Adds new or updates existing enrollment data for the specified user. Accepts enrollment data defined as EnrollmentData and EnrollmentDataValue.

For Java:

Copy 
void addEnrollmentData(UserId userId, EnrollmentData[] enrollmentData)
throws NoSuchUserException, MalformedEnrollmentDataException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

Copy 
void addEnrollmentData(UserId *userId, EnrollmentDataVector *enrollmentData);

Parameters:

  • userId—Unique identifier of the user.

  • enrollmentData[ ]—Array of enrollment data to be added to the specified user.

Exceptions:

  • MalformedEnrollmentDataException— if the enrollment data provided was incorrectly formatted or if the reference is invalid.

  • NoSuchUserException— if the specified user does not exist.

  • SessionException— if there is no valid session (such as session not opened or timed out).

  • ManagementException— if an internal failure occurs.

  • LocalizedRemoteException— (thrown by the Web service layer) only when the most severe, unexpected, SOAP-level failures occur.

See also: Section Behavior with Multi-Valued Attributes.

See closeSession in Common Methods.

Creates a new User object with the information contained in the user parameter. This method makes it possible to instantiate individual users with strongly typed exceptions.

For Java:

Copy 
UserId createUser(User user)
throws MalformedEnrollmentDataException, UserAlreadyExistsException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

Copy 
UserId *createUser(User *user);

Parameters:

  • user—Information that defines the user. The User instance can contain a set of EnrollmentData instances as an initial or complete set of user data. In order for a user creation to succeed, a minimum set of enrollment data must be supplied. Depending on the underlying directory configuration, the following required enrollment data is typically required:

    • ENROLLMENT_DATA_ID_PARENT_DN—Determines the user branch in which the user is created. (This is mandatory for all directory configurations.)

    • givenName—User's first name.

    • sn—User's last name; also known as surname (sn).

    • cn—User's common name (cn).

    • sAMAccountName (for MS AD only)—Directory unique identifier.

    • uid(for Sun Microsystems SunOne directory)—Directory unique identifier. This attribute is required if walletId (the user binding attribute) is configured

Returns:

Unique identifier of the User object that was created.

Exceptions:

  • MalformedEnrollmentDataException— if the enrollment data provided in the user parameter was incorrectly formatted or if the reference is invalid.

  • UserAlreadyExistsException— if the user already exists.

  • SessionException— if there is no valid session (such as session not opened or timed out).

  • ManagementException— if an internal failure occurs.

  • LocalizedRemoteException— (thrown by the Web service layer) only when the most severe, unexpected, SOAP-level failures occur.

Deletes the supplied list of enrollment data from the specified user. For example, in the case of LDAP attributes this method sets the value to empty.

For Java:

Copy 
void deleteEnrollmentData(UserId userId, String[] enrollmentDataIds)
throws NoSuchEnrollmentDataException, NoSuchUserException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

Copy 
void deleteEnrollmentData(UserId *userId, TStringVector *enrollmentDataIds);

Parameters:

  • userId—Unique identifier of the user.

  • enrollmentDataIds—Enrollment data to be deleted.

Exceptions:

  • NoSuchUserException— if the user specified does not exist.

  • NoSuchEnrollmentDataException— if one or more of the IDs does not specify a valid enrollment data item.

  • SessionException— if there is no valid session (such as session not opened or timed out).

  • ManagementException— if an internal failure occurs.

  • LocalizedRemoteException— (thrown by the Web service layer) only when the most severe, unexpected, SOAP-level failures occur.

See also: Section Behavior with Multi-Valued Attributes.

Deletes the specified user. All associated security modules and credentials are revoked in response to this call. Cancels all pending actions, terminates and unbinds the user’s security module(s), and terminates all credentials associated with the terminated security modules.

The following list summarizes its state once this method completes:

  • All devices bound to the user are unbound, including assigned, issued, produced, and invalid devices.

  • All pending requests for this user are deleted.

  • All credentials associated with this the user are revoked.

  • No Wallet should exist for this user.

  • No devices should be bound to this user.

For Java:

Copy 
void deleteUser(UserId userId)
throws NoSuchUserException, InvalidStateException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

Copy 
void deleteUser(UserId *userId);

Parameters:

  • userId —ID of the user to be deleted.

Exceptions:

  • NoSuchUserException— if the specified user does not exist.

  • InvalidStateException— if the user is in a state not compatible with deletion.

  • SessionException— if there is no valid session (such as session not opened or timed out).

  • ManagementException— if an internal failure occurs.

  • LocalizedRemoteException— (thrown by the Web service layer) only when the most severe, unexpected, SOAP-level failures occur.

Returns the list of users that match the supplied criteria. This method performs searches where the search result set size is known to be small by the caller. The maxItems parameter provides a safety limit to ensure large search result sets are not retrieved. The following are some example use cases that can be supported:

  • Get all users with pending actions for their bound wallets.

  • Get all users with no security modules bound to their bound wallets.

  • Determine if a specific user exists.

For Java:

Copy 
User[] findUsers(Criteria[] criteria, String[]
enrollmentDataIds, int maxItems)
throws SessionException, ManagementException, LocalizedRemoteException;

For C++:

Copy 
UserVector *findUsers(CriteriaVector *criteria, TStringVector *enrollmentDataIds, int maxItems);

Parameters:

  • critieria—List of search criteria with which to filter. The criteria that can be specified are listed and described in the following table.

  • maxItems—Maximum number of items to fetch should the search exceed this number. If there is no limit, set this parameter to 0 (zero) or to a negative number.

  • enrollmentDataIds—List of enrollment data identifiers that are to be retrieved for each matching user.

Listing of Search Criteria

Criterion

Criteria Comparison

Possible Values

Description

CRITERIA_ID_ACTION_STATUS

CRITERIA_COMPARISON_EQUAL, CRITERIA_COMPARISON_NOT_EQUAL

Accepted values:

ACTION_STATUS_REQUESTED, ACTION_STATUS_PENDING, ACTION_STATUS_DENIED, ACTION_STATUS_FAILED

Selects users with actions in a particular state.

CRITERIA_ID_ACTION_TYPE

CRITERIA_COMPARISON_EQUAL

ACTION_TYPE_ISSUANCE, ACTION_TYPE_PRODUCE, ACTION_TYPE_POSTISSUANCE, ACTION_TYPE_PINUNLOCK, ACTION_TYPE_CARDLOCK, ACTION_TYPE_CARDUNLOCK

Selects users with actions of a particular type.

CRITERIA_ID_ACTION_APPLICATION_SET

CRITERIA_COMPARISON_EQUAL

String

Selects all users with actions that are associated with a particular application set (aka ActivIdentity ActivID CMS policy ID).

CRITERIA_WALLET_SECURITYMODULE_COUNT

CRITERIA_COMPARISON_EQUAL, CRITERIA_COMPARISON_NOT_EQUAL

Positive integer

Specifies the number of security modules bound to a wallet.

CRITERIA_ID_USERID

CRITERIA_COMPARISON_EQUAL

User ID string

Specifies the identifier of a specific user.

CRITERIA_ID_ENROLLMENT_DATA+attributeName

CRITERIA_COMPARISON_EQUAL

User enrollment data value

Specifies an enrollment data item to use when searching. For example, CRITERIA_ID_ENROLLMENT_DATA must be followed by the attribute name.
Note: If the data set retrieved is large, the time required to assemble the data set might be longer than the current ActivID CMS LDAP request timeout configuration (which is defined by LDAP.RequestTimeout). As a result, this value might have to be increased.

Returns:

  • The list of users matching the supplied criteria.

Exceptions:

  • SessionException— if there is no valid session (such as session not opened or timed out).

  • ManagementException— if an internal failure occurs.

  • LocalizedRemoteException— (thrown by the Web service layer) only when the most severe, unexpected, SOAP-level failures occur.

Returns the list of user IDs for those users that match the supplied criteria. This method performs searches where the search result set size is known to be small by the caller. If the result set is large or unknown, consider using:

Copy 
findUsersInit(Criteria[ ])/findUserIdsFetch(String, boolean, or int)

For Java:

Copy 
UserId[] findUserIds(Criteria[] criteria, int maxItems) 
throws ManagementException, SessionException, LocalizedRemoteException;

Parameters:

  • criteria—List of search criteria with which to filter. This parameter can take the same values as the criteria parameter of findUsers.

  • maxItems—Maximum number of items to fetch if the search exceeds this number. If there is no limit, you can set this parameter to 0 (zero) or to a negative number. If, as the result of an LDAP search (such as findUser), the number of results matching the query exceeds the maxItems specified, this causes an exception to be thrown— SizeLimitPeopleException. For more information, refer to the JDK documentation:

    • http://docs.oracle.com/javase/jndi/tutorial/basics/directory/countlimit.html

When this occurs, to receive a result set you must increase the value of maxItems or make your query more specific. Also note that the CCM API times out after 60 seconds if the query is taking too long.

Returns:

  • List of identifiers of users matching the supplied criteria.

Exceptions:

  • SessionException— if there is no valid session (such as session not opened or timed out).

  • ManagementException— if an internal failure occurs.

  • LocalizedRemoteException— (thrown by the Web service layer) only when the most severe, unexpected, SOAP-level failures occur.

Returns the user that is bound to the wallet containing the specified security module. Each user has exactly one wallet, and this wallet has one or more SecurityModule(s). However, in most cases, the user has only one SecurityModule, unless they have a temporary device.

For Java:

Copy 
UserId getBoundUserFromSM(SecurityModuleId securityModuleId)
throws NoSuchSecurityModuleException, NoSuchBindingException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

Copy 
UserId *getBoundUserFromSM(SecurityModuleId *smId);

Parameters:

  • \securityModuleId—unique identifier of the security module.

Returns:

  • The user bound (using a wallet) to the supplied security module.

Exceptions:

  • NoSuchBindingException— if the specified security module is not bound to any user.

  • NoSuchSecurityModuleException— if the specified security module is not found.

  • SessionException— if there is no valid session (such as session not opened or timed out).

  • ManagementException— if an internal failure occurs.

  • LocalizedRemoteException— (thrown by the Web service layer) only when the most severe, unexpected, SOAP-level failures occur.

Returns the user bound to the specified wallet.

For Java:

Copy 
UserId getBoundUserFromWallet(WalletId walletId)
throws NoSuchWalletException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

Copy 
UserId *getBoundUserFromWallet(WalletId *walletId);

Parameters:

  • walletId—ID of the wallet to be retrieved.

Returns:

The UserId of the user bound to the specified wallet.

Exceptions:

  • NoSuchWalletException— if the wallet ID specified does not identify a valid wallet.

  • SessionException— if there is no valid session (such as session not opened or timed out).

  • ManagementException— if an internal failure occurs.

  • LocalizedRemoteException— (thrown by the Web service layer) only when the most severe, unexpected, SOAP-level failures occur.

Returns the list of specified enrollment data for the supplied user.

For Java:

Copy 
EnrollmentData[] getEnrollmentData(UserId userId, String[] enrollmentDataIds)
throws NoSuchUserException, NoSuchEnrollmentDataException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

Copy 
EnrollmentDataVector getEnrollmentData(UserId *userId, TStringVector *enrollmentDataIds);

Parameters:

  • userId—Unique indentifier of the user.

  • enrollmentDataIds—Enrollment data to be retrieved.

Returns:

  • The list of specified enrollment data for the supplied user.

Exceptions:

  • NoSuchUserException— if the specified user does not exist.

  • NoSuchEnrollmentDataException— if one or more of the IDs does not specify a valid enrollment data item.

  • SessionException— if there is no valid session (such as session not opened or timed out).

  • ManagementException— if an internal failure occurs.

  • LocalizedRemoteException— (thrown by the Web service layer) only when the most severe, unexpected, SOAP-level failures occur.

See also: Section Behavior with Multi-Valued Attributes.

See getSessionInfo in Common Methods.

Returns the list of selected users and optionally some of their enrollment data (depending on the list of userIds and enrollmentDataIds provided as parameters).

For Java:

Copy 
User[] getUsers(UserId[] userIds, String[]
enrollmentDataIds)
throws NoSuchUserException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

Copy 
UserVector *getUsers(UserIdVector *userIds, TStringVector *enrollmentDataIds);

Parameters:

  • userIds—Identifiers of the users to be retrieved.

  • enrollmentDataIds—List of enrollment data identifiers that are to be retrieved for each user.

Returns:

The list of specified users.

Exceptions:

  • NoSuchUserException— if one or more of the users specified does not exist.

  • SessionException— if there is no valid session (such as session not opened or timed out).

  • ManagementException— if an internal failure occurs.

  • LocalizedRemoteException— (thrown by the Web service layer) only when the most severe, unexpected, SOAP-level failures occur.

See getVersion in Common Methods.

See isSessionOpen in Common Methods.

See openSession in Common Methods.

Updates the DN (Distinguished Name) of the user to the new DN in the Directory.

The following list summarizes the prerequisites of this call:

For Java:

Copy 
void updateDn(UserId userId) 
throws NoSuchUserException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

Copy 
void updateDn(UserId *userId);

Parameters:

  • userId —ID of the user to be deleted.

Exceptions:

  • NoSuchUserException— if the specified user does not exist.

  • SessionException— if there is no valid session (such as session not opened or timed out). For related error codes, see Maximum Session Error Codes.

  • ManagementException— if an internal failure occurs.

  • LocalizedRemoteException—thrown by the Web service layer only when the most severe, unexpected, SOAP-level failures occur. For related error codes, see Communication and Connectivity Error Codes.