Microsoft AD Federation Service: nShield HSM Integration Guide

This document covers the integration using module protection for the AD FS Token keys, with cipher suite DLf3072s256mAEScSP800131Ar1 .

• An existing Active Directory Domain Services (AD DS) system (domain controller) operating the domain at the Windows Server 2016 Functional Level.

• An existing Microsoft Active Directory Certification Service (AD CS) system configured as an Enterprise issuing CA (for access to certificate templates).

• Credentials to update the domain’s DNS service to configure a host entry for AD FS.

• A Security World has already been created or loaded on the HSM to be used by AD FS. For details on installing and registering the nshield CNG KSP via the installed CNG wizard, see Install and register the CNG provider .

Throughout this guide, sections are prefaced with AD FS Server , AD DS Server , or AD CS Server ; make sure you execute the steps in each section on the intended server.

For details on installing and configuring the Active Directory Certificate Authority using nshield HSMs, see the Microsoft AD CS and OCSP Integration Guide for Microsoft Windows Server 2019 .

Requirements for deploying the Microsoft Windows Server environment to support the AD FS role:

This Integration Guide provides step-by-step instructions to install and configure Microsoft AD FS for use with nshield HSMs. For our testing purposes, Microsoft Windows Server 2019 was used as the platform for all three requires roles (AD DS, AD CS, and AD FS).

Entrust has successfully tested the integration of AD FS and an nshield HSM using the following configurations:

¹ In this configuration, the OCS must not have a passphrase.

² In this configuration, using a Softcard or OCS with passphrase (or with/without passphrase if k>1) requires that you start the AD FS service using the nshield preload tool. For module protected keys or OCS without a passphrase, preload is not necessary.

¹ Requires Security World client software v12.71 or later if OCS has a passphrase

² Requires Security World client software v12.71 or later both with or without OCS passphrase

³ Requires Security World client software v12.71 or later

⁴ If using Softcard to protect AD FS keys, an OCS is still required as the preload command requires FIPS-auth to load keys

Perform the steps in this section on an AD DS (domain controller) system serving the AD FS server.

1. Open a PowerShell window to execute the commands in this section.

2. Create a Key Distribution Services, (KDS) Root Key so that Domain Controllers (DC) can begin generating gMSA passwords:

   PS C:\> Add-KdsRootKey -EffectiveTime ((get-date).addhours(-10))
   
   Guid
   -----
   bdab22a0-16c1-b0eb-f46c-0638024f7fc9

   When the root key has been created, it will take several hours to propagate across to all Domain Controllers on the network.

3. Create the Group Managed Service Account (gMSA) to run the AD FS service:

   New-ADServiceAccount <Name of AD FS gMSA> -DNSHostName <FQDN of AD FS service>
   -ServicePrincipalNames http/<Name of AD FS service>

   Example:

   PS C:\> New-ADServiceAccount FedServgMSA -DNSHostName adfs.example.com -ServicePrincipalNames http/adfs.example.com

4. Configure the AD FS Service Principle Name (SPN):

   setspn -s http/<name of the AD FS service> <Name of AD FS gMSA>

   Example:

   PS C:\> setspn -s http/adfs1.example.com example.com\FedServgMSA

   This sometimes shows a duplicate SPN, with the following message:

   Checking domain DC=domain,DC=com
   CN=FedServgMSA,CN=Managed Service Accounts,DC=domain,DC=com
      http/adfs.domain.com
   Duplicate SPN found, aborting operation!

5. Create a DNS host record for your AD FS service name and its IP address:

   1. Using Server Manager, select Tools > DNS .

   2. Select the Domain controller and then expand Forward Lookup Zones .

   3. Select <your domain> .

   4. Right-click either: <your domain> in the left hand pane or right-click in the right hand pane to pull up a list of options and select New Host (A or AAAA) .

   5. In New Host , enter:

      Name	<AD FS service name> (the FQDN will auto complete)
      IP address	<IP address of the AD FS host server>

   6. Select Add Host at the bottom of the screen.

Perform the steps in this section on an AD CS(CA) system serving the AD FS server.

This Integration Guide relies on the availability of an Enterprise Microsoft AD CS (CA) server within the Active Directory forest. While it may be possible to use another CA product or an external CA for issuing AD FS certificates, the procedures are not in scope of this Integration Guide .

Follow the Microsoft installation and configuration procedures to deploy your CA. If you wish to deploy your Microsoft AD CS server using an nshield HSM for protection of the CA’s private signing key, download the latest Microsoft AD CS and OCSP Integration Guide for Microsoft Windows Server from the Entrust nFinity Microsoft partner page .

Perform the steps in this section on an AD CS (CA) system serving the AD FS server.

Create a TLS certificate template for use by AD FS as follows:

1. On an Issuing CA, open the Certification Authority management console.

2. Expand the Certification Authority node in the left hand pane, then right-click Certificate Templates and select Manage .

3. In the Certificate Templates Console , locate the Web Server certificate template, right-click it and from the context menu select Duplicate Template .

4. In the Properties of new template dialog, select the General tab.

5. For Template display name , name the template, for example "ADFS TLS1".

6. Change the Validity Period to whatever value is desired.

7. Select the Compatibility tab and change the Certification Authority to Windows Server 2016 and the Certificate Recipient to Windows 10/Windows Server 2016 .

8. Select the Subject Name tab and make sure that Supply in the request is selected. This is because the AD FS service name will be different from the AD FS Server name, and will need to be specified in the request.

9. Select the Request Handling tab and under Purpose select Signature and encryption . Select Authorize additional service accounts to access the private key .

10. Select Key Permissions .

11. In the Permissions for screen, select Add .

12. Select Object Types and then check the boxes for Service Accounts and Computers from the listed objects.

13. Select OK .

14. For Enter the object names to select , type in full/partial names for (separated by semicolons):

    • The Group Managed Service Account you created on your Domain Controller.

    • The AD FS server computer account.

15. Select the Advanced tab, select Find Now and select the Group Managed Service Account you created on your Domain Controller .

16. Select OK to add into Enter the object names .

17. Select OK .

18. Select Allow Full Control .

19. Repeat to add the AD FS server Computer account, make sure that the AD FS server Computer account has Full Control .

20. Select OK to close the Permissions for…​ window.

21. Select the Cryptography tab. On this tab:

    1. Make sure Key Storage Provider is selected from the drop down list for Provider Category .

    2. For Algorithm Name , select RSA from the drop down menu.

    3. Set the Minimum Key Size to at least 2048 for RSA.

    4. Make sure that Requests can use any provider available on the subject’s computer and nCipher Security World Key Storage Provider are selected.

    5. Set Request Hash to SHA256.

22. Select the Security tab. On this tab:

    1. Select Add

    2. Select Object Types and then check the boxes for Service Accounts and Computers from the listed objects.

    3. Select OK .

    4. For Enter the object names to select , type in full/partial names for (separated by semicolons).

    5. The Group Managed Service Account you created on your domain controller. That is, the AD FS server computer account(s) and the Domain Computers group.

    6. Select Check Names to auto-complete (you may need to select Advanced to narrow down your search in large domains).

    7. Select OK .

23. Back in the Security tab, for each account or system that was just added, select the check boxes in the Allow column labeled Read and Enroll . Do not modify the default permissions for any of the existing groups/users:

    • Authenticated Users should only have Read permission.

    • Administrator should have Read/Write permissions.

    • Domain Admins should have Read/Write/Enroll permissions.

    • Enterprise Admins should have Read/Write/Enroll permissions.

24. When all template configuration has been completed, select Apply and OK then close the Certificate Templates console.

25. Make sure that you are logged into the AD CA as Domain administrator.

26. Issue the new certificate template to the current CA:

    1. Open the Certificate Authority console.

    2. On the Server Manger Dashboard, go to Tools > Certificate Authority .

    3. Under Certification Authority (local) , expand the Domain (this is presented as a computer with a green tick next to it).

       Note	You may need to restart Active Directory Certificate Service to make sure the new template is available.

    4. Right-click Certificate Templates (last item from the list in the left hand section).

    5. Select New and then select Certificate Template to Issue .

    6. Select the certificate template just created, and then select OK . The new template will now appear in the Certificate templates list.

27. Close the Certification Authority management console.

Perform the steps in this section on the AD FS server

Install a compatible and supported version of the nshield Security World software (see the Validation Matrix in the introduction for more detail) on the designated AD FS server.

1. Log into the Windows workstation as an administrator.

2. Navigate to the location of the Security World software.

3. Install the Security World software:

   1. Double-click on the Security World setup.msi to start installation.

   2. At the Welcome screen select Next .

   3. At the End-User License Agreement screen, accept the terms and then select Yes .

   4. At the Product Features screen, select the appropriate packages for your environment and select Install .

   5. The installation will begin installing the selected software components.

   6. At the Completed screen, select Finish .

4. Add the Security World tools to the system path environment variable:

   1. Navigate to Start > Windows System > Control Panel .

   2. Navigate to System and Security .

   3. Navigate to System .

   4. On the left side of the System window, select Advanced system settings .

   5. In the System Properties > Advanced tab that appears, select Environment Variables .

   6. In the popup Environment Variables window, in the System Variables section, select Path and select Edit .

   7. In the Edit environment variable dialog, select New .

   8. In the text field that enables, enter in the additional path of %NFAST_HOME%\bin and select OK .

   9. Back in the Environment variables window, select OK .

   10. Back in the System Properties window, select OK .

5. If using a Softcard or OCS with a passphrase (requires Security World client v12.71 or later — see section Validation Matrix for more detail), you will need to use the preload command to start the AD FS service, and thus must configure the NFAST_NFKM_TOKENSFILE system environment variable.

   1. Navigate to Start > Windows System > Control Panel .

   2. Navigate to System and Security .

   3. Navigate to System .

   4. On the left side of the System window, select Advanced system settings .

   5. In the System Properties > Advanced tab that appears, select Environment Variables .

   6. In the popup Environment Variables window, in the System Variables section, select New .

   7. For Variable name , select NFAST_NKM_TOKENSFILE .

   8. For Variable value , enter c:\nfast_nfkm_tokensfile (or another name/location of your choosing).

   9. Select OK .

   10. Back in the Environment Variables window, select OK .

   11. Back in the System Properties window, select OK .

6. If you are using the nshield Remote Administration cards, you must make sure that the cardlist file, C:\ProgramData\nCipher\Key Management Data\config\cardlist , has either the relevant card serial number(s) (recommended) or contains a single line with a wildcard * (not recommended for production environments). See the contents of the default cardlist file for more info.

7. Close any open PowerShell or Command Prompt windows (when you open new ones later on, the system environment variables will be known in the new shells)

Refer to the applicable User Guide for your nshield HSM for installation and configuration instructions. If using an nshield Connect HSM or nshield-as-a-Service (nSaaS) HSM, be sure to perform the required procedures to enroll the AD FS server with the HSM (with the nethsmenroll command).

If you are using an nshield-as-a-Service (nSaaS) fully-managed environment, the nSaaS Operations Team will configure your HSM subscription and assist you with establishing a VPN connection to the HSM datacenter(s).

Once your server is configured to communicate with an HSM, verify the HSM connection with enquiry before continuing. The output below should be similar:

Refer to the applicable User Guide for your nshield HSM for instructions on creating or loading a Security World that fits your organizational security requirements. If you are using an nshield-as-a-Service (nSaaS) fully-managed environment, the Entrust nSaaS Operations Team will create the Security World for you and provide you with the necessary world data files for your AD FS server.

A valid Security World must be loaded in the HSM, and world data must exist in the AD FS server in the C:\ProgramData\nCipher\Key Management Data\local folder before continuing to the next section.

Ensure you have properly created a Softcard or Operator Card Set (OCS) if you plan on using either to protect your AD FS keys. Refer to the applicable nshield User Guide for instructions.

Check the world status using nfkmcheck before continuing on to the next section.

For an unrestricted (FIPS 140-2 level 2) Security World, the output should resemble the following:

For a strict FIPS (FIPS 140-2 level 3) Security World, the following output should resemble the following:

Application key tokens are an encrypted form of a Security World generated cryptographic key. These key tokens must not be mistaken for or regarded as being a Key in or of itself. The key is at all times obfuscated in this encrypted form and is only available for use as a cryptographic key when copied to the FIPS 140-2 Level 3 security boundary of a correctly configured nshield HSM.

It is possible to use the CNG wizard to either load (reuse) an existing Security World instance or create a new instance. If you are creating a new Security World, see Installation Guide and User Guide for your HSM on the information required to define Security World parameters. The HSM must be properly configured before running the CNG installation wizard.

To confirm the HSM is available:

1. Open a CLI as Administrator. You must run the cmd with elevated privileges. To do this, right-click the cmd icon and select Run as administrator .

2. Run the command:

   enquiry

   Server: and Module #1: should be reported showing the serial number (in form eeee-ssss-nnnn ) of the module and hardware status as OK (this can be found at the bottom of the section detailing information on the module #).

   Note	If you are using an existing Security World, you can check to make sure it is available by running the command nfkminfo . Look at the state line of the output it should be reported as initialized and usable . There should be no ! prefix.

3. When the Security World software is operational, you must run the CNG install wizard to install and register the nshield Key Storage Provider (KSP). This can be performed via the CNG install wizard that can be found in the Start menu of the desktop > nCipher > CNG Configuration Wizard .

4. Select Start and look for the recently added nshield utilities, double-click the CNG configuration wizard . If the User Access Control prompt appears, select YES to continue.

5. The Enable HSM Pool Mode screen prompts you to Enable HSM Pool Mode for CNG Providers . Leave the default value, make sure that the check box is clear, and select Next .

6. At the Initial Setup screen, your security world should have already been created or loaded in the section Create or Load a Security World . Choose Use the existing security world and select Next .

7. Make sure that the Set Module States screen, ensure module 1 shows both operational and usable then select Next .

8. At the Key Protection Setup screen choose Allow any protection method to be selected in the GUI when generating and select Next .

9. At the Software Installation screen, select Next .

10. At the Finish registering the nCipher Providers screen, select Finish .

11. The nshield CNG providers will now be installed and the KSP will be registered. To confirm that the KSP has been successfully registered open either a CLI or PowerShell (right-click and Run as Administrator ) and run the following command:

    >cnglist.exe --list-providers
    
    PS C:\WINDOWS\system32> cnglist.exe --list-providers
    Microsoft Key Protection Provider
    Microsoft Passport Key Storage Provider
    Microsoft Platform Crypto Provider
    Microsoft Primitive Provider
    Microsoft Smart Card Key Storage Provider
    Microsoft Software Key Storage Provider
    Microsoft SSL Protocol Provider
    Windows Client Key Protection Provider
    nCipher Primitive Provider
    nCipher Security World Key Storage Provider
    
    PS C:\WINDOWS\system32>

    You should see the nCipher Security World key Storage Provider listed.

    Note	Ensure command prompt or PowerShell is launched as Administrator.

12. Reboot the server.

The instructions in this section assume that all certificates for AD FS will be issued from an Enterprise Microsoft AD CS (CA) server within the Active Directory forest The certificate template to be used was previously configured in section AD FS Server: Create a TLS certificate template for use by AD FS . Configuring AD FS for use with a different CA product or an external PKI is not in scope of this integration guide.

Four keys/certificates will be created for use by AD FS. You can create all four of these keys/certificates before installing the AD FS role, so they will be ready for use in later sections. The critical parameters for these objects are as follows (tailor these for your environment), which will be referenced in the steps to follow:

Make sure the new certificate template is visible within the domain, run gpupdate to refresh the Group Policy before proceeding Open a command prompt opened as Administrator and run gpupdate :

1. On the AD FS server, open certlm.msc using the Run command or an administrator level command prompt.

2. From the left-hand panel beneath Certificates-Local Computer , right-click the Personal folder, select All Tasks > Request New Certificate .

3. The Certificate Enrollment wizard will start, select Next .

4. On the Select Certificate Enrollment Policy screen, select Next .

5. The Request Certificates window should display the recently created certificate template, select the link More information is required to enroll for this certificate. Click here to configure settings to continue.

6. On the Certificate Properties window, in the Subject tab:

   1. Under Subject Name , in Type choose Common Name .

   2. In Value , enter the value from the Common Name field in the table at the beginning of this section.

   3. Select Add .

   4. Under Alternative name , in Type choose DNS .

   5. In Value , enter the value from the Alternative Name field in the table at the beginning of this section. If there is no alternative name required as shown in the table, this step can be skipped. Select Add .

      Note	Repeat this process if more than one alternative name is required.

7. On the General tab, specify a sensible and recognizable name for the certificate.

8. Select the Private Key tab and expand the Cryptographic Service Provider and select the appropriate provider defined in the table at the beginning of the section. Make sure that only one provider is checked. Uncheck all of them except the one you need.

   • For a software-based key, choose RSA,Microsoft Software Key Storage Provider .

   • For an HSM-based key, choose RSA,nCipher Security World Key Storage Provider .

9. Select OK to close the Certificate Properties window.

10. On the Certificate Enrollment , Request Certificates window, check the box for the certificate just requested, and then select Enroll .

11. For HSM-based keys, the nCipher Key Storage Provider - Create Key wizard will appear.

    1. At the Create new key screen, select Next .

    2. At the Select a method to protect new key screen, select the desired key protection mechanism to use. For module, select Module protection and select Finish . For Softcard select Softcard protection and select Next .

    3. At the Select token to protect key with screen select the appropriate Softcard from the list and select Finish .

    4. When prompted for the passphrase (if required) enter it and select Finish .

12. For OCS select Operator Card Set protection and select Next .

13. At the Select token to protect key with screen select the appropriate OCS from the list and select Finish .

14. At the Loading "<OCS name>" screen, insert a card from the selected OCS.

15. When the OCS card has been read, if it has a passphrase, enter it now and select Next .

16. If using a k/n OCS with k>1, repeat to load other OCS cards until quorum is made.

17. After loading the required card(s), at the Card reading complete screen, select Finish .

18. The Certificate Installation Results window should show STATUS: Succeeded , select Finish .

    Note	Repeat these steps until all four certificates have been generated.

19. Verify the new HSM keys:

    1. Open a cmd window as Administrator and run nfkminfo.exe similar to the example below This will print the CNG key created via the Certificate template. The key will have been generated using the nshield Key Storage Provider. It is possible to use the key’s AppName and its Ident to show further details.

       Example:

       PS C:\> nfkminfo -l
       
       OUTPUT:
       key_caping_machine--c4ce33928f457a19dd5a536a9038b55f02a2eaf1 `te-ADFSTLS-3ec97a8c-791a-4139-a0e6-ecbf1e185bd8`
       
       PS C:\> nfkminfo -k caping machine--c4ce33928f457a19dd5a536a9038b55f02a2eaf1
       
       OUTPUT:
       Key AppName caping Ident machine--c4ce33928f457a19dd5a536a9038b55f02a2eaf1
       BlobKA length        1052
       name                 "te-ADFSTLS-3ec97a8c-791a-4139-a0e6-ecbf1e185bd8"
       hash                 42b4875c0a2fc7af57fa8a904939c4a361c30ff9
       recovery             Enabled
       protection           Module
       other flags          PublicKey !SEEAppKey !NVMemBlob +0x0
       gentime              2021-09-10 19:49:17
       SEE integrity key    NONE
       
       PS C:\> certutil -silent -store MY tq-ADFSKeys-9ad0688f-4686-4368-9586-95dc5a89c672
       
       OUTPUT:
       Serial Number: 610000000d4ee2b718a2dd02ef00000000000d
       Issuer: CN=DOMAIN ENTERPRISE ROOT CA, DC=domain, DC=com
       NotBefore: 9/17/2021 10:07 PM
       NotAfter: 9/17/2023 10:17 PM
       Subject: CN=ADFS Token-Decrypting Key
       Non-root Certificate
       Template: ADFSKeys, ADFS Keys
       Cert Hash(sha1): dc36ce9322cc6be72acf6c073861105074d036cb
       Key Container = tq-ADFSKeys-9ad0688f-4686-4368-9586-95dc5a89c672
       Provider = nCipher Security World Key Storage Provider
       Encryption test FAILED

    2. In the first output, copy the key hash for the next command, then verify the Protection field for the proper protection type. Module for module protection, PassPhrase for Sard protection, and CardSet for OCS protection.

       Note	The hash may not match the ones generated for your system.

    3. Save the name of the output of the second command for the last command.

    4. Verify the Provider field to ensure the proper Key Storage Provider has been used.

Perform the steps in this section on the AD FS server.

This can be done manually in the Server Manager.

1. Open Server Manager .

2. In Server Manager , navigate to Manage > Add Roles and Features .

3. On the Before you begin page (if it appears), select Next .

4. On the Select installation type page, select Role-based or feature-based installation , and then select Next .

5. On the Select destination server page, select Select a server from the server pool , verify that the target computer is selected, and then select Next .

6. On the Select server roles page, check the box for Active Directory Federation Services and select Next .

7. On the Select features page, select Next .

8. On the Active Directory Federation Service (AD FS) page, select Next .

9. Verify the information on the Confirm installation selections page then select Install .

   Note	Do not select the Restart the destination server automatically if required check box.

10. On the Installation progress page, wait for everything to install correctly.

11. Once the installation has completed, select Close .

This step can be completed manually in the Server Manager.

1. In Server Manager , initiate post-deployment configuration for the AD FS role.

2. At the Welcome screen, select Create the first federation server in a federation server farm , select Next .

3. In the Connect to Active Directory Domain Services page, select the account you want to use to perform the configuration (the currently logged-on account if you have admin rights, which you will need to configure the role) then select Next .

4. On the Specify Service Properties window:

   1. Select the appropriate SSL Certificate from the drop down list. Choose the software-based TLS key previously generated, which should be first in the list This will be replaced later with an HSM-based key. If you need to, select the View link to verify the certificate serial number (since both the software and HSM based credentials will be the FQDN of the AD FS service.

   2. In Federation Service Name , ensure the same FQDN is shown (the first Alternative Name, the one that matches the certificate common name.

   3. For Federation Service Display Name , enter a meaningful name for the AD FS service.

   4. Select Next .

5. On the Specify Service Account page:

   1. Select Use an existing domain user account or group Managed Service Account .

   2. Select Select .

   3. Enter the name of the gMSA account that was created on the domain controller.

   4. Select Check Names , the account should be found.

   5. Select OK .

   6. Select Next .

6. On the Specify Configuration Database page, select Create a database on this server using Windows Internal Database , and then select Next .

7. On the Review Options page, verify your configuration selections then select Next .

8. On the Prerequisite Checks page, verify that all prerequisite checks completed successfully then select Configure .

9. On the Results page you should see a green tick against This server was successfully configured .

10. You may be informed that a machine restart is required.

11. Select Close to exit the configuration.

12. In Services , make sure to configure Active Directory Federation Services to start manually . If you are using OCS or Softcard protection for your AD FS integration with the HSM, some sort of manual interaction will be required to start the service.

At this point, the AD FS server should be restarted. Once it has rebooted, log in as Administrator.

1. Ensure the AD FS service is stopped.

   net stop adfssrv

2. Ensure any existing preload cache is reset.

   preload exit

3. Remove the NFAST_NFKM_TOKENSFILE cache (if it exists) by deleting the file c:\nfast_nfkm_tokensfile .

   del c:\nfast_nfkm_tokensfile

4. Preload the keys into the HSM if necessary:

   1. For module protected keys, go to the next step.

   2. For Softcard protected keys:

      preload --reload-everything --softcard-name=<Softcard Name> pause

   3. For OCS protected keys:

      preload --reload-everything --cardset-name=<OCS Name> pause

      This preload command will intentionally pause until cancelled. You will cancel this in a later step.

5. In a separate PowerShell window, start the AD FS service.

   net start adfssrv

The AD FS sign-on page is not enabled by default in Windows 2016 and later. To enable and allow verification of a successful installation, open a PowerShell CLI as Administrator and run the following command:

1. Open Internet Explorer.

2. Add the AD FS server FQDN to the local intranet zone.

3. Add the web page to Trusted Sites:

   1. Navigate to Internet Options > Security > Trusted Sites .

   2. Select Sites .

   3. In Add this website to the zone , the web site should be auto-populated. Select Add .

   4. Select Close .

   5. Select OK to close the Internet Options window.

4. Navigate to https://adfs.domain.com/adfs/ls/idpinitiatedsignon.aspx (substitute your correct FQDN of the AD FS service).

5. You should see the AD FS sign in screen, enter your credentials to sign in AD FS.

6. You should also successfully be able to pull the AD FS configuration XML from https://adfs.domain.com/federationmetadata/2007-06/federationmetadata.xml .

Perform the steps in this section on the AD FS server.

1. On the AD FS server, open a Powershell command prompt as Administrator.

2. Run the following command:

   > Set-AdfsProperties -AutoCertificateRollover $false

Roll the AD FS Certificates from Default Objects to HSM Objects, this can be done manually on the AD FS Management Console.

1. Update the SSL Certificate object to use the new HSM-backed certificate/key in a PowerShell window running as Administrator:

   Note	For customers that installed the desired end-state SSL certificate during AD FS role configuration, there is no need to roll the SSL cert at this time. Skip to the next step (Service-Communications certificate).

   Note	If you intend to use a Web Application Proxy (which is not covered in this guide), you may want to keep the SSL/TLS certificate as a software-protected key. Refer to Microsoft guidance for requirements to configure a Web Application Proxy.

   1. Get the current state of the certificate configuration:

      Get-AdfsSslCertificate
      
      HostName                   PortNumber     CertificateHash
      --------                   ----------     ---------------
      adfs.domain.com                443        92E09233FF55F16A661AB417845C04FF3EC8F68E
      localhost                      443        92E09233FF55F16A661AB417845C04FF3EC8F68E
      certauth.adfs.domain.com       443        92E09233FF55F16A661AB417845C04FF3EC8F68E

   2. Locate the certificate thumbprint of the new HSM-backed SSL key (locate the object with the nCipher Security World Key Storage Provider and capture its Cert Hash(sha1) field for later use:

      certutil -silent -store my "adfs.domain.com"
      
      Serial Number: 610000000b29ee27dd2a24900c00000000000b
      Issuer: CN=DOMAIN ENTERPRISE ROOT CA, DC=domain, DC=com
      NotBefore: 9/17/2021 10:06 PM
      NotAfter: 9/17/2023 10:16 PM
      Subject: CN=adfs.domain.com
      Non-root Certificate
      Template: ADFSKeys, ADFS Keys
      Cert Hash(sha1): 6c4d3d71556303f42d5813d87836757a4a07f2ac
      Key Container = tq-ADFSKeys-8ca805b2-5e51-495f-a223-59d6fcf3c4db
      Provider = nCipher Security World Key Storage Provider
      Encryption test FAILED

   3. Set the certificate object to point to the new HSM-backed certificate:

      Set-AdfsSslCertificate -Thumbprint 6c4d3d71556303f42d5813d87836757a4a07f2ac
      
      WARNING: PS0344: ADFS is configured to use Alternate TLS client binding. This command will not modify Alternate TLS client binding. If you want to modify Alternate TLS client binding too, please use the cmdlet 'Set-AdfsAlternateTlsClientBinding'.

   4. Get the updated state of the certificate configuration - notice how the certauth object did not change, and there is a new object at port 49443 :

      Get-AdfsSslCertificate
      
      HostName                    PortNumber      CertificateHash
      --------                    ----------      ---------------
      certauth.adfs.domain.com        443         92E09233FF55F16A661AB417845C04FF3EC8F68E
      localhost                       443         6C4D3D71556303F42D5813D87836757A4A07F2AC
      adfs.domain.com                 443         6C4D3D71556303F42D5813D87836757A4A07F2AC
      adfs.domain.com                49443        6C4D3D71556303F42D5813D87836757A4A07F2AC

   5. To correct the certauth object, update the alternate TLS client binding (ignore the warning):

      Set-AdfsAlternateTlsClientBinding -Force $true -Member "certauth.adfs.domain.com" -Thumbprint "6c4d3d71556303f42d5813d87836757a4a07f2ac"
      
      Set-AdfsAlternateTlsClientBinding : PS0317: One or more of AD FS servers returned errors during execution of command 'Set-AdfsAlternateTlsClientBinding'. Error information: PS0316: AD FS Server: 'certauth.adfs.domain.com', Error: 'Connecting to remote server certauth.adfs.domain.com failed with the following error message : WinRM cannot process the request. The following error occurred while using Kerberos authentication: Cannot find the computer certauth.adfs.domain.com. Verify that the computer exists on the network and that the name provided is spelled correctly.
      For more information, see the about_Remote_Troubleshooting Help topic.'.
      At line:1 char:1
      + Set-AdfsAlternateTlsClientBinding -force $true -member "certauth.adfs ...
      + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
           + CategoryInfo          : NotSpecified: (:) [Set-AdfsAlternateTlsClientBinding], RemoteException
           + FullyQualifiedErrorId :
      RuntimeException,Microsoft.IdentityServer.Management.Commands.SetAlternateTlsClientBinding

   6. Get the updated state of the certificate configuration (all the certificate hashes should match now):

      Get-AdfsSslCertificate
      
      HostName                    PortNumber      CertificateHash
      --------                    ----------      ---------------
      certauth.adfs.domain.com        443         6C4D3D71556303F42D5813D87836757A4A07F2AC
      localhost                       443         6C4D3D71556303F42D5813D87836757A4A07F2AC
      adfs.domain.com                 443         6C4D3D71556303F42D5813D87836757A4A07F2AC
      adfs.domain.com                49443        6C4D3D71556303F42D5813D87836757A4A07F2AC

   7. Remove the new addition on port 49443 :

      netsh http delete sslcert hostnameport=adfs.domain.com:49443
      SSL Certificate successfully deleted

   8. Get the updated state of the certificate configuration (everything should look good now):

      Get-AdfsSslCertificate
      
      HostName                    PortNumber      CertificateHash
      --------                    ----------      ---------------
      certauth.adfs.domain.com        443         6C4D3D71556303F42D5813D87836757A4A07F2AC
      localhost                       443         6C4D3D71556303F42D5813D87836757A4A07F2AC
      adfs.domain.com                 443         6C4D3D71556303F42D5813D87836757A4A07F2AC

2. Navigate to Start > Windows Administrative Tools > AD FS Management .

3. Expand the ADFS folder and navigate to Service > Certificates .

4. Update the Service-Communications object to use the new HSM-backed certificate/key:

   1. Right-click on Certificates and select Set Service Communication Certificate .

   2. In the Select a service communication certificate screen, select More Choices and select the newly created HSM-based TLS certificate. You may have named it as AD FS TLS HSM Key .

   3. A dialog appears if the AD FS cannot determine the keyspec of the key. Select OK .

   4. A warning will pop up advising you to make sure the private key is accessible for each AD FS server, select OK .

      Note	All AD FS services in the cluster must contain the same keys/certificates, so you will need to copy the HSM key(s) to other AD FS systems in the cluster, restore their CNG linkage, and configure AD FS with those key(s). The procedures for performing this are not in scope of this Integration Guide .

   5. The new certificate should be visible in the middle pane; you can double-click on the certificate to view its properties.

5. Update the Token-Decrypting object to use the new HSM-backed certificate/key:

   1. Right-click on Certificates and select Add Token-Decrypting Certificate .

   2. In the Select a token-decrypting certificate screen, select More Choices and select the newly created HSM-based token-decrypting certificate and select OK You may have named it as AD FS Token-Decrypting HSM Key .

   3. A dialog appears if the AD FS cannot determine the keyspec of the key. Select OK .

   4. A warning will pop up advising you to make sure the private key is accessible for each AD FS server, select OK .

      Note	All AD FS services in the cluster must contain the same keys/certificates, so you will need to copy the HSM key(s) to other AD FS systems in the cluster, restore their CNG linkage, and configure AD FS with those key(s). The procedures for performing this are not in scope of this Integration Guide .

   5. The new certificate should be visible in the middle pane; you can double-click on the certificate to view its properties.

   6. In the middle pane, right-click on the new HSM token-decrypting certificate and select Set as Primary .

   7. Do NOT delete the original certificate (yet), which should now be marked as Secondary.

6. Update the Token-Signing object to use the new HSM-backed certificate/key:

   1. Right-click on Certificates and select Add Token-Signing Certificate .

   2. In the Select a token-signing certificate screen, select More Choices and select the newly created HSM-based token-signing certificate and select OK . You may have named this as AD FS Token-Signing HSM Key .

   3. A dialog appears if the AD FS cannot determine the keyspec of the key. Select OK .

   4. A warning will pop up advising you to make sure the private key is accessible for each AD FS server, select OK .

      Note	All AD FS services in the cluster must contain the same keys/certificates, so you will need to copy the HSM key(s) to other AD FS systems in the cluster, restore their CNG linkage, and configure AD FS with those key(s). The procedures for performing this are not in scope of this Integration Guide .

   5. The new certificate should be visible in the middle pane; you can double-click on the certificate to view its properties.

   6. In the middle pane, right-click on the new HSM token-signing certificate and select Set as Primary .

   7. When warned about setting this certificate as primary, select Yes .

      Note	Setting a new token-signing certificate as primary could break trust relationships with relying parties that do not yet have the certificate. If this is an existing AD FS infrastructure, make sure you coordinate this activity prior to performing this step.

   8. Do NOT delete the original certificate (yet), which should now be marked as Secondary.

7. Close the AD FS Management Console.

At this point, restart the AD FS Service:

1. Stop the AD FS service:

   net stop adfssrv

2. If preload is still running in pause mode in another window, go back to that window and use [CTRL]-[C] to break the pause and return back to the command prompt.

3. Clear the preload state:

   preload exit

4. Remove the NFAST_NFKM_TOKENSFILE cache:

   del c:\nfast_nfkm_tokensfile

5. Verify the preload cache is clear:

   nfkminfo -p
   
   <...snip all but last line...>
   
   No Pre-Loaded Objects

To restart AD FS, refer to the chosen HSM Key protection mechanism below for instructions:

1. For module protected HSM Keys:

   1. Stop the AD FS service via the command prompt as follows:

      net stop adfssrv

   2. Start the AD FS service via the command prompt as follows:

      net start adfssrv

2. For Softcard protected HSM Keys:

   1. Stop the AD FS service via command prompt as follows:

      net stop adfssrv
      
      preload exit
      
      del c:\nfast_nfkm_tokensfile

   2. Start the AD FS service via command prompt as follows:

      preload --reload-everything --softcard-name=<Softcard name> net start adfssrv

3. For OCS protected HSM Keys:

   1. Stop the AD FS service via the command prompt as follows:

      net stop adfssrv
      
      preload exit
      
      del c:\nfast_nfkm_tokensfile

   2. Start the AD FS service via command prompt as follows:

      preload --reload-everything --cardset-name=<OCS Name> net start adfssrv

Log into the AD FS web page to ensure the service is working properly. Similar to the steps followed in the previous section, log into the AD FS web page at https://adfs.domain.com/adfs/ls/idpinitiatedsignon.aspx - the log in process should be successful.

1. Open a PowerShell window and execute the following command(s):

   Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -force
   Install-Module -Name ADFSToolbox -force
   Import-Module ADFSToolbox -force
   Export-AdfsDiagnosticsFile -ServerNames @("adfs.domain.com")

2. Navigate to the following: https://adfshelp.microsoft.com/diagnosticsanalyzer/Analyze

3. Upload the resulting JSON from the Export-AdfsDiagnosticsFile command and analyze the results.

• If you are using preload to start AD FS, the NFAST_NFKM_TOKENSFILE system environment variable must have been previously configured or AD FS will not start/work properly.

• If you receive the following error when performing any HSM operation (including AD FS service start), then the NFAST_NFKM_TOKENSFILE ( c:\nfast_nfkm_tokensfile ) has gone stale from not cleaning up properly:

  HH:MM:SS WARNING: NFastApp_Connect failed: ClientUnknown
  error setting application: ClientUnknown

  Make sure any services that were using preload have been stopped, delete the file referenced in NFAST_NFKM_TOKENSFILE and try running the HSM command again.

  To avoid seeing this error, make sure you run preload exit after stopping the service using the preloaded HSM keys.

1. Stop the AD FS service.

2. Run the preload command from the previous section for your particular HSM configuration, but use preload with pause instead of net start adfssrv .

3. Navigate to Start > Run and enter certlm.msc then select OK .

4. Expand Certificates - Local Computer > Personal > Certificates .

5. Right-click on the AD FS TLS key generated on the HSM and navigate to All Tasks > Manage Private Keys .

6. In the Permissions for screen, select Add .

7. Select Object Types and then check the boxes for Service Accounts and Computers from the listed objects.

8. Select OK .

9. For Enter the object names to select , type in full/partial names for (separated by semicolons). That is, the Group Managed Service Account you created on your domain controller, and the AD FS server computer account(s).

10. Select Check Names to auto-complete (you may need to select Advanced to narrow down your search in large domains).

11. Select OK .

12. Back in the Permissions for…​ window, for each added account/computer ensure that Full control and Read are both checked in the Allow column.

13. Select OK to close the Permissions for…​ window.

14. Close the Certificates - Local Computer window.

15. Cancel the preload window with [CTRL]+[C] .

16. Delete the c:\nfast_nfkm_tokensfile .

17. Resume whatever you were doing before.