Manually assigning, renewing or replacing FIM CM account certificates

Applies To: Forefront Identity Manager 2010

FIM CM has three accounts that require certificates. These are the FIM CM Agent account, the FIM CM Enrollment Agent account, and the FIM CM Key Recovery Agent account. These certificates are typically issued when the FIM CM Configuration Wizard is run. However, these certificates can also be manually issued. Likewise, if these certificates expire, it will be necessary to renew them. This document describes how to configure the certificates manually and how to renew these certificates.

Manually configuring FIM CM account certificates

When you run the FIM CM Configuration wizard, there is an option for Create and configure certificates manually. By default, this option is not checked and FIM CM will request certificates for these accounts when the wizard runs. If you have already assigned these accounts certificates or wish to manually assign certificates later, select this option.

WarningWarning
To avoid data loss, it is highly recommended that the certificates and keys for the FIM CM Agent, FIM CM Key Recovery Agent and FIM CM Enrollment Agent be backed up.

Configuration Wizard

If you are manually issuing certificates to the FIM CM accounts, you must ensure that the proper type of certificate is issued to the account. That is, make sure that the FIM CM Agent has a certificate that was based on the User certificate template of a Windows Certificate Authority. Likewise be sure that the FIM CM Key Recovery Agent has a certificate that was based on the Key Recover Agent certificate template and that the FIM CM Enrollment Agent has a certificate that was based on the Enrollment Agent certificate template of a Windows Certificate Authority. Also make sure that the certificate templates used are based on Windows 2003 Server Enterprise. FIM CM does not yet support Cryptography Next Generation (CNG) which is enabled jn Windows 2008 Server Certificate Authority certificate templates if the minimum supported CA is set to “Windows 2008 Enterprise Edition.” The following table provides a summary of the FIM CM Accounts and the certificate requirments.

 

FIM CM Account Certificate Based on the following Windows CA Certificate Template Description

FIM CM Agent

User

This account is used by FIM CM to sign data. It is also the default account used to encrypt data. The certificate requirements are:

  • Private key must be exportable

  • Certificate template must be Windows Server 2003

  • Recommended minimum key size: 2048

  • De-select Include e-mail name in subject name.

  • De-select E-mail under Include this information in the alternate subject name:

  • At least one of the configured Cryptographic Service Providers (CSPs) must support SHA256, 3DES, DES, and AES encryption alogorithims. The Microsoft Enhanced RSA and AES Cryptographic Provider satisfies this requirement.

FIM CM Key Recovery Agent

Key Recovery Agent

This account recovers archived private keys from the CA or HSM. The certificate requirements are:

  • Private key must be exportable

  • Certificate template must be Windows Server 2003

  • Recommended minimum key size: 2048

  • De-select Include e-mail name in subject name.

  • De-select E-mail under Include this information in the alternate subject name:

FIM CM Enrollment Agent

Enrollment Agent

This account requests certificates on behalf of a user account. These requests are signed using the FIM CM Enrollment Agent certificate. The certificate requirements are:

  • Private key must be exportable

  • Certificate template must be Windows Server 2003

  • Recommended minimum key size: 2048

  • De-select Include e-mail name in subject name.

  • De-select E-mail under Include this information in the alternate subject name:

The process of manually configuring the certificates can be complete doing the following:

  1. Obtain the account’s certificate thumbprint.

  2. Edit the web.config file

  3. Add the FIM CM Key Recovery Agent’s thumbprint to the certificate authority.

  4. Add the FIM CM Agent’s thumbprint to the certificate authority.

Obtain the account’s certificate thumbprint

A certificate’s thumbprint is the SHA-1 hash of a certificate. The thumbprints are required because they are referenced by the FIM CM web.config file. The FIM CM Agent account thumbprint also needs to be added to the certificate authority.

The following section shows two different ways of obtaining a certificates thumbprint. The first method assumes that the FIM CM accounts have already been issued certificates from a Windows Certificate Authority and that the certificates are published in Active Directory. The second method describes how to use the certutil command line utility to obtain the certificates hash. This is useful in situations when the certificate may not be published in Active Directory. If the accounts have been issued certificates from a 3rd party CA, then these steps will differ. Consult the vendor or product documentation of the 3rd party certificate authority for information on how to obtain the thumbprint. These steps can be used for all 3 accounts, the FIM CM Agent, the FIM CM Enrollment Agent, and the FIM CM Key Recovery Agent.

Method 1 - To obtain the account certificate thumbprint via Active Directory

  1. Log on to a domain controller with the appropriate credentials.

  2. Click Start, Administrative Tools, and then click Active Directory Users and Computers.

  3. In Active Directory Users and Computers, at the top, select view and ensure that Advanced Features is selected.

  4. Navigate the OU that contains the FIM CM Agent account, right-click the account and choose Properties

    FIM CM Agent account properties

  5. At the top, select the Published Certificates tab.

  6. On the Published Certificates tab, click the certificate in the center and select View Certificate. This will bring up a certificate window.

  7. On the certificate window, at the top, click Details.

  8. On the Details tab, scroll down through the list of fields and select thumbprint. This will populate the lower box with a thumbprint. Highlight the thumbprint and select Ctrl+ C.

    Certificate

  9. Open notepad and hit Ctrl+V. This should paste the thumbprint into notepad.

    Cert Paste

  10. Now, in notepad, remove all of the spaces and capitalize all of the letters so that it looks like the screenshot below. Save this file so that we can use it later. It must be in this format when entering it into the web.config file and adding it to the Recovery Agents properties on the Certificate Authority.

    Redone thumbprint

  11. Repeat these steps for the other FIM CM Enrollment Agent account and the FIM CM Key Recovery Agent account.

Method 2 - To obtain the account certificate thumbprint via certutil

  1. Using the FIM CM Agent account, log on to a computer such as Windows 7 Ultimate.

  2. Click Start, All Programs, Accessories, and then click Command Prompt. This will open a command prompt window.

  3. In the command prompt window enter certutil –show –user my” and hit enter. This will display information about the FIM CM Agent’s certificate. See the screen shot below.

    certutil

  4. At the top of the command prompt window, right-click the top border. This will bring up a drop-down box. Select Edit, and Select All. Now, right-click the top border, select Edit and Copy.

  5. Open notepad and at the top click Edit and Paste. This should paste the information into notepad.

  6. Now scroll down, highlight the certificate hash and from the top select Edit and copy.

    Notepad of certutil

  7. Now open another instance of notepad and hit Ctrl+V. This should paste the thumbprint into notepad.

  8. Now, in notepad, remove all of the spaces and capitalize all of the letters so that it looks like the screenshot below. Save this file so that we can use it later. It must be in this format when entering it into the web.config file and adding it to the Recovery Agents properties on the Certificate Authority.

    Redone thumbprint

  9. Repeat these steps for the other FIM CM Enrollment Agent account and the FIM CM Key Recovery Agent account.

Edit the web.config file

The web.config file is a local configuration file that resides on the FIM CM Web portal. The FIM CM web.config file contains six different lines that reference the thumbprints of these certificates. By default it is located at %Program Files%\Microsoft Forefront Identity Manager\2010\Certificate Management\web. Be aware that changes to the web.config are only local, so if you have multiple web portals, then each one will need to have their web.config updated. By default, if the FIM CM Configuration Wizard automatically assigns the FIM CM account certificates, the entries in the web.config file will be setup automatically. If this is a brand new install, and you have selected the Create and configure certificate manually in the Configuration wizard, then the values in the FIM CM web.config file will be blank. At this point, you will need to manually configure these thumbprints. The following table summarizes the web.config entry and the required hash.

 

Web.config entry Thumbprint Hash

<add key=”Clm.SigningCertificate.Hash” value=”” />

FIM CM Agent

<add key=”Clm.ValidSigningCertificates.Hashes” value=”” />

FIM CM Agent

<add key=”Clm.Decryption.Certificate.Hash” value=”” />

FIM CM Agent or unique certificate. This is optional and may be left blank.

<add key=”Clm.Encryption.Certificate.Hash” value=”” />

FIM CM Agent or unique certificate. This is optional and may be left blank.

<add key=”Clm.SmartCard.ExchangeCetificate.Hash” value=”” />

FIM CM Agent

<add key=”Clm.EnrollAgent.Certificate.Hash” value=”” />

FIM CM Enrollment Agent

The Clm.Decryption.Certificate.Hash and the Clm.Encryption.Certificate.Hash are the only two that are optional. The other four all require a valid certificate hash. These keys are used for encrypting and decrypting data collection information that has the encryption option enabled for storage in the FIM CM database. These keys allow a unique certificate to be referenced rather than the default certificate issued to the FIM CM Agent account. The certificate and the private key must be in the FIM CM Agent’s profile on the FIM CM server, but using a separate key allows the key to be used programmatically to access the encrypted data, without exposing the FIM CM Agent’s private key that is used for signing operations outside of the FIM CM environment. If these entries are left blank then FIM CM will default to using the FIM CM Agent certificate hash.

Once the thumbprints have been copied, they are ready to be added to the FIM CM web.config file. Follow the steps below to do this.

To edit the web.config file

  1. Log on to the FIM CM web portal machine with an account that has appropriate permissions to edit the web.config file.

  2. Navigate to the web.config file.

  3. Open the web.config file in Notepad or another editor. Microsoft Visual Studio Tools for Applications 2.0 was used while creating this document.

  4. Navigate through the web.config file. Find the entry from the table above and enter the corresponding certificate thumbprint.

    Edited web.config

    Repeat the above steps for the remaining entries.

  5. Once this is done, click Start, click All Programs, click Accessories, and then click Command Prompt. This will launch a Command Prompt window.

  6. In the Command Prompt window, type the following text, and then hit Enter: iisreset. This will stop and then restart IIS. Once this completes, close the Command Prompt window.

  7. Click Start, select Administrative Tools, and then click Services

  8. Scroll down and right-click Forefront Identity Manager CM Update Service, and then select Restart. This will restart the Forefront Identity Manager CM Update Service.

    FIM CM Update Service

Add the FIM CM Key Recovery Agent’s certificate to the certificate authority

The FIM CM Key Recovery agent’s certificate must be added to the Recovery Agents properties of the certificate authority. The Key Recovery Agent allows for key archival and recovery. It is important to have a lifecycle strategy for the Key Recovery Agent certificates. Designing a lifecycle strategy is outside the scope of this document. For more information see Key Archival and Management in Windows Server 2008 (http://go.microsoft.com/fwlink/?LinkId=212503).

The following section assumes the use of a Windows Certificate Authority and that the FIM CM Key Recovery agent was issued a Key Recovery Certificate. If you are using a 3rd party CA, then these steps will differ. Consult the vendor or product documentation of the 3rd party certificate authority for information on how add the FIM CM Key Recovery Agents certificate to the Recovery Agents for the certificate authority.

ImportantImportant
If FIM CM is using multiple certificate authorities then the certificate will have to be added to each of these CAs.

To add the FIM CM Key Recovery Agent’s certificate to the certificate authority

  1. Log on to the Certificate Authority with the appropriate credentials.

  2. Click Start, Administrative Tools, and then click Certification Authority.

  3. On the left, right-click the certificate authority and select Properties.

  4. In Properties, select the Recovery Agents tab.

  5. On the Recovery Agents tab, select Archive the key and click Add.

  6. Choose the FIM CM Key Recovery Agent’s certificate.

    Key Recovery

  7. Click Apply. You will be prompted to restart the certificate authority. Click Yes. Once the certificate authority restarts, close Certification Authority.

Add the FIM CM Agent’s thumbprint to the certificate authority

The FIM CM agent’s thumbprint must be added to the Policy Module properties of the certificate authority. The FIM CM Policy Module is a component installed on the CA that facilitates communication between the FIM CM web portal and the SQL server.

The following section assumes the use of a Windows Certificate Authority. If you are using a 3rd party CA, then these steps will differ. Consult the vendor or product documentation of the 3rd party certificate authority for information on how to add the FIM CM Agents thumbprint.

ImportantImportant
If FIM CM is using multiple certificate authorities then the thumbprint will have to be added to each of these CAs.

To add the FIM CM Agent’s thumbprint to the certificate authority

  1. Log on to the Certificate Authority with the appropriate credentials.

  2. Click Start, Administrative Tools, and then click Certification Authority.

  3. On the left, right-click the certificate authority and select Properties.

  4. In Properties, select the Policy Module tab.

  5. Ensure that the FIM CM Policy Module is selected and click Properties.

  6. On the Recovery Agents tab, select Archive the key and click Add.

  7. Click the Signing Certificates tab. Click Add.

  8. Enter the certificate hash in the box provided and click OK.

    Signing Certificate

  9. Click Apply. You will be told that the certificate authority needs to be to restart for the changes to take effect. Click Ok. Click OK. You will be prompted to restart the certificate authority. Click Yes. Once the certificate authority restarts, close Certification Authority.

Replacing or Renewing the FIM CM Account certificates

Replacing or renewing the certificates for the FIM CM accounts is similar to the steps outlined above, however there are some differences. The recommended process of replacing or renewing the certificates for these accounts is to log on to a machine using these accounts and either use auto-enrollment, if enabled, or by using web enrollment. If using web enrollment, you must ensure that the proper certificate templates are available to choose from for the Key Recovery Agent and Enrollment Agent accounts. This can be an issue if the accounts were automatically created using the FIM CM Configuration Wizard. How to overcome A work around for this obstacle is described below. Once you have obtained new certificates then the thumbprint needs to be updated in the web.config file. You can use the following flowchart to help guide you through the process of renewing certificates.

ImportantImportant
Be aware that if you have multiple FIM CM web portals, this will need to be done on each one.

Renewal flowchart

The Clm.ValidSigningCertificate.Hashes contains a history of all the FIM CM Agent account hashes that have been implemented during the server’s lifetime. When you renew or replace the FIM CM Agent certificate, you must keep the previous thumbprint value and add the new thumbprint value separated by a semicolon. Also, you must keep a copy of all the old certificates in the FIM CM Agents certificate store. See the following example.

signing cert hahes

Use the following table as a reference for either replacing the hash in the web.config file or appending it.

ImportantImportant
After you replace or append the hashes you must perform an IIS reset. See above on how to do this.

 

Web.config entry Hash Action

<add key=”Clm.SigningCertificate.Hash” value=”” />

Replace

<add key=”Clm.ValidSigningCertificates.Hashes” value=”” />

Append

<add key=”Clm.Decryption.Certificate.Hash” value=”” />

Replace

<add key=”Clm.Encryption.Certificate.Hash” value=”” />

Replace

<add key=”Clm.SmartCard.ExchangeCetificate.Hash” value=”” />

Replace

<add key=”Clm.EnrollAgent.Certificate.Hash” value=”” />

Replace

Be aware that when you renew or replace the FIM CM Agent account’s certificate, if this certificate was used for encryption, the old certificate still needs to exist in the FIM CM Agent account’s certificate store. This will allow you to decrypt data that may have been encrypted with the old certificate. If these certificates are no longer available, then data that was encrypted with them will be unavailable.

Using CLMUtil -setacctpwd

If you let the FIM CM configuration wizard create the FIM CM accounts, chances are that the passwords that FIM CM uses will not be known. In order to log on to a Windows machine and renew or replace the certificate using these accounts you will need to reset the password for these accounts in Active Directory. Once you have done this, you also need to use the CLMUtil command-line tool that is installed with FIM CM and change the encrypted password that is stored in the registry on the web portal.

ImportantImportant
Be aware that if you have multiple FIM CM web portals, this step will need to be done on each one.

To set an account password using CLMUtil -setacctpwd

  1. Log on to the Certificate Authority with the appropriate credentials.

  2. Click Start, click All Programs, click Accessories, and then click Command Prompt. This will launch a Command Prompt window.

  3. In the Command Prompt window navigate to %Program Files%\Microsoft Forefront Identity Manager\2010\Certificate Management\Bin

  4. Type: CLMUtil –setacctpwd agent “Pass1word$”.

  5. Restart IIS and FIM CM Update service.

  6. clmutil

For additional information on clmutil –setacctpwd see CLMUtil command-line tool(http://go.microsoft.com/fwlink/?LinkId=208822).

Backing up the FIM CM account certificiates and keys

The following section shows two different ways of backing up the FIM CM account certificates. The first method uses certmgr.msc and the export wizard. The second method uses certutil.exe. In order to perform both methods you will need to know the account passwords. You must use the methods below with each individual account and be able to log on to the FIM CM Server with each of these accounts. Also, you will need to know the certificate hash if using certutil.exe to backup the certificate. To obtain the hash see the above section.

Method 1 – To backup the FIM CM account certificates and keys using certmgr.msc

  1. Log on to the FIM CM server with the FIM CM Agent account.

  2. Click Start, Run, and then enter certmgr.msc in the Run box. Click OK.

  3. At the top, on the left, expand Personal and click on Certificates.

  4. On the right, right-click the FIM CM Agent account certificate and select All Tasks and Export. This will begin the certificate export wizard.

    certmgr.msc

  5. On the Welcome screen, click Next.

  6. On the Export Private Key screen, select Yes, export the private key and click Next.

  7. On the Export File Format screen, under Personal Information Exchange – PKCS#12(.PFX) select Include all certificates in the certificate path if possible and Export all extended properties then click Next.

    export file format

  8. On the Password screen, enter a password and confirm the password to protect the .pfx file and click Next.

  9. On the File to Export screen, browse to the directory you wish to save the .pfx file, enter a file name, and click Save.

  10. Click Next.

  11. Click Finish. You should see a pop-up box saying The export was successful. Click OK.

  12. Close certmgr.msc.

  13. Repeat for the remaining accounts.

Method 2 - To backup the FIM CM account certificates and keys using certutil

  1. Using the FIM CM Agent account, log on to the FIM CM Server.

  2. Click Start, All Programs, Accessories, and then click Command Prompt. This will open a command prompt window.

  3. In the command prompt window enter certutil –f –p pass1word$ -user –exportPFX DB072CD509CF6E22C2E5042ECD668E17EA71D5F4 c:\certbackup\fimcmagent.pfx and hit enter. Change the password , certificate hash, and directory to reflect your information.

    certutil backup

  4. Repeat these steps for the other FIM CM Enrollment Agent account and the FIM CM Key Recovery Agent account.

Community Additions

ADD
Show: