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.

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.

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

   

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.

   

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

   

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.

    

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.

   

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.

   

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.

   

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.

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.

   

   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.

   

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 (https://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.

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.

   

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.

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.

   

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.

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.

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

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.

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. 

For additional information on clmutil –setacctpwd see CLMUtil command-line tool(https://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.

   

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.

   

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.

   

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