Procedures

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

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

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>

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

Configure the AD FS Service Principal Name (SPN):

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

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

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!

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

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

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

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

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

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

Change the Validity Period to whatever value is desired.

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

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.

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

Select Key Permissions.

In the Permissions for screen, select Add.

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

Select OK.

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

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

Select OK to add into Enter the object names.

Select OK.

Select Allow Full Control.

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

Select OK to close the Permissions for window.

Select the Cryptography tab. On this tab:

Select the Security tab. On this tab:

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:

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

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

Issue the new certificate template to the current CA:

Close the Certification Authority management console.

Sign in to the Windows workstation as an administrator.

Navigate to the location of the Security World software.

Install the Security World software:

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

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.

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.

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)

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

Run the command:

enquiry

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.

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.

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.

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.

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

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

At the Software Installation screen, select Next.

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

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>

On the start menu select Next.

Select Next on the Enable HSM Pool Mode Screen.

Select Next on the Initial Set Up Screen.

Select Next on the Set Module States Screen.

Select Module Protection.

Select Next on the Software Installation Screen.

Select Finish.

Reboot the server.

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

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

The Certificate Enrollment wizard will start, select Next.

On the Select Certificate Enrollment Policy screen, select Next.

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.

On the Certificate Properties window, in the Subject tab:

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

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.

Select OK to close the Certificate Properties window.

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

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

For OCS select Operator Card Set protection and select Next.

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

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

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

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

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

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

Verify the new HSM keys:

Open Server Manager.

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

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

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

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.

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

On the Select features page, select Next.

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

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

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

Once the installation has completed, select Close.

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

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

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.

On the Specify Service Properties window:

On the Specify Service Account page:

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

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

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

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

You may be informed that a machine restart is required.

Select Close to exit the configuration.

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.

Ensure the AD FS service is stopped.

net stop adfssrv

Ensure any existing preload cache is reset.

preload exit

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

del c:\nfast_nfkm_tokensfile

Preload the keys into the HSM if necessary:

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

net start adfssrv

Open Internet Explorer.

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

Add the web page to Trusted Sites:

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

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

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

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

Run the following command:

> Set-AdfsProperties -AutoCertificateRollover $false

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

Open a PowerShell as administrator, create a container for the ms capi (ncipher CSP) key:

 cd "c:\program files\ncipher\nfast\bin"

 keytst -c -m adfstokendecrypt

 CSP being used: nCipher Enhanced Cryptographic Provider

 Container 'adfstokendecrypt' created

List all of the containers:

csputils -U ALL -m

File ID    Container name       Container owner      DLL name   S X
=========  ===================  ===================  =========  = =
cb551513e  adfstokendecrypt     MACHINE              ncsp

1 container and 0 keys found.

Find the container you just created by name and go to the left hand column and get the FILEID of that container.

To find your ADFS Token-Decrypting Key IDENT value, for example, key_caping-machine-IDENT, run:

nfkminfo -l

Keys with module protection:
 key_caping_machine--0e29b54e36c1a2006981a7a8ca6234fd6cf15bed `te-ADFSTLS-dc716c04-87e1-417e-9ec6-5fb9928de1fc'
 key_caping_machine--2c21df63f288ed189ef4f1e6af9b781ae2c6c031 `te-ADFSTLS-1d0559b1-2759-4645-991c-8d7838097e6a'
 key_caping_machine--5d9f162dec839f3e4250af803fb0a81415359ed1 `te-ADFSTLS-9b36d23f-397a-48a2-adc4-f03888c145d9'

Now run the following command and type yes if prompted, see the next line for an example:

cspimport -i -k machine--IDENT -a caping FILEID exchange

Now we have the key imported into the CSP container as a machine and exchange key.

Move the original ADFS Token-Decrypting Key key-caping-machine out of C:\ProgramData\nCipher\Key Management Data\local or else it will continue to use CNG. The new CAPI container and cloned key should remain in local.

Run the following command:

 certutil -store my

================ Certificate 3 ================
Serial Number: 18000000047adbec8d4cc951f5000000000004
Issuer: CN=ADFSWIN2022-3, DC=interop, DC=local
 NotBefore: 7/30/2024 8:26 AM
 NotAfter: 7/30/2026 8:26 AM
Subject: CN=ADFS Token-Decrypting Key
Non-root Certificate
Template: ADFSTLS, ADFS TLS
Cert Hash(sha1): 03a19f17154193a70231c19dcdf64f91c496cf8e
  Key Container = te-ADFSTLS-d223bf5d-ab52-4753-a401-06f82de95711
  Provider = nCipher Security World Key Storage Provider
Private key is NOT exportable
ERROR: Could not verify certificate public key against private key
CertUtil: -store command completed successfully.

Get the signing cert Serial Number from the above command and use it in the next command.

certutil -f -repairstore -csp "nCipher Enhanced Cryptographic Provider" my "18000000047adbec8d4cc951f5000000000004"

. my "Personal"
================ Certificate 3 ================
Serial Number: 18000000047adbec8d4cc951f5000000000004
Issuer: CN=ADFSWIN2022-3, DC=interop, DC=local
 NotBefore: 7/30/2024 8:26 AM
 NotAfter: 7/30/2026 8:26 AM
Subject: CN=ADFS Token-Decrypting Key
Non-root Certificate
Template: ADFSTLS, ADFS TLS
Cert Hash(sha1): 03a19f17154193a70231c19dcdf64f91c496cf8e
cbData: 14 ==> 40
  Key Container = adfstokensign
  Provider = nCipher Enhanced Cryptographic Provider
Private key is NOT exportable
ERROR: Could not verify certificate public key against private key
nCipher Enhanced Cryptographic Provider: KeySpec=1
AES256+RSAES_OAEP(RSA:AT_KEYEXCHANGE) test passed
================ Begin force NCrypt ================
Private key is NOT exportable
ERROR: Could not verify certificate public key against private key
nCipher Security World Key Storage Provider: KeySpec=0
AES256+RSAES_OAEP(RSA:CNG) test passed
----------------  End force NCrypt  ----------------
CertUtil: -repairstore command completed successfully.

Now the ADFS Decrypting Certificate is linked to the key in the MS CAPI nCipher provider.

For the Decryption Certificate you should see "Provider = nCipher Enhanced Cryptographic Provider" when you run the below command:

 certutil -store my

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

Expand the ADFS folder and navigate to Service > Certificates.

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

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

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

Close the AD FS Management Console.

Stop the AD FS service:

net stop adfssrv

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 to the command prompt.

Clear the preload state:

preload exit

Remove the NFAST_NFKM_TOKENSFILE cache:

del c:\nfast_nfkm_tokensfile

Verify the preload cache is clear:

nfkminfo -p

<...snip all but last line...>

No Pre-Loaded Objects

For module protected HSM Keys:

For Softcard protected HSM Keys:

For OCS protected HSM Keys: