Certificate Filtering

The Forefront Identity Manager Certificate Management (FIM CM) Provision API can be used to create a client application that replaces the default profile and smart card handling that is built into FIM CM. Such an application will be responsible for interacting with profiles and smart cards and creating any required certificate requests. To do this an application will need to determine for which certificates it will need to create certificate requests and for which certificates this will be handled automatically by the FIM CM server.

The collection of certificates that are associated with a profile or a smart card can be filtered to get a smaller collection of just the particular certificates of interest. For example, a client application might want to get a collection of just the certificates that are part of the user's key history. This is useful for operations such as recovering a profile.

Filtering Certificates

To obtain a collection of certificates of interest that are associated with a profile or a smart card, a client application first must obtain the complete collection of certificates for the profile or the smart card. To do this, the client application calls the FindCertificates method. The collection of certificates that is returned by this method contains all of the certificates that are associated with the profile or smart card, including all of the key history certificates (these are archived certificates that have been previously renewed).

After the client application has obtained the complete collection of certificates for the profile or the smart card, it then calls the FindAll method to filter the collection down to just the certificates of interest. When the client application calls the FindAll method it specifies a bitwise OR'ed combination of one or more CertificatesFilterFlags values that determines which of the certificates that are associated with the profile or the smart card will be included in the resulting collection. The resulting collection will include only the certificates that match all of the specified filters. For example, if a client application calls the FindAll method with an expression for the filter parameter of (CertificatesFilterFlags.Native | CertificatesFilterFlags.KeyHistory) will return all of certificates that are native certificates AND that are part of the key history. The result is equivalent to making multiple calls to the FindAll method, each time specifying a single filter, and using the results of each call as the input collection of certificates to the next call.

For example, if a client application calls the Recover method to recover a software profile or a smart card profile, the application must first determine for which certificates the application needs to generate certificate requests, and for which certificates the FIM CM server will automatically generate certificate requests. The application can perform certificate filtering for this purpose as follows:

1. Call the FindCertificates method to get all of the certificates that are associated with the profile.

   allCerts = FindOperations.FindCertificates(profile);
   

2. Call the FindAll method to filter all of the certificates that are associated with the profile to get only those certificates that are native to the profile and are not part of the key history.

   nativeCerts = CertificatesFilter.FindAll(allCerts, CertificateFilterFlags.Native | CertificateFilterFlags.NotKeyHistory);
   

3. Call the GetProfileTemplate method to get the profile template for the profile.

   profileTemplate = GetProfileTemplate(profile.ProfileTemplateUuid);
   

4. Check the recovery policy in the profile template to see if the archived certificates need to be reissued.

   reissue = profileTemplate.RecoverPolicy.ReissueArchivedCertificates;
   

   1. If the archived certificates do not need to be reissued, then call the FindAll method again to filter the results of the first certificate filtering operation to remove all of the archived certificates.

      certsToGenerate = CertificatesFilter.FindAll(nativeCerts, CertificateFilterFlags.NotArchivedOnCa);
      

      In this situation the archived certificates will be returned by the FIM CM server.

   2. If the archived certificates need to be reissued, then certificate requests must be generated for the archived certificates. Check the server key generation configuration in the profile template to see if the FIM CM server will generate the archived certificates.

      serverGenerates = profileTemplate.ServerKeyGeneration.ServerGeneratesArchivedKeys;
      

      If the FIM CM server will generate the archived certificates, then call the FindAll method to filter the results of the first certificate filtering operation to remove all of the archived certificates.

      certsToGenerate = CertificatesFilter.FindAll(nativeCerts, CertificateFilterFlags.NotArchivedOnCa);
      

      Otherwise, the application must generate all of the certificates in the collection that resulted from the first certificate filtering operation.

      certsToGenerate = nativeCerts;
      

5. Call the Recover method to recover the profile with the certificate requests for the identified certificates.

   recoverCerts = ExecuteOperations.Recover(..., certificateRequests, ...);
   

Remarks

Calls to the FindAll method are not remoted.

See Also

Reference

CertificatesFilterFlags
FindAll
FindCertificates
GetProfileTemplate
Recover

Concepts

Programming with the FIM CM Provision API