CredentialProvider Interface Classes

This method returns the ProviderContext’s unique identifier.

This method is called prior to shutdown of the ProviderContext and allows the ProviderContext to perform any breakdown activities required.

This method performs a validation check on the ProviderContext to ensure it has been initialized and is functioning correctly.

Credential[] commitCredentialTransaction(TransactionId txId)

Commits a credential transaction to complete the creation or update of the proto-Credential/Credential associated with a specified transaction. The commitCredentialTransaction() must return a Credential object for each credential.

This Credential object must contain all of the CredentialElements that are required for the provider to uniquely identify and manage the credential during subsequent calls to:

• updateCredential
• performProcess

• deleteCredential

The CredentialElements of a given Credential may be modified by the Provider during calls to updateCredential() or performProcess(). The Credential Provider must also set the ID of the Credential Profile for each Credential, along with a string description that is displayed in the ActivID CMS graphical user interface (GUI).

The Provider must not modify the Credential ID of a Credential. It is the responsibility of ActivID CMS to create and manage the Credential ID for each Credential. All PKI credential providers must return Credentials that, at a minimum, contain a CredentialElement with the complete PKI certificate.

A CredentialElement must meet the following prerequisites:

• Be named com.activcard.provider.cred.pki.certificate

• Possess type 1.2.840.113549.1.9.22 (meaning, an X.509 certificate)

• Contain an X.509 certificate represented as a base64 encoded string

TransactionId createCredential(CredentialProfile credProfile

Creates (or starts the creation workflow of) a new Credential using the supplied CredentialProfile. Returns a transaction identifier that is used as input for any potential further steps required for Credential creation. The transaction identifier returned must have the default type: Transaction.

This entry point may result in the following processes:

• To retrieve External Operation(s) by calling:

  Copy

  getNextExternalOperations(TransactionId, ExternalOperation[])

• To externally process the External Operation(s)

• To return the results to the Credential Provider by calling:

  Copy

  getNextExternalOperations(TransactionId, ExternalOperation[])

If no External Operations are pending, the final unique credential can be retrieved by calling commitCredentialTransaction(TransactionId). The CredentialID of the retrieved Credential must be null (it is the responsibility of ActivID CMS to set the CredentialID).

TransactionId createCredentials(CredentialProfile[] credProfiles)

Creates (or starts the creation workflow of) a set of new Credentials using a batch process using the supplied CredentialProfiles. Returns a transaction identifier which is used as input to any potential further steps that may be required for Credential creation. The transaction identifier returned must have the default type: Transaction. This entry point may result in the following processes:

• To retrieve External Operation(s) by calling:

  Copy

  getNextExternalOperations(TransactionId, ExternalOperation[])

• To externally process the External Operation(s)

• To return the results to the Credential Provider by calling:

  Copy

  getNextExternalOperations(TransactionId, ExternalOperation[])

If no External Operations are pending, the final unique Credentials can be retrieved by calling commitCredentialTransaction(TransactionId). The CredentialID of each of the retrieved credentials must be null. It is the responsibility of ActivID CMS to set the CredentialIDs.

Due to this method’s batch nature, it assumes an all or nothing (transactional) approach to credential management. Any failure means the entire transaction fails and is rolled back. It is the Credential Provider’s responsibility to enforce the contract.

TransactionId deleteCredential(Credential credential)

Deletes the specified Credential, completing or terminating its lifecycle and returning a transaction identifier used as input for any potential further steps that may be required for Credential deletion. The transaction identifier that is returned must have the default type: Transaction. This entry point may result in the following processes:

• To retrieve External Operation(s) by calling:

  Copy

  getNextExternalOperations(TransactionId, ExternalOperation[])

• To externally process the External Operation(s)

• To return the results to the Credential Provider by calling:

  Copy

  getNextExternalOperations(TransactionId, ExternalOperation[])

If no External Operations are pending, the final unique credential can be retrieved by calling commitCredentialTransaction(TransactionId).

TransactionId deleteCredentials(Credential[] credentials)

Deletes the specified Credential(s), completing or terminating their lifecycles in batch and returning a transaction identifier used as input to any potential further steps required for Credential deletion. The transaction identifier returned must have the default type: Transaction. This entry point may result in the following processes:

• To retrieve External Operation(s) by calling:

  Copy

  getNextExternalOperations(TransactionId, ExternalOperation[])

• To externally process the External Operation(s)

• To return the results to the Credential Provider by calling:

  Copy

  getNextExternalOperations(TransactionId, ExternalOperation[])

If no External Operations are pending, the final unique credential can be retrieved by calling commitCredentialTransaction(TransactionId). Due to this method’s batch nature, it assumes an all or nothing (transactional) approach to credential management.

Any failure means the entire transaction fails and is rolled back. It is the Credential Provider’s responsibility to enforce the contract.

java.lang.String[] getActionTypes(Credential credential) throws NoSuchCredentialException, ProviderException;

Returns:

Returns the list of update action types supported for the specified Credential.

Capabilities getCapabilities()

Returns the Credential Provider's capability set.

java.lang.String getCredentialStatus(Credential credential)

Returns:

Returns the status of the specified Credential. Credential providers should return one of the following valid status values:

• Active—Indicates that the credential is usable and active

• Hold—Indicates that the credential has been suspended and is on hold

• Revoked— Indicates that the credential has been revoked and is permanently unusable

ExternalOperation[] getExternalOperations(String transactionType, CredentialProfile credProfile) throws VolatileTransactionException, ProviderException;

Returns:

Returns the list of expected ExternalOperations that ActivID CMS must execute for the specified transaction type based on the supplied credential profile.

ExternalOperation[] getNextExternalOperations(TransactionId txId, ExternalOperation[] completedExternalOps)

Retrieves pending external operation(s) for the specified Credential transaction. These operations are used to update credentials with the data resulting from external processing.

The pending external operation(s) are generally formed where Credential creation, updating, or processing involves multiple steps that require interaction with an entity external to the Credential Provider.

Initial pending external operations can be queued or requested as a result of calling one of the following entry points:

• createCredential(CredentialProfile)

• deleteCredential(Credential)

• performProcess(Credential, String, String)

• updateCredential(Credential, String, CredentialProfile)

Once external processing is complete, the updated, processed external operation(s) is/are returned to the Credential Provider to advance or complete the workflow using this same entry point. This update may itself cause further pending external operations to be queued or requested.

The passed-in completed External Operation(s) are the results of processing External Operation(s) that were returned from a previous call to getNextExternalOperations().

Returns:

Returns zero or more generated External Operation(s) for the specified transaction.

java.lang.String[] getProcessTypes(Credential credential)

Returns:

Returns the list of process types supported for the specified Credential.

CredentialProfileTemplate[] getProfileTemplates()

Returns:

Returns the set of base or default profile templates specific to this CredentialProviderContext.

CredentialId[] importCredential(CredentialProfile credProfile, CredentialElement[] credEls) throws MalformedDataException, ProviderException;

Imports a new Credential using the supplied CredentialElements and a CredentialProfile. The provider may transform, add to, or delete from the input credential elements to arrive at the format the provider requires to assume management of the credential. This final format is what is returned in the output Credential.

Returns:

The resulting Credential.

Exceptions:

• MalformedDataException if the input data was malformed

• ProviderException if an internal failure occurs

TransactionId performProcess(Credential credential, java.lang.String process, java.lang.String comment)

Performs a lifecycle process or initiates a workflow for the process, for the specified Credential. The types of processes are associated with the Credential life cycle rather than its content. For example, they might be the following types:

• Suspend

• Resume

• Revoke

Returns:

Returns a transaction identifier that is used as input to any potential further steps required to complete or advance this process. The transaction identifier returned must have the default type: Transaction. This entry point may result in the following processes:

• To retrieve External Operation(s) by calling:

  Copy

  getNextExternalOperations(TransactionId, ExternalOperation[])

• To externally process the External Operation(s)

• To return the results to the Credential Provider by calling:

  Copy

  getNextExternalOperations(TransactionId, ExternalOperation[])

If no External Operations are pending, the final unique credential can be retrieved by calling commitCredentialTransaction(TransactionId).

TransactionId performProcesses(Credential[] credentials, java.lang.String process, java.lang.String comment)

Performs a lifecycle process or initiates a workflow for the process in batch for each specified Credential. Returns a transaction identifier that is used as input to any potential further steps required to complete or advance this process. The transaction identifier returned must have the default type: Transaction. This entry point may result in the following processes:

• To retrieve External Operation(s) by calling:

  Copy

  getNextExternalOperations(TransactionId, ExternalOperation[])

• To externally process the External Operation(s)

• To return the results to the Credential Provider by calling:

  Copy

  getNextExternalOperations(TransactionId, ExternalOperation[])

If no External Operations are pending, the final unique Credentials can be retrieved by calling commitCredentialTransaction(TransactionId). Due to this method’s batch nature, it assumes an all or nothing (transactional) approach to credential management. Any failure means the entire transaction fails and is rolled back. It is the Credential Provider’s responsibility to enforce the contract.

void rollbackCredentialTransaction(TransactionId txId)

Rolls back a credential transaction to revert the creation or update of the proto-Credential/Credential associated with the specified transaction.

TransactionId updateCredential(Credential Credential, java.lang.String action, CredentialProfile credProfile)

Updates an existing Credential with the supplied CredentialProfile, according to the requested action. Returns a transaction identifier that is used as input to any potential further steps required for Credential update. The transaction identifier returned must have the default type: Transaction.

This entry point may result in the following processes:

• To retrieve External Operation(s) by calling:

  Copy

  getNextExternalOperations(TransactionId, ExternalOperation[])

• To externally process the External Operation(s)

• To return the results to the Credential Provider by calling:

  Copy

  getNextExternalOperations(TransactionId, ExternalOperation[])

TransactionId updateCredentials(java.lang.String action, CredentialUpdateRequest[] requests)

Updates an existing Credential in batch with the specified credential requests, according to the requested action.

A CredentialUpdateRequest is a comprised of:

• A Credential to be updated

• A Credential Profile from which the Credential is to be updated

Returns:

Returns a transaction identifier that is used as input to any potential further steps required for Credential update. The transaction identifier returned must have the default type: Transaction. This entry point may result in the following processes:

• To retrieve External Operation(s) by calling:

  Copy

  getNextExternalOperations(TransactionId, ExternalOperation[])

• To externally process the External Operation(s)

• To return the results to the Credential Provider by calling:

  Copy

  getNextExternalOperations(TransactionId, ExternalOperation[])

If no External Operations are pending, the final unique credential can be retrieved by calling commitCredentialTransaction(TransactionId).

Due to this method’s batch nature, it assumes an all or nothing (transactional) approach to credential management. Any failure means the entire transaction fails and is rolled back. It is the Credential Provider’s responsibility to enforce the contract.