Developing, Installing, and Initializing a Credential Provider in an ActivID Credential Management System

The topics in this section address key tasks involved in developing, installing, and initializing a Credential Provider in ActivID CMS.

Guidelines for Developing a Credential Provider

This section briefly lists a set of recommended guidelines you can use for developing a Credential Provider. The following list illustrates some typical steps that you can follow when developing a Credential Provider:

1. Define the configuration needed by the Credential Provider.

2. Determine which data is global (meaning that it spans contexts) and which data is more context-specific.

3. Define the capabilities of the Credential Provider.

4. Define the internal workflows (in terms of specific steps) for each of the Credential Management operations; for example, operations that create, update, perform a process, or delete.

5. Determine if internal workflows need external interaction (typically with security module) and what are the quantity needs required for any external interaction.

6. Define the credential creation types and configuration needs to determine the structure of the credential profile template(s).

7. Determine if multiple credential types can or cannot share a single credential profile template and structure accordingly.

8. Design internal mechanisms, resources, and/or any services required by the Credential Provider and determine what additional configuration may be needed accordingly.

9. Build a Credential Provider based upon the results found in the previous steps in this list.

Prior to attempting to install and configure a new Credential Provider, you must first complete all of the prerequisite interactions that are listed in the following three Credential Provider tables.

Initializing a Single CredentialProviderContext

The first of the three tables defines the interactions between the ActivID CMS Operator, the ActivID CMS server, and the Credential Provider. The interactions described in the table are prerequisites that you need to complete to perform the following tasks:

• Initialize a single CredentialProviderContext

• Start the process of installing a Credential Provider

Initializing a Single CredentialProviderContext

ActivID CMS Operator	ActivID CMS Server	Credential Provider
The following interactions are associated with initializing a single CredentialProviderContext prior to installing a Credential Provider:
Presents Credential Provider install.jar file for installation.
	Accepts a vendor's Credential Provider installation component from the ActivID CMS Operator.
	Stores the completed Configuration in an ActivID CMS repository.
	Initializes the Credential Provider using the newly created Configuration.
		Performs any global set up as required prior to initializing context.
Requests the creation of an ActivID CMS repository (CredentialProviderContext).
	Requests the ConfigurationTemplates from the Credential Provider.
		Returns a set of one or more of the ConfigurationTemplates intended for configuring    CredentialProviderContexts (which may be constructed at runtime or static).
	Presents the appropriate ConfigurationTemplate to the operator using the GUI.
Supplies the information as prompted.
	Validates the operator's responses against the syntax specified in the ConfigurationTemplate.
	Stores the completed Configuration in an ActivID CMS repository.
	Initializes the CredentialProviderContext using the newly created Configuration.
		The CredentialProviderContext performs all set up required to start managing Credentials.

Preparing a Credential Profile

The second of the three tables includes interactions between the ActivID CMS Operator, ActivID CMS, and the Credential Provider that are involved in preparing a Credential Profile.

Preparing a Credential Profile

ActivID CMS Operator	ActivID CMS Server	Credential Provider
The following interactions are associated with preparing a Credential Profile:
Requests the issuance of a device with a device policy application drawing its configuration from a Credential Profile.
	Retrieves the relevant CredentialProfile.
	Requests CredentialProviderContext create a Credential using the selected CredentialProfile.
		Returns a set of (one or more) CredentialProfileTemplates (this may be constructed at runtime or be static).
	Presents CredentialProfileTemplate that was chosen to the operator using the GUI.
Supplies the information requested.
	Validates the operator's responses against the CredentialProfileTemplate.
	Stores the completed CredentialProfile in an ActivID CMS repository.
Note: Once this sequence is completed, a single CredentialProfile has been created and the configuration steps required to start the process of creating and managing credentials has been completed.

Creating a Credential

The third of the three tables includes interactions between the ActivID CMS Operator, ActivID CMS, and the Credential Provider that are involved in creating credentials.

Creating a Credential

ActivID CMS Operator	ActivID CMS Server	Credential Provider
The following interactions are associated with Credential creation:
Request the configuration of a Device Policy's Application (CredentialProfile).
	Retrieves the relevant CredentialProfile.
	Requests CredentialProviderContext create a Credential using the selected CredentialProfile.
		Initiates the Credential creation transaction.

Installing a Credential Provider

To install a Credential Provider you create using the Credential Provider SPI A Service Provider Interface (SPI) consists of a set of constant definitions and method declarations without implementations and intended to be called or used in a pre-determined generic manner with a set of outputs that meet pre-determined abstract rules and expectations. into ActivID CMS, complete the following steps:

1. Edit the credential provider initialization properties file (credProviders.properties) by completing the following tasks:

   Copy

   %PROGRAMDATA%/HID Global/Credential Management System/Shared Files/credProviders.properties

   • Open the properties file in a text editor.

   • Append the name of the new credential provider to the end of the credential.providers line (as shown in the following example):

     Copy

     credential.providers=NewProviderName

   Note: NewProviderName is the friendly name of the new Credential Provider that is to be installed. Any entries and values added to the credProviders.properties file are used in initializing the new Credential Provider.

   • Append the following lines to the file:

     Copy

     credential.provider.NewProviderName.description=your_description
     credential.provider.NewProviderName.class=your_ProviderClass_name_including_package
     credential.provider.NewProviderName.entries= your_entry1, your_entry2, ...
     credential.provider.NewProviderName.your_entry1= value_of_your_entry1
     credential.provider.NewProviderName.your_entry2= value_of_your_entry2

   • Save the file.

2. Create any directories that the new Credential Provider requires under the CMS_install_dir.

3. Copy the new Credential Provider .jar files to the %PROGRAMDATA%\HID Global\Credential Management System\custom.war\WEB-INF\lib directory.

4. Restart the ActivID CMS server.

5. Once the ActivID CMS server has been restarted, the new Credential Provider should be available.

To verify that the newly-installed Credential Provider is available, perform the following tasks:

• Log into ActivID CMS.

• Click the Configuration tab.

• Click Add Certificate Authority to display the Certificate Authority Creation window (Verifying the Credential Provider).

The newly added provider type should display in the Provider: pull-down menu (in this example, it is Provider XYZ).

Verifying the Credential Provider

Adding the Credential Provider Context

To add a Credential Provider context, complete the following steps:

1. Log into ActivID CMS.

2. Click the Configuration tab.

3. Click Add Certificate Authority to display the Certificate Authority Creation window (Adding a Certificate Authority). The newly added provider type should display in the Provider: pull-down menu (in this example, it is Provider XYZ).

   Adding a Certificate Authority

   

4. Click to select one of the templates in the Template: pull-down menu and click Submit. A window similar to (Configuring the Credential Provider) displays.

   The window illustrated in Configuring the Credential Provider is only an example.

   All graphical user interface (GUI) elements below the Name: text box are dynamically rendered from the template, which is both provider-specific and template-specific, and is driven by the selected configuration template.

   Configuring the Credential Provider

   

5. Enter the necessary information in the other text boxes, and click Create to complete the configuration.

Using the Credential Provider Context

Creating Credential Profiles and using the Credential Provider Context are driven using the Policy menu located under the Configuration tab. The need for Credential configuration information is created when a PKI application is added to a device policy. Credential Profiles are the provider-level technical manifestations of this PKI application configuration information.

The following steps in this section only deal with the configuration items concerned with the Credential Provider, Credential Provider Contexts, and Credential Profiles. See the ActivID CMS documentation that accompanies this release for specifics and details about creating policy and other items. Where applicable, any correlation between GUI concepts and technical provider-level concepts are made by listing the GUI concept with the corresponding provider concept in parentheses.

To configure a PKI Application, complete the following steps:

1. Click to select the desired Credential Provider.

2. Click to select the relevant CA (context) from the newly populated list of Certificate Authorities (Credential Provider Contexts).

3. Click to select the relevant template from the newly populated Application Template list (Credential Profile Templates).

4. Click Submit to proceed after all other selections have been made.

Migrating from Credential Provider SPI 1.x to 1.5 (ActivID Credential Management System 4.x to 5.0 / 5.1)

The ActivID CMS 5.0 release introduced minor modifications to the Credential Provider SPI A Service Provider Interface (SPI) consists of a set of constant definitions and method declarations without implementations and intended to be called or used in a pre-determined generic manner with a set of outputs that meet pre-determined abstract rules and expectations., with the resulting version number of the Credential Provider SPI incremented to 1.4. The modifications made to the Credential Provider SPI 1.4 include the following:

• Added getDeviceTypes() method to the Capabilities class

• Added setDeviceTypes() method to the Capabilities class

For any Credential Provider reporting version 1.2 or below, ActivID CMS does not attempt to use any of the new methods introduced in Credential Provider SPI version 1.4. Only Credential Providers that explicitly implemented the new features available in the Credential Provider SPI 1.4 are required to explicitly set their version to 1.4.

The ActivID CMS 5.0.1 release introduced minor modifications to the Credential Provider SPI, with the resulting version number of the Credential Provider SPI incremented to 1.5. The modifications made to the Credential Provider SPI 1.5 include the following:

• Added isDerived() method to the Capabilities class

• Added setDerived() method to the Capabilities class

Credential Provider SPI 1.5 is fully backwards compatible with Credential Provider SPI 1.4.

For any Credential Provider reporting version 1.4 or below, ActivID CMS does not attempt to use any of the new methods introduced in Credential Provider SPI version 1.5. Only Credential Providers that explicitly implemented the new features available in the Credential Provider SPI 1.5 are required to explicitly set their version to 1.5.

ActivID CMS 5.0.2 and subsequent versions did not introduce any modifications to the Credential Provider SPI, except to add new device types. The Credential Provider SPI version is still 1.5.

In the current version of ActivID CMS, the list of known device types is: OP_2.0, PKCS_11, MOBILE, MSC, VSC, YK.