Federated Authentication Service private key protection 编辑

Introduction

Certificates are stored in the registry on the FAS server. The associated private keys are stored by means of the Network Service account of the FAS server and marked as non-exportable by default.

There are two types of private keys:

• The private key associated with the registration authority (RA) certificate, from the Citrix_RegistrationAuthority certificate template.
• The private keys associated with the user certificates, from the Citrix_SmartcardLogon certificate template.

There are actually two RA certificates: Citrix_RegistrationAuthority_ManualAuthorization (valid for 24 hours by default) and Citrix_RegistrationAuthority (valid for two years by default).

During step 3 of the Initial Setup in the FAS administration console, when the administrator clicks “Authorize” the FAS server generates a keypair and sends a Certificate Signing Request (CSR) to the CA for the Citrix_RegistrationAuthority_ManualAuthorization certificate. This is a temporary certificate, valid for 24 hours by default. The CA does not automatically issue this certificate; its issuance must be manually authorised on the CA by an administrator. Once the certificate is issued to the FAS server, FAS uses the Citrix_RegistrationAuthority_ManualAuthorization certificate to automatically obtain the Citrix_RegistrationAuthority certificate (valid for two years by default). The FAS server deletes the certificate and key for Citrix_RegistrationAuthority_ManualAuthorization as soon as it obtains the Citrix_RegistrationAuthority certificate.

The private key associated with the RA certificate is particularly sensitive, because the RA certificate policy allows whoever possesses the private key to issue certificate requests for the set of users configured in the template. As a consequence, whoever controls this key can connect to the environment as any of the users in the set.

You can configure the FAS server to protect private keys in a way that fits your organization’s security requirements, using one of the following:

• Microsoft Enhanced RSA and AES Cryptographic Provider or Microsoft Software Key Storage Provider for both the RA certificate and the user certificates’ private keys.
• Microsoft Platform Key Storage Provider with a Trusted Platform Module (TPM) chip for the RA certificate’s private key, and Microsoft Enhanced RSA and AES Cryptographic Provider or Microsoft Software Key Storage Provider for the user certificates’ private keys.
• A Hardware Security Module (HSM) vendor’s Cryptographic Service or Key Storage Provider with the HSM device for both the RA certificate and the user certificates’ private keys.

Private key configuration settings

Configure FAS to use one of the three options. Use a text editor to edit the Citrix.Authentication.FederatedAuthenticationService.exe.config file. The default location of the file is in the Program Files\Citrix\Federated Authentication Service folder on the FAS server.

The FAS reads the config file only when the service starts. If any values are changed, the FAS must be restarted before it reflects the new settings.

Set the relevant values in the Citrix.Authentication.FederatedAuthenticationService.exe.config file as follows:

Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.ProviderLegacyCsp (switch between CAPI and CNG APIs)

Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.ProviderName (name of the provider to use)

Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.ProviderType (Required only in case of CAPI API)

Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.KeyProtection (When FAS needs to perform a private key operation, it uses the value specified here) Controls the “exportable” flag of private keys. Allows the use of TPM key storage, if supported by the hardware.

Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.KeyLength (Specify size of private key in bits)

The config file settings are represented graphically as follows (installation defaults are shown in red):

Configuration scenario examples

Example 1

This example covers the RA certificate private key and user certificates’ private keys stored using the Microsoft Software Key Storage Provider

This is the default post-install configuration. No additional private key configuration is required.

Example 2

This example shows the RA certificate private key stored in the FAS server motherboard’s hardware TPM via the Microsoft Platform Key Storage Provider, and user certificates’ private keys stored using the Microsoft Software Key Storage Provider.

This scenario assumes that the TPM on your FAS server motherboard has been enabled in the BIOS according to the TPM manufacturer’s documentation and then initialized in Windows; see https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-vista/cc749022(v=ws.10)?redirectedfrom=MSDN
.

Using PowerShell (recommended)

The RA certificate can be requested offline using PowerShell. This is recommended for organizations that do not want their CA to issue a RA certificate through an online CSR. An offline RA CSR cannot be made using the FAS administration console.

Step 1: During the initial setup of the FAS configuration using the administration console, complete only the first two steps: “Deploy certificate templates” and “Setup Certificate Authority.”

Step 2: On your CA server, add the Certificate Templates MMC snap-in. Right-click the Citrix_RegistrationAuthority_ManualAuthorization template and select Duplicate Template.

Select the General tab. Change the name and validity period. In this example, the name is Offline_RA and the validity period is 2 years:

Step 3: On your CA server, add the CA MMC snap-in. Right-click Certificate Templates. Select New, then click Certificate Template to Issue. Choose the template you just created.

Step 4: Load the following PowerShell cmdlets on the FAS server:

Add-PSSnapin Citrix.Authentication.FederatedAuthenticationService.V1

Step 5: Generate the RSA keypair inside the FAS server’s TPM and create the CSR by entering the following PowerShell cmdlet on the FAS server. Note: Some TPMs restrict key length. The default is key length is 2048 bits. Be sure to specify a key length supported by your hardware.

New-FasAuthorizationCertificateRequest -UseTPM $true -address <FQDN of FAS Server>

For example:

New-FasAuthorizationCertificateRequest -UseTPM $true -address fashsm.auth.net

The following is displayed:

Notes:

• The Id GUID (in this example, “5ac3d8bd-b484-4ebe-abf8-4b2cfd62ca39”) is required in a subsequent step.
• Think of this PowerShell cmdlet as a one-time “override” that is used to generate the private key for the RA certificate.
• When running this cmdlet, the values that are read from the config file when the FAS service started are checked to determine the key length to use (the default is 2048).
• Because -UseTPM is set to $true in this manual PowerShell-initiated RA certificate private key operation, the system ignores values from the file that do not match the settings required to use a TPM.
• Running this cmdlet does not change any settings in the config file.
• During subsequent automatic FAS-initiated user certificate private key operations, the values that were read from the file when the FAS service started will be used.
• It is also possible to set the KeyProtection value in the config file to GenerateTPMProtectedKey when the FAS server is issuing user certificates to generate user certificate private keys protected by the TPM.

To verify that the TPM was used to generate the keypair, look in the application log in the Windows Event viewer on the FAS server, at the time that the keypair is generated.

Note “[TPM: True]”

Followed by:

Note “Provider: [CNG] Microsoft Platform Crypto Provider”

Step 6: Copy the certificate request section into a text editor and save it to disk as a text file.

Step 7: Submit the CSR to your CA by typing the following into PowerShell on the FAS server:

certreq -submit -attrib “certificatetemplate:<certificate template from step 2>” <certificate request file from step 6>

For example:

certreq -submit -attrib “certificatetemplate:Offline_RA” C:\Users\Administrator.AUTH\Desktop\usmcertreq.txt

The following is displayed:

At this point a Certification Authority List window might appear. The CA in this example has both http (top) and DCOM (bottom) enrolment enabled. Select the DCOM option, if available:

After the CA has been specified, PowerShell displays the RequestID:

Step 8: On the CA server, in the CA MMC snap-in, click Pending Requests. Note the Request ID. Then right-click the request and choose Issue.

Step 9: Select the Issued Certificates node. Find the certificate that was just issued (the Request ID should match). Double-click to open the certificate. Select the Details tab. Click Copy to File. The Certificate Export Wizard launches. Click Next. Choose the following options for the file format:

The format must be “Cryptographic Message Syntax Standard – PKCS #7 Certificates (.P7B)” and “Include all certificates in the certification path if possible” must be checked.

Step 10: Copy the exported certificate file onto the FAS server.

Step 11: Import the RA certificate into the FAS server registry by entering the following PowerShell cmdlet on the FAS server:

For example:

The following is displayed:

Step 12: Close the FAS administration console and then restart it.

Note that the step “Authorize this Service” has turned green, and now displays “Deauthorize this Service.” The entry below indicates “Authorized by: Offline CSR”

Step 13: Select the User Roles tab in the FAS administration console and edit the settings described in the main FAS article.

Note: Deauthorizing the FAS through the administration console will delete the User Rule.

Using the FAS management console

The FAS management console cannot do offline CSR, so using it is not recommended unless your organization allows online CSR for RA certificates.

When performing the FAS initial setup steps, after deploying certificate templates and setting up the CA, but before authorizing the service (step 3 in the configuration sequence):

Step 1: Edit the config file by changing the following line as follows:

The file should now appear as follows:

Some TPMs restrict key length. The default key length is 2048 bits. Be sure to specify a key length supported by your hardware.

Step 2: Authorize the service.

Step 3: Manually issue the pending certificate request from the CA server. After the RA certificate is obtained, step 3 in the setup sequence in the management console will be green. At this point, the RA certificate’s private key will have generated in the TPM. The certificate will be valid for 2 years by default.

Step 4: Edit the config file back to the following:

Note: Although FAS can generate user certificates with TPM protected keys, the TPM hardware may be too slow for large deployments.

Step 5: Restart the Citrix Federated Authentication Service. This forces the service to re-read the config file and reflect the changed values. The subsequent automatic private key operations will affect user certificate keys; those operations will not store the private keys in the TPM, but use the Microsoft Software Key Storage Provider.

Step 6: Select the User Roles tab in the FAS administration console and edit the settings as described in the main FAS article.

Note: Deauthorizing the FAS through the administration console will delete the User Rule.

Example 3

This example covers an RA certificate private key and user certificates’ private keys stored in an HSM. This example assumes a configured HSM. Your HSM will have a provider name, for example “HSM_Vendor’s Key Storage Provider.”

If you plan to run your FAS server in a virtualized environment, check with your HSM vendor about hypervisor support.

Step 1. During the initial setup of the FAS configuration using the administration console, complete only the first two steps: “Deploy certificate templates” and “Setup Certificate Authority.”

Step 2: Consult your HSM vendor’s documentation to determine what your HSM’s ProviderName value should be. If your HSM uses CAPI, the provider might be referred to in the documentation as a Cryptographic Service Provider (CSP). If your HSM uses CNG, the provider might be referred to as a Key Storage Provider (KSP).

Step 3: Edit the config file as follows:

The file should now appear as follows:

This scenario assumes that your HSM uses CNG, so the ProviderLegacyCsp value is set to false. If your HSM uses CAPI, ProviderLegacyCsp value should be set to true. Consult your HSM vendor’s documentation to determine whether your HSM uses CAPI or CNG. Also consult your HSM vendor’s documentation on supported key lengths for asymmetric RSA key generation. In this example, the key length is set to the default of 2048 bits. Ensure that the key length you specify is supported by your hardware.

Step 4: Restart the Citrix Federated Authentication Service to read the values from the config file.

Step 5: Generate the RSA keypair inside the HSM and create the CSR by clicking Authorize in the Initial Setup tab of the FAS administration console.

Step 6: To verify that the keypair was generated in the HSM, check the application entries in the Windows Event log:

Note: [Provider: [CNG] HSM_Vendor’s Key Storage Provider]

Step 7: On the CA server, in the CA MMC, select the Pending Requests node:

Right-click the request and select Issue.

Note that the step “Authorize this Service” has turned green, and now displays “Deauthorize this Service.” The entry below indicates “Authorized by: [<CA Name>]”

Step 8: Select the User Roles tab in the FAS administration console and edit the settings as described in the main FAS article.

Note: Deauthorizing the FAS through the administration console will delete the User Rule.

FAS certificate storage

FAS does not use the Microsoft certificate store on the FAS server to store its certificates. It uses the registry.

Note: When using an HSM to store private keys, HSM containers are identified with a GUID. The GUID for the private key in the HSM matches the GUID for the equivalent certificate in the registry.

To determine the GUID for the RA certificate, enter the following PowerShell cmdlets on the FAS server:

Add-pssnapin Citrix.a*

Get-FasAuthorizationCertificate –address <FAS server FQDN>

For example:

Get-FasAuthorizationCertificate –address cg-fas-2.auth.net

To obtain a list of user certificates, enter:

Get-FasUserCertificate –address <FAS server FQDN>

For example:

Get-FasUserCertificate –address cg-fas-2.auth.net

Related information

• The Federated Authentication Service
  article is the primary reference for FAS installation and configuration.
• The common FAS deployments are summarized in the Federated Authentication Services architectures overview
  article.
• Other “how-to” articles are introduced in the Federated Authentication Service configuration and management
  article.