This topic describes how you can create, approve, and execute a request using the Provision APIs in Forefront Identity Manager Certificate Management (FIM CM). It also discusses the life cycle of a request.

Creating an Enrollment Request

The following procedure details the steps that you would ordinarily perform to create enrollment requests through the FIM CM Provision API.

  1. Use the FindOperations class to retrieve a list of profile templates available for this user, and select the appropriate profile template. You can also specify a particular profile template.

  2. Create required data collection items to correspond to the data collection requirements as laid out in the specific Profile Template Policy.

  3. Create enrollment request using the InitiateEnroll method.

The following example demonstrates these steps.

  Copy Code 
// Initiate Request for a specific Profile Template with Guid parameter
// profileTemplateUuid, with targetUserUuid being the GUID in Active 
// Directory of the target user

ProfileTemplate profileTemplate = FindOperations.GetProfileTemplate(profileTemplateUuid);
List<Microsoft.Clm.Shared.Requests.DataCollectionItem> dataCollectionList = new List<Microsoft.Clm.Shared.Requests.DataCollectionItem>();
dataCollectionList.Add(new Microsoft.Clm.Shared.Requests.DataCollectionItem("TelephoneNumber", "(555) 555-5555"));
Microsoft.Clm.Shared.Requests.DataCollection dataCollection = new Microsoft.Clm.Shared.Requests.DataCollection(dataCollectionList);
Request enrollRequest= RequestOperations.InitiateEnroll(profileTemplateUuid,dataCollection, targetUserUuid,"comment",0);

Note You can use the same general procedure to create other request types, for example Recover, Unblock, Offline Unblock, and Retire.

Approving a Request

The following procedure details steps that you would ordinarily perform to approve a request.

  1. Find a specific request to approve. You can use the FindOperations class to search for specific requests based on factors such as request status, target user, or request type.

  2. Create required data collection items for this policy. If you are not sure of what data collection items are required, you can use the ProfileTemplate class to retrieve details from the policy.

  3. Perform additional operations required by your application to approve the request.

  4. Call Approve to approve the request.

The following example demonstrates these steps.

  Copy Code 
// Approve request for the request GUID specified by requestUuid 
Request request = FindOperations.GetRequest(requestUuid);
List<Microsoft.Clm.Shared.Requests.DataCollectionItem> dataCollectionList = new List<Microsoft.Clm.Shared.Requests.DataCollectionItem>();
dataCollectionList.Add(new Microsoft.Clm.Shared.Requests.DataCollectionItem("TelephoneNumber", "(555) 555-5555"));
Microsoft.Clm.Shared.Requests.DataCollection dataCollection = new Microsoft.Clm.Shared.Requests.DataCollection(dataCollectionList);
Request approvedRequest = RequestOperations.Approve(request, dataCollection, “Approve Comment”);

Performing the Request

The following procedure details steps that you would ordinarily perform to run a request after it has been approved.

  1. Find a specific request to execute. You can use the FindOperations class to search for specific requests based on factors such as request status, target user, or request type.

  2. After you have selected the request, load the request details using the request’s unique identifier.

  3. If this is a new Smart Card Enroll or Smart Card Recover request, use the CreateSmartcard method.

  4. For all certificate templates in the Profile Template that require client-side requests, generate the Certificate Requests (CMC Requests) using your own code implementation.

  5. Run the Enroll Request by calling the Enroll method, which returns a collection of certificate responses (either PKCS #7 or PFX, or a mix of both, depending on Profile Template settings). You can then either install these responses onto the smart card through custom code, or install the responses into the certificate store of the user (for using without smart card).

  6. Perform additional smart card processing as required by your application. This can include storing additional smart card data, making the smart card available for physical access, or any other operation your application requires.

  7. Mark request as completed by calling Complete.

The following example demonstrates these steps.

  Copy Code 
//Execute request for the request GUID specified by requestUuid. 
//'cardSerialNumber' parameter: Smart card serial number 
//'middleware' parameter : Middleware string
//'atr' parameter : Answer to Reset of the card (ATR)
  Copy Code 
Request request = FindOperations.GetRequest(requestUuid);
Microsoft.Clm.Shared.Smartcards.Smartcard smartCard;
//Create and Assign a Smart Card
smartCard = RequestOperations.CreateSmartcard(cardSerialNumber, middleware, atr, request);   

//Retrieve the Profile Template to determine Certificate Template List
ProfileTemplate profileTemplate = FindOperations.GetProfileTemplate(request.ProfileTemplateUuid);

//Implement your own GetCertificateRequests method to generate 
//certificate requests as needed
ReadOnlyCollection<CertificateRequest> certificateRequests = GetCertificateRequests(profileTemplate);

ReadOnlyCollection<Microsoft.Clm.Shared.Certificates.Certificate> results = ExecuteOperations.Enroll(request.Uuid, certificateRequests, "pfxPassword", "some comment");

//Install the responses as necessary

//Mark the request as completed
request = ExecuteOperations.Complete(request.Uuid);

Request Lifecycle

A request moves between different states as it passes through its life cycle. The operations you perform on a request depend on the request’s current state. In addition, a request can only be executed when it is in an approved state.

The states that can exist for a request in a software profile template are as follows:

  • Pending: If one or more approvals are required, a request is in a pending state after it is created. If no approvals are required, the request can transition to an approved state.

  • Canceled: Once a request is in a pending state, the person who initiated or created the request can decide to cancel the request. Once canceled, the request is in a canceled state.

  • Denied: If an approver chooses to deny a pending request, the request enters a denied state. A request cannot be approved after it is denied.

  • Approved: If all designated approvers decide to approve a pending request or no approvals are required, the request enters an approved state.

  • Executing: When execution is initiated on an approved request, the request enters an executing state.

  • Failed: A request is marked as 'Failed' if the person running the request explicitly ends or abandons the request.

  • Completed: If an executing request is completed successfully, the request enters a completed state.

For more information, see Request Processing.

See Also

Other Resources

Request Processing