Using the Service Provider Interface

This section provides a series of pseudo-code examples that outline the way that the service provider interface (SPI) entry points are intended to be called by the ActivID CMS infrastructure.

The pseudo-code samples provide a perspective illustrating some of the example usage patterns that the Credential provider developers can expect to see.

Pseudo-Code: Provider Initialization

The following example illustrates how the ActivID CMS infrastructure initializes a CredentialProvider. All of the CredentialProvider implementation classes should implement this interface, not the more general Provider interface.

Pseudo-Code Example 1:

How Infrastructure Initializes a CredentialProvider

Copy

// List the External Operation types that can be carried// out by the CredentialProvider and use this information
// as part of a CredentialProvider installation sanity
//    check:
externalOpTypes = prov. getSupportedExternalOperatioTypes()
// Get default / template configuration data
provConfigTemp = prov. getProviderConfigurationTemplate()
// Gather input from UI and produce Configuration
Configuration provConfig = new Configuration() provConfig.setEntries(provEntries)
// Persist configuration for later use
// Globally initialize provider with provider
configuration prov.initialize(provConfig)

Once CredentialProvider configuration information has been collected, only the last line of the above example is executed when ActivID CMS starts up.

Pseudo-Code: Provider Context Initialization

The following example illustrates how the Credential Manager infrastructure initializes a CredentialProviderContext. All Credential Provider Context implementation classes should implement the CredentialProviderContext interface, not the more general ProviderContext interface.

Pseudo-Code Example 2:

How the Credential Manager Infrastructure Initializes a Credential Provider

Copy

// Get default / template configurations for initializing
// provider contexts
instConfigTemps = prov.getContextConfigurationTemplates()
// Gather input from UI and produce Configuration Configuration instConfig = new Configuration(); instConfig.setEntries(instEntries);
// Persist configuration for later use
// Initialize provider context with a context-specific
// configuration
context = prov.initializeContext(instConfig, providerId)
// Ensure that the provider is functioning normally
context.validate()

The Credential Provider configuration information is collected once. After that, only the last two lines of the example above are executed when ActivID CMS starts up.

Pseudo-Code: Credential Profile Preparation

Once the CredentialProviderContext is initialized, the ActivID CMS Operator can begin creating the CredentialProfiles using CredentialProviderContext. The following example illustrates the process by which a CredentialProfile is created.

Pseudo-Code Example 3:

How a CredentialProfile is Created

Copy

// Retrieve the set of default supported
// CredentialProfiles
// Note: these profiles may or may not be complete
// (that is, they may be partial templates)
credProfileTemplates = context.getProfileTemplates()
// Use profile templates to create externally managed
// CredentialProfiles for later use by gathering input
// from the UI.
profile = credProfileTemplates[0].newProfileInstance() entryTemps = credProfileTemplates[0].getEntries()
// Eval entry templates and populate profile with new
// entries formed from the templates
// Flag dynamic entries to be populated at credential
// provisioning time
Profile.setEntries(entries)
// Store profile

Pseudo-Code: Credential Creation

The following example illustrates how an external operation process is used during Credential creation.

Pseudo-Code Example 4:

How an External Operation Process is Used during Credential Creation

Copy

// Select credential profile
credProfile = ...
// Evaluate selected credential profile
entries = credProfile.getEntries()
// Evaluate dynamic entries and set resulting name/value
// pairs in the selected credential profile
credProfile.setEntries(entries)
// Create the base credential structure by passing the
// profile information (value copy, not reference)
txId = createCredential(credProfile)
// Test to see if there are external operations pending
// for the new transaction.
// If no external processing is required, flow terminates
// at top of the loop below.
// Retrieve initial set of pending external operations 
externalOps = getNextExternalOperations(txId, NULL); 
while (externalOps) {
for (externalOp in externalOps) {
// Externally process externalOp and update with result
externalOp.setResponseParameters(someDataFromProcessing)
}
// Update transaction with results
// Retrieve next set of pending external operations
externalOps = getNextExternalOperations(txId, externalOps);
}
// Commit transaction AND retrieve newly formed
// credential
credentials = commitCredentialTransaction(txId)

The initial getNextExternalOperations() call may return no external operations, and therefore the while loop may never be called.

Pseudo-Code: Credential Update

The following example illustrates how the infrastructure interacts with a CredentialProvider in order to update a Credential.

Pseudo-Code Example 5:

How a Credential is Updated

Copy

// Decide to do an update on an existing credential;
// Retrieve profile and evaluate dynamic entries
profileId = credential.getProfileId()
// Retrieve profile using profileId
credProfile = ...
// Evaluate selected credential profile
entries = credProfile.getEntries()
// Evaluate dynamic entries and set the resulting
// name/value pairs in the selected credential profile
credProfile.setEntries(entries)
// Pass the credential profile along with the credential
// and the desired update action
txId = updateCredential(credential, "pki.renew”, credProfile)
// Test to see if there are external operations pending
// for the new transaction. If no external processing is
// required then flow terminates at top of loop below.
// Retrieve initial set of pending external operations 
externalOps = getNextExternalOperations(txId, NULL); 
while (externalOps) {
for (externalOp in externalOps) {
// Externally process externalOp and update with
// result
externalOp.setResponseParameters(someDataFrom Processing)
}
// Update transaction with results
// Retrieve next set of pending external operations
externalOps = getNextExternalOperations(txId, externalOps);
}
// Commit transaction AND retrieve updated credential
credentials = commitCredentialTransaction(txId)

Pseudo-Code: Credential Suspension/Resumption/Revocation/Recovery

The following example illustrates how the infrastructure interacts with a CredentialProvider to change the state of a Credential.

Pseudo-Code Example 6:

How Infrastructure Interacts with Credential Provider in Carrying Out Credential State Changes

Copy

txId = performProcess(credential, “revoke”, comment)
// Are External Operations pending for the new
// transaction?
// If no external processing is required, flow terminates
// at the top of the loop.
// Retrieve initial set of pending external operations 
externalOps = getNextExternalOperations(txId, NULL);
 while (externalOps) {
for (externalOp in externalOps) {
// Externally process externalOp and update with
// result
externalOp.setResponseParameters(someDataFrom Processing)
}
// Update transaction with results
// Retrieve next set of pending external operations
externalOps = getNextExternalOperations(txId, externalOps);
}
// Commit transaction AND retrieve updated credential for potential use
credentials = commitCredentialTransaction(txId)

Resulting Credential Object

Each of the previous examples in this section results in returning a Credential (as illustrated in the following example).

Pseudo-Code Example 7:

Results of External Operation(s)

Copy

// Commit transaction AND retrieve credential for
// potential use
credentials = commitCredentialTransaction(txId)

Following the completion of a credential management operation that creates or modifies the Credential, the resulting Credential(s) are returned. Whatever happens to the Credential(s), and more importantly when, is not a part of the ActivID CMS infrastructure or CredentialProvider contract. For example, the workflow may create several Credentials before collecting them together and injecting them into a single application.