Microsoft AD FS
This guide is designed to assist security administrators in integrating Microsoft Active Directory Federation Services (AD FS) with Thales Luna HSM devices or Luna Cloud HSM services. By securely offloading cryptographic operations—such as key generation, encryption, decryption, and signing—from the AD FS Server to the Luna HSM, the integration not only enhances system performance but also fortifies security. Offloading these operations frees up the AD FS Server to focus on managing authentication requests more efficiently, reducing the overall processing load and improving response times.
From a cybersecurity perspective, this integration significantly strengthens the security posture by isolating and protecting high-value cryptographic keys (such as token signing, decrypting, and TLS keys) within a dedicated, FIPS 140-2 certified hardware security module. This mitigates the risk of key compromise by preventing the keys from being exposed on the AD FS Server, reducing the attack surface, and ensuring that sensitive cryptographic operations occur within a tamper-resistant environment.
Key benefits of integrating Microsoft AD FS with Luna HSM devices or Luna Cloud HSM services include:
-
Secure generation, storage, and protection of the identity signing private keys using either FIPS 140-2 or FIPS 140-3 Level 3 validated hardware.
-
Full life cycle management of the keys to ensure their integrity and reliability throughout their usage.
-
Maintenance of a comprehensive HSM audit trail for transparency and accountability in key operations. It's important to note that Luna Cloud HSM service does not have access to this secure audit trail.
-
Significant performance enhancements by offloading cryptographic operations from application servers.
Supported Platforms
This integration has been tested and verified on the following platforms:
| HSM Type | Platform Tested |
|---|---|
| Luna HSM | Windows Server 2019 |
| Luna Cloud HSM | Windows Server 2019 |
Prerequisites
The prerequisites for this integration are:
Set up Microsoft AD FS
This procedure outlines the steps to set up Microsoft AD FS using a Windows Server as a Domain Controller and Certificate Authority (CA), and another as a Federation and Web Server. Follow these instructions to create the necessary Group Managed Service Account (gMSA) and configure the AD FS service for your domain.
Set up the following machines for the AD FS installation:
-
A Windows server acting as a domain controller and CA.
-
A Windows server serving as the federation server and Web server.
Ensure that Active Directory Domain Services (AD DS) are installed on the domain controller machine, and the AD FS/Web server has joined the domain. In this guide, we are using contoso.com as the domain.
Denote the machines used in the setup as follows:
-
ADFSCA: Domain controller and CA machine.
-
ADFSWEB: AD FS and Web server machine.
Create a Group Managed Service Account (gMSA) that will be used to run the AD FS service. Perform the following steps on the AD DS (domain controller) machine:
a. Open PowerShell as an Administrator to execute the commands.
b. Create a Key Distribution Services (KDS) Root Key so that Domain Controllers can begin generating gMSA passwords:
PS C:\> Add-KdsRootKey -EffectiveTime ((get-date).addhours(-10))
c. Create the Group Managed Service Account to run the AD FS service:
PS C:\> New-ADServiceAccount adfsgMSA -DNSHostName adfsweb.contoso.com -ServicePrincipalNames http/adfsweb.contoso.com
d. Set the Service Principal Name (SPN) for the AD FS service:
PS C:\> setspn -s http/adfsweb.contoso.com contoso.com\adfsgMSA
The gMSA account created here must be registered with SafeNet KSP later when configuring the Key Storage Provider (KSP).
Set up Luna HSM
You need to set up either On-Premise Luna HSM or Luna Cloud HSM.
Set up On-Premise Luna HSM
Follow these steps to set up your on-premise Luna HSM:
Ensure that the HSM is set up, initialized, provisioned, and ready for deployment. For more information, refer to Luna HSM documentation.
Create a partition that will be later on used by Microsoft AD FS.
Create and exchange certificate between the Luna Network HSM and client system. Register client and assign partition to create an NTLS connection.
Initialize Crypto Officer and Crypto User roles for the registered partition.
Run the following command to verify that the partition has been successfully registered and configured:
C:\Program Files\SafeNet\LunaClient>lunacm.exe
Upon successful execution, you should observe an output similar to the example provided below:
lunacm.exe (64-bit) v10.7.1-125. Copyright (c) 2024 Thales Group. All rights reserved. Available HSMs: Slot Id -> 0 Label -> TPA01 Serial Number -> 1312109862218 Model -> LunaSA 7.7.1 Firmware Version -> 7.7.1 Bootloader Version -> 1.1.2 Configuration -> Luna User Partition With SO (PW) Key Export With Cloning Mode Slot Description -> Net Token Slot FM HW Status -> Non-FM Current Slot Id: 0
Refer to Luna HSM documentation for detailed steps on creating NTLS connection, initializing the partitions, and assigning various user roles.
Set up Luna HSM in High Availability Mode
Refer to Luna HSM documentation for High Availability (HA) steps and details regarding configuring and setting up two or more HSM boxes on host systems. You must enable the HAOnly setting in HA for failover to work so that if the primary goes down due to any reason, all calls get automatically routed to the secondary until the primary recovers and starts up.
This integration been tested using Luna Client in both HA and FIPS-compliant modes.
Set up Luna Cloud HSM
The following steps are applicable for setting up the Luna Cloud HSM on a Windows environment:
Transfer the downloaded .zip file to your client workstation using pscp, scp, or other secure means
Extract the .zip file into a directory on your client workstation.
Extract or untar the appropriate client package for your operating system. Do not extract to a new subdirectory; place the files in the client install directory.
cvclient-min.zip
Run the setenv script to generate a new configuration file with the necessary information for the Luna Cloud HSM service. Right-click setenv.cmd and select Run as Administrator.
To add the configuration to an already installed UC client, use the –addcloudhsm option when running the setenv script.
Run the LunaCM utility and verify that the Cloud HSM service is listed.
If your organization requires non-FIPS algorithms for your operations, ensure that the Allow non-FIPS approved algorithms check box is checked. For more information, refer to Supported Mechanisms.
Integrating Luna HSM with Microsoft Active Directory Federation Services
To successfully integrate Microsoft AD FS with Luna HSM or Luna Cloud HSM, follow these key steps:
Configure SafeNet Key Storage Provider
Install AD CS using SafeNet KSP
Set up your CA to issue AD FS certificates through SafeNet KSP
Configure and enroll your AD FS TLS certificate to secure communications
Install and configure AD FS to ensure proper integration with Luna HSM
Verify that AD FS is fully operational and correctly integrated with Luna HSM
Before beginning the integration, it is recommended to get acquainted with Microsoft AD FS. Refer to the Microsoft AD FS documentation for detailed information.
Configure SafeNet Key Storage Provider
The SafeNet Key Storage Provider (KSP) must be configured on both ADFSCA (for securing the certificate authority signing keys on Luna HSM) and ADFSWEB to enable the necessary user accounts and systems to access the Luna HSM or Luna Cloud HSM service. Follow these steps to configure SafeNet KSP:
Log in to both ADFSCA and ADFSWEB as a domain administrator.
Navigate to the <Luna HSM Client Installation Directory>/KSP directory. If using the Luna Cloud HSM service, the /KSP folder is included in the service client package.
Launch the KSP configuration wizard by double-clicking the KspConfig.exe file.
Access the Security Library by double-clicking Register or View Security Library in the left pane.
Register the Cryptographic Library by clicking Browse, navigating to the Luna HSM Client installation directory, and selecting cryptoki.dll. Then, click Register. If using Luna Cloud HSM, the cryptographic libraries are in the service client package.
Confirm successful registration with the message: Success registering the security library!
Register HSM Slots by double-clicking Register HSM Slots in the left pane.
Select the logged-in user and enter the Slot Password.
Register the user slot for User \ Domain by clicking Register Slot. A message will confirm successful registration: The slot was successfully and securely registered!
Repeat the slot registration process for SYSTEM \ NT AUTHORITY.
Confirm successful registration with the message: The slot was successfully and securely registered!
Close the KSP configuration wizard.
Register the gMSA account on ADFSWEB by registering the slot for the ADFS gMSA account created during the AD FS setup. This step is required only on the ADFSWEB system where AD FS will run.
Steps 13 and onward apply only to the ADFSWEB system where the AD FS service is being set up.
Navigate to the <Luna HSM Client Installation Directory>/KSP directory. If using Luna Cloud HSM, the /KSP folder is in the service client package.
Double-click the KspConfig.exe file to launch the KSP configuration wizard.
Double-click Register HSM Slots on the left side of the pane.
Enter the gMSA account name in the User section. Enter the Slot Password.
Click Register Slot to register the slot. Upon successful registration, the following message will appear on screen: The slot was successfully and securely registered!
Close the KSP configuration wizard and restart the ADFSWEB system.
Install AD CS using SafeNet KSP
Active Directory Certificate Services (AD CS) can be installed using Microsoft's Key Storage Provider, but it is recommended to use a Luna HSM for securing Certificate Authority (CA) signing keys. To install Microsoft AD CS and secure the signing keys with Luna HSM, follow these steps:
Log in to ADFSCA as an Enterprise Admin or Domain Admin with administrative privileges.
Open Server Manager and click Add Roles and Features.
Click Next when the Add Roles and Features wizard appears.
Select the Role-based or feature-based installation option and click Next.
Select the Select a server from the server pool option and choose your server from the Server Pool menu.
Click Next and select the Active Directory Certificate Services check box.
A prompt will appear asking if you want to add the required features for Active Directory Certificate Services. Click Add Features to confirm.
Click Next to proceed.
Click Next on the Features page to continue.
Click Next on the AD CS page to continue.
Select the Certification Authority check box from the Role Services list and click Next.
Click Install.
After installation is complete, click Configure Active Directory Certificate Services on the destination server to open the AD CS Configuration wizard.
Click Next on the Credentials page of the AD CS Configuration wizard to continue.
Select the Certification Authority check box in Role Services and click Next.
Select the Enterprise CA radio button and click Next.
Select the Root CA radio button and click Next.
Select the Create a new private key radio button and click Next.
Click the Select a cryptographic provider drop-down menu and choose RSA#SafeNet Key Storage Provider. Select the key length, for example, 2048.
Choose the hash algorithm for signing certificates issued by this Certificate Authority; for example, select SHA256 as the desired hash algorithm.
Click Next.
Enter a common name to identify this Certificate Authority and click Next.
Set the Certificate Validity Period, then click Next. Configure the location of the Certificate database, which stores all certificate requests, issued certificates, and records of revoked or expired certificates. Click Next to proceed.
Click Configure to apply the selected roles, role services, or features.
Click Close to exit the AD CS Configuration wizard after viewing the installation results. A private key for the CA will be generated and stored on the Luna HSM.
Set up your CA to issue AD FS certificates through SafeNet KSP
Follow the steps below to configure a CA to create a certificate template and issuing properties for AD FS server certificates.
Log in to ADFSCA as a domain administrator.
Select Run from the Start menu. Type certtmpl.msc and hit Enter. The Certificate Templates Console dialog box will appear.
Expand the Certificate Templates snap-in under Console Root. View all available certificate templates in the middle section and update the template that your CA will issue.
Scroll down to locate the Web Server template.
Right-click on the Web Server template and select Duplicate Template from the options that appear.
In the Compatibility tab, select Windows Server 2016 Enterprise and set the Certificate Recipient to Windows 10/Windows Server 2016 Enterprise.
Click on the General tab.
Enter the Template Display Name, such as ADFS Server.
Select Publish certificate in Active Directory.
Click on the Cryptographic tab and select Key Storage Provider in the Provider Category.
Select the Request can use any CSP available on subject’s computer option.
Click on the Request Handling tab. In the Purpose field, select Signature and encryption.
Select Authorize additional service accounts to access the private key.
Click on Key Permissions… and then click Add….
Click on Object Types…, select Service Accounts and Computers, and then click OK.
Type the gMSA service account name and the ADFS service computer name, then click Check Names.
Click OK. In the Permissions for accounts section, select Full Control in Allow for both the gMSA account and ADFSWEB, then click OK.
Click on the Security tab and click Add.
Type NETWORK SERVICE and click OK.
Click on NETWORK SERVICE in the Group or user names area.
Ensure that the Read and Enroll check boxes are selected in the Permissions area.
Similarly, add and provide Read and Enroll permissions to the following members: Domain Computers, Domain Controllers, NETWORK SERVICE, and IIS_IUSRS.
Provide Read, Write, and Enroll permissions for Domain Admins and Enterprise Admins by selecting the respective check boxes.
Click Apply, then click OK. Close the Certificate Template Console.
From the Start menu, select Control Panel > Administrative Tools > Certification Authority.
Expand the CA in the console tree. Look for the computer icon with a green tick next to it.
In the Certification Authority snap-in's console tree, right-click Certificate Templates, and then select New Certificate Templates to Issue.
In the Enable Certificates Templates window, choose the ADFS Server or the other configured certificate template, and click OK to confirm your selection.
Open Certificate Templates in the Certification Authority and verify that the modified certificate templates appear in the list.
Stop and start the Certificate Authority.
Configure and enroll your AD FS TLS certificate to secure communications
To secure communication between your AD FS server and clients, follow the steps below to configure and enroll the AD FS TLS certificate:
Log on to ADFSWEB as a domain administrator.
Select Run from the Start menu.
Type mmc in the Run dialog box and click OK.
When the MMC console appears, select File > Add/Remove Snap-in….
In the Add or Remove Snap-Ins dialog box, select the Certificates snap-in from the Available snap-ins section.
Click Add >>, select Computer Account, and click Next.
Select Local Computer and click Finish.
Click OK and expand Certificates under Console Root.
Right-click the Personal folder and select All Tasks > Request New Certificate….
Click Next, select Active Directory Enrollment Policy, and then click Next. The configured certificate template will be displayed.
Click Details, then select Properties.
Select the Subject tab when the Certificate Properties window appears.
Choose Common Name from the Type dropdown in the Subject Name section. Enter the system's fully qualified domain name, such as ADFSWEB.contoso.com, in the Value field. Click Add and repeat as necessary to add additional values.
Select DNS from the Type dropdown in the Alternative Name section. Enter the following values in the Value field:
-
ADFSWEB.contoso.com: Fully qualified domain name of the AD FS Server.
-
certauth.ADFSWEB.contoso.com: A DNS name used by the AD FS server to authenticate certificate-based authentication requests.
Click the General tab and provide the Friendly Name. For example: ADFS TLS Cert.
Click the Private Key tab and under Cryptographic Service Provider, select RSA, SafeNet Key Storage Provider. Ensure all other providers are deselected.
Click the Certificate Authority tab and ensure that Enterprise Root CA is selected.
Click Apply, then click OK.
Select the AD FS certificate template or the configured template, and click Enroll.
Wait for the enrollment process to complete. When it succeeds, click Finish.
Close the certificate console.
Install and configure AD FS to ensure proper integration with Luna HSM
To install and configure Active Directory Federation Services (AD FS) on your server, follow these steps:
Log in to ADFSWEB as a domain administrator.
Open Server Manager. In the Quick Start tab on the Welcome tile of the Dashboard page, click Add roles and features. Alternatively, click Add Roles and Features on the Manage menu.
Click Next on the Before you begin page.
Select Role-based or Feature-based installation on the Select installation type page, and click Next.
Select Select a server from the server pool, verify the target computer is selected, and click Next on the Select destination server page.
Click Active Directory Federation Services on the Select server roles page, and then click Next.
Click Next on the Select features page. The required prerequisites are preselected.
Click Next on the Active Directory Federation Service (AD FS) page.
Verify the information on the Confirm installation selections page, and click Install.
On the Dashboard page of Server Manager, click the Notifications flag, and then click Configure the federation service on the server.
Open the Active Directory Federation Service Configuration Wizard.
Select Create the first federation server in a federation server farm on the Welcome page, and click Next.
Enter domain administrator credentials for the Active Directory (AD) domain to which this computer is joined on the Connect to AD DS page, and click Next.
On the Specify Service Properties page:
-
Select the certificate configured for AD FS TLS using SafeNet Key Storage Provider.
-
Enter a name for the federation service, such as adfsweb.contoso.com, ensuring it matches one of the Subject or Subject Alternative Names in the certificate.
-
Provide a display name for the federation service that will appear on the sign-in page.
-
Click Next.
Select Use an existing domain user account or group Managed Service Account on the Specify Service Account page. Click Select…, and specify the gMSA account provisioned to access the SafeNet Key Storage Provider during AD FS setup. Click Next.
Specify an AD FS configuration database on the Specify Configuration Database page, then click Next. You can either select Create a database on this computer using Windows Internal Database or specify the location and instance name of an existing Microsoft SQL Server Database, if configured.
Verify your configuration selections on the Review Options page, and then click Next.
Ensure all prerequisite checks are completed successfully on the Pre-requisite Checks page, then click Configure.
Check the Results page to confirm whether the configuration has been completed successfully, then click Next steps required for completing your federation service deployment.
Click Close to exit the configuration wizard.
Restart the ADFSWEB server.
Enroll and configure AD FS for token signing and decrypting certificates, ensuring secure authentication
In this procedure, you will enroll and configure Active Directory Federation Services (AD FS) for token signing and token decryption certificates. The initial token-decryption and token-signing certificates created by the AD FS role configuration are software-based and self-signed. We have previously configured the TLS certificate to use a Luna HSM-backed private key for SSL. Follow the steps below to configure new token decryption and token signing certificates using keys generated on the Luna HSM:
Log on to ADFSWEB as a domain administrator.
Select Run from the Start menu.
Type mmc in the Run dialog box, and click OK.
Select File > Add/Remove Snap-in… when the MMC console appears on the screen.
Select the Certificates snap-in from the Available snap-ins section in the Add or Remove Snap-Ins dialog box.
Click Add>>, select Computer Account, and click Next.
Select Local Computer, and click Finish.
Click OK and expand the Certificates under Console Root.
Right-click the Personal folder and select All Tasks > Request New Certificate…
Click Next, select Active Directory Enrollment Policy, and then click Next. The certificate template that you’ve configured will be displayed.
Click on Details and then Properties.
Select the Subject tab in the Certificate Properties window that appears on the screen.
In the Subject Name section, choose Common Name and enter the values for AD FS token signing/encryption along with the fully qualified domain name of the computer where you are installing the certificate in the Value field:
-
For Token Signing: ADFS Token Signing - ADFSWEB.contoso.com
-
For Token Decrypting: ADFS Token Encryption - ADFSWEB.contoso.com
Click Add to include the value. Repeat this step to add additional values, if necessary.
Click the General tab and provide a Friendly Name:
-
For the signing certificate: ADFS Signing
-
For the decrypting certificate: ADFS Decryption
Click the Private Key tab, and under Cryptographic Service Provider, select RSA, SafeNet Key Storage Provider. Ensure that all other listed providers are deselected.
Click the Certificate Authority tab and verify that Enterprise Root CA is selected.
Click Apply, then OK.
Select the AD FS certificate template or the configured certificate template and click Enroll.
Wait for the enrollment process to complete, then click Finish.
Ensure that both ADFS token signing and token decrypting certificates have been created successfully.
Close the certificate console.
Open the PowerShell command prompt as an Administrator. Run the following command to check the ADFS TLS certificate:
PS C:\> Get-AdfsSslCertificate
Copy the CertificateHash and run the following command to confirm that the TLS certificate is using the SafeNet Key Storage Provider:
PS C:\> certutil -verifystore My [CertificateHash]
To replace the Token Signing and Encryption certificate with the newly generated certificates, run the following command:
PS C:\> Set-AdfsProperties -AutoCertificateRollover $false
Navigate to Start > Windows Administrative Tools > AD FS Management.
Expand the ADFS folder and navigate to Service > Certificates.
Update the Token Signing certificate to use the new Luna HSM backed certificate/key:
a. Right-click on Certificates and select Add Token-Signing Certificate…
b. In the Select a token-signing certificate screen, click More choices and select the newly created HSM-based token signing certificate, then click OK. In this demonstration, we have named it ADFS Signing.
c. A warning will pop up advising you to ensure that the private key is accessible for each AD FS server; select OK.
d. The new certificate should be visible in the middle pane. Double-click on the certificate to view its properties.
e. In the middle pane, right-click on the new HSM token signing certificate and select Set as Primary.
f. You can delete the original certificate, which should now be marked as Secondary.
Update the Token Decrypting certificate to use the new Luna HSM backed certificate/key:
a. Right-click on Certificates and select Add Token-Decrypting Certificate….
b. In the Select a token-decrypting certificate screen, click More choices and select the newly created HSM-based token decrypting certificate, then click OK. In this demonstration, we have named it ADFS Decryption.
c. A warning will pop up advising you to ensure that the private key is accessible for each AD FS server; select OK.
d. The new certificate should be visible in the middle pane. Double-click on the certificate to view its properties.
e. In the middle pane, right-click on the new HSM token decrypting certificate and select Set as Primary.
f. You can delete the original certificate, which should now be marked as Secondary.
Close the AD FS Management Console.
Navigate to Start > Windows Administrative Tools > Computer Management.
In the left pane, expand Local Users and Groups. Double-click on Groups to display all local groups.
Locate the Administrators group. Right-click on it and click Add to Group….
In the Properties window, click Add… and then enter the gMSA account that is running the AD FS Service.
Click Check Names and then OK to add the gMSA account to the Local Administrator group.
Click Apply and then OK. Close the Computer Management Console.
Restart the AD FS Service by running the following command in the PowerShell command prompt:
PS C:\> net stop adfssrv PS C:\> net start adfssrv
Ensure that the PowerShell command prompt is launched as an Administrator.
Navigate to Start > Windows Administrative Tools > AD FS Management.
Expand the ADFS folder and navigate to Service > Certificates.
Double-click the Token signing or decrypting certificate to open the certificate properties. Copy the certificate Thumbprint.
Run the following command in the PowerShell command prompt to verify the certificate is using SafeNet Key Storage Provider:
PS C:\> certutil -verifystore My [Thumbprint]
Close the PowerShell command prompt and AD FS Management console.
Verify that AD FS is operational.
Verify that AD FS is fully operational and correctly integrated with Luna HSM
After configuring AD FS to use Luna HSM for securing TLS, Token Signing, and Token Decrypting keys, it is essential to verify that the AD FS server is functioning correctly. This procedure will guide you through the steps to confirm that your federation server is operational and properly utilizing the SafeNet Key Storage Provider on Luna HSM for key access. Follow the steps below to complete the verification.
Open a browser and in the address bar, type the federation server name, appending it with /federationmetadata/2007-06/federationmetadata.xml to browse to the federation service metadata endpoint. For example: https://adfsweb.contoso.com/federationmetadata/2007-06/federationmetadata.xml
Ensure that your browser is configured to trust the federation server role by adding your federation service name (e.g., https://adfsweb.contoso.com) to the browser’s local intranet zone.
Verify that the federation server metadata is displayed without any Secure Socket Layer (SSL) errors or warnings in the browser window. This confirms that your federation server is operational.
Enable the AD FS sign-on page for verification by opening PowerShell as an Administrator and running the following command:
PS C:\> Set-AdfsProperties -EnableIdPInitiatedSignonPage $true
Open a browser and in the address bar, type the federation server name, appending it with /adfs/ls/idpinitiatedsignon.aspx to access the AD FS sign-on page. For example: https://adfsweb.contoso.com/adfs/ls/idpinitiatedsignon.aspx
Click on Sign in on the AD FS sign-in screen, provide your credentials, and click Sign in again.
Confirm that a message "You are signed in" is displayed, verifying that AD FS is operational and using the SafeNet Key Storage Provider for accessing the keys secured on the Luna HSM.
