Certificate Revocation List (CRL) checking
Introduction
You can configure StoreFront to check the status of TLS certificates used by CVAD delivery controllers using a published certificate revocation list (CRL). You may need to revoke access to a certificate if:
- you believe the private key has been compromised
- the CA is compromised
- the affiliation has been changed
- the certificate has been superseded
Note:
This topic is only relevant when HTTPS connections between StoreFront and Citrix Virtual Apps and Desktops delivery controllers are used. HTTP connections to delivery controllers do not require a certificate, so the -CertRevocationPolicy setting for the Store, described here, has no effect.
StoreFront supports certificate revocation checking using CRL Distribution Point (CDP) certificate extensions and locally installed certificate revocation lists (CRLs). StoreFront supports full CRLs only: delta CLRs are not supported.
CRL Distribution Points (CDP) extensions
StoreFront does not enumerate resources from Citrix Virtual Apps and Desktops delivery controllers which are using revoked certificates whose serial numbers are listed in the published CRL. To detect which certificates have been revoked, StoreFront must be able to access the published CRL using one of the URLs defined in the CDP certificate extensions.
CRL publishing interval
To make StoreFront detect revoked certificates on the delivery controller more quickly, reduce the CRL publishing interval on the CA. Edit the properties of the CLR Distribution Points extension to set a lower CLR publishing interval value appropriate to your public key infrastructure.
Client CRL caching
The Windows public key infrastructure client caches CRLs locally. A more recent CRL is not downloaded until the locally cached CRL has expired.
StoreFront’s access to certificate revocation lists (CRLs)
Certificate revocation checking relies on StoreFront’s ability to access CRLs. Consider carefully how StoreFront contacts the webserver or the certificate authority (CA) that publishes the CRL, and how StoreFront receives CRL updates.
Internal enterprise CAs and private certificates on delivery controllers
To use private CAs and certificates, StoreFront requires a correctly configured enterprise CA and a published CRL which it can access within your organization and internal network. Refer to Microsoft documentation for information on configuring the enterprise CA to publish CDP extensions. Any certificates on your delivery controllers, which existed before the CA was configured to include CDP extensions, may need to be reissued.
It is typical for StoreFront and Citrix Virtual Apps and Desktops servers to be in isolated private networks without access to the Internet. In this scenario, private CAs should be used.
External public CAs and public certificates on delivery controllers
StoreFront servers and Citrix Virtual Apps and Desktops delivery controllers can use certificates issued by public CAs. StoreFront must be able to contact the public CA’s webserver via the Internet, using the URL referenced in the CDP extensions. If StoreFront cannot download a copy of the CRL using a CDP URL after a public certificate has been revoked, then StoreFront cannot perform the CRL check.
Certificate revocation policy settings
Use the Citrix StoreFront PowerShell cmdlets Get-STFStoreFarmConfiguration and Set-STFStoreFarmConfiguration to set the certificate revocation policy for a store. Running Get-Help Set-STFStoreFarmConfiguration -detailed displays the PowerShell help and examples containing the option -CertRevocationPolicy. For more information of these StoreFront PowerShell cmdlets, see Citrix StoreFront SDK PowerShell Modules.
The -CertRevocationPolicy option can be set to the following values:
| Setting | Description |
|---|---|
| NoCheck | StoreFront does not check the revocation state of the certificate on the delivery controller. StoreFront still enumerates resources from delivery controllers that use revoked certificates. This is the default setting. |
| MustCheck | This is the most secure option. StoreFront attempts to obtain a CRL by contacting the URLs referenced in the CDP extensions of the certificate on the delivery controller. StoreFront fails to enumerate from the delivery controller if the CRL is not available or if the certificate in use on the delivery controller has been revoked. The URL can point to an internal webserver if the certificate is private, or to a public internet webserver if the certificate is issued by a public CA. |
| FullCheck | StoreFront attempts to contact the URLs published in the CDP extensions of the delivery controller certificate. If StoreFront fails to obtain a copy of the CRL from the URLs, then it still allows enumeration of resources from the delivery controller. If StoreFront successfully obtains the CRL and the delivery controller’s certificate has been revoked, then StoreFront does not enumerate resources. The URL can point to an internal webserver if the certificate is private, or to a public internet webserver if the certificate is issued by a public CA. |
| NoNetworkAccess | Only CRLs, which have been imported locally into the Citrix Delivery Servers certificate store on the StoreFront server are checked. StoreFront does not attempt to contact any of the URLs specified in the CDP extensions. If StoreFront fails to obtain a a local copy of the CRL, then it still allows enumeration of resources from the delivery controller. If StoreFront successfully obtains a local copy of the CRL from the Citrix Delivery Servers certificate store, and the delivery controller’s certificate has been revoked, then StoreFront does not enumerate resources. |
Configure a store for certificate revocation checking
To set the certificate revocation policy for a store, open the PowerShell ISE with Run As Admin, then run the following PowerShell cmdlets. If you have multiple stores, repeat this procedure on them all. -CertRevocationPolicy is a store-level setting which affects all delivery controllers configured for the store specified in $StoreVirtualPath.
$SiteID = 1
$StoreVirtualPath = "/Citrix/Store"
$StoreObject = Get-STFStoreService -SiteId $SiteID -VirtualPath
$StoreVirtualPath
Set-STFStoreFarmConfiguration -StoreService $StoreObject -CertRevocationPolicy "MustCheck"
<!--NeedCopy-->
To check that the setting has been correctly applied, or to view the current -CertRevocationPolicy configuration, run the following:
(Get-STFStoreFarmConfiguration -StoreService $StoreObject).CertRevocationPolicy
<!--NeedCopy-->
Using locally imported CRLs on the StoreFront server
Using locally imported CRLs is supported, but Citrix does not recommend it because:
- They are difficult to manage and update in large enterprise deployments, where multiple StoreFront server groups may be involved.
- Manually updating CRLs on every StoreFront server, every time a certificate is revoked, is much less efficient than using CDP extensions and published CRLs on the entire active directory domain.
Using locally installed or updated CRLs can be used if -CertRevocationPolicy is set to “NoNetworkAccess”, and you have the means to distribute the CRL efficiently to all StoreFront servers.
To use locally imported CLRs
-
Copy the CRL to the StoreFront server’s desktop. If the StoreFront server is part of a server group, copy it to all the StoreFront servers in the group.
-
Open the MMC snap-in and select File > Add/remove Snapins > Certificates > Computer Account > Citrix Delivery Services certificate store.
-
Right click and select All Tasks > Import, then browse to the .CRL file and choose Select All Files > Open > Place all certificates in the following Store > Citrix Delivery Services.
To add the CRL to the Citrix Delivery Services certificate store via PowerShell or the command line
-
Log into StoreFront and copy the .CRL file to the desktop of the current user.
-
Open the PowerShell ISE and select Run as Admin.
-
Run the following:
certutil -addstore "Citrix Delivery Services" "$env:UserProfile\Desktop\Example-DC01-CA.crl"
If successful, the following is returned:
Citrix Delivery Services
CRL "CN=Example-DC01-CA, DC=example, DC=com" added to store.
CertUtil: -addstore command completed successfully.
You can use this command as an example to distribute the CRL to all StoreFront servers in your deployment automatically via scripts.
XML authentication using delivery controllers
You can configure StoreFront to delegate user authentication to Citrix Virtual Apps and Desktops delivery controllers. Users are prevented from signing in to StoreFront if the certificate on the delivery controller has been revoked. This behaviour is desirable as active directory users should not be able to sign in to StoreFront if the certificate on the Citrix Virtual Apps and Desktops delivery controller, responsible for authenticating them, has been revoked.
To delegate user authentication to delivery controllers
-
Configure the store for certificate revocation as described in the previous section Configure a store for certificate revocation checking.
-
Configure the delivery controller to use HTTPS, following the procedure described in XML service-based authentication.
Configure an XML authentication service for certificate revocation checking
These steps are only required if you are using XML authentication in your deployment.
Note:
StoreFront supports two models for mapping stores to an authentication service. The recommended approach is a one-to-one mapping between store and Authentication Service. In this case you must perform the steps in this section on all stores and their respective authentication services.
Make sure that the certificate revocation mode is set to the same value for both the store and the authentication service. Alternatively, if the authentication configuration is identical for all stores, multiple stores can be configured to share a single authentication service.
The authentication service PowerShell cmdlets have no equivalent of Set-STFStoreFarmConfiguration, so a slightly different PowerShell approach is required. Use the same Certificate revocation policy settings describe in the earlier section.
-
Open the PowerShell ISE and select Run As Admin.
$SiteID = 1 $StoreVirtualPath = "/Citrix/Store" $AuthVirtualPath = "/Citrix/StoreAuth" <!--NeedCopy--> -
Select the store service, authentication service, and delivery controller to be used for XML authentication. Ensure that the delivery controller is already configured for the Store.
$StoreObject = Get-STFStoreService -SiteId $SiteID -VirtualPath $StoreVirtualPath $FarmObject = Get-STFStoreFarm -StoreService $StoreObject -FarmName "CVAD" $AuthObject = Get-STFAuthenticationService -SiteID $SiteID -VirtualPath $AuthVirtualPath <!--NeedCopy--> -
Modify the CertRevocationPolicy property of the authentication service directly.
$AuthObject.FarmsConfiguration.CertRevocationPolicy = "FullCheck" $AuthObject.Save() Enable-STFXmlServiceAuthentication -AuthenticationService $AuthObject -Farm $FarmObject <!--NeedCopy--> -
Confirm that you have set the correct certificate revocation mode.
$AuthObject = Get-STFAuthenticationService -SiteID 1 -VirtualPath $AuthVirtualPath $AuthObject.FarmsConfiguration.CertRevocationPolicy <!--NeedCopy-->
Windows Event Viewer errors to expect
When CRL checking is enabled, errors are reported in the Windows Event Viewer on the StoreFront server.
To open the Event Viewer:
- On the StoreFront server type Run.
- Type eventvwr then press enter.
- In Applications and Services look for Citrix Delivery Services events.
Example Error: Store cannot contact a delivery controller with a revoked certificate
An SSL connection could not be established: An error occurred during SSL crytography: Access is denied.
This message was reported from the Citrix XML Service at address https://deliverycontrollerTLS.domain.com/scripts/wpnbr.dll.
The specified Citrix XML Service could not be contacted and has been temporarily removed from the list of active services.
<!--NeedCopy-->
Example Error: From Receiver for Web if user cannot log in due to failing XML authentication
An unexpected response was received during the authentication process.
Citrix.DeliveryServicesClients.Authentication.Exceptions.ExplicitAuthenticationFailure,
Citrix.DeliveryServicesClients.Authentication, Version=3.20.0.0,
Culture=neutral, PublicKeyToken=null
General Authentication Failure
ExplicitResult.State: 5
AuthenticationControllerRequestUrl:
https://storefront.example.com/Citrix/StoreWeb/ExplicitAuth/LoginAttempt
ActionType: LoginAttempt
at
Citrix.Web.AuthControllers.Controllers.ExplicitAuthController.GetExplicitAuthResult(ActionType
type, Dictionary`2 postParams)
<!--NeedCopy-->
In this article
- Introduction
- Certificate revocation policy settings
- Configure a store for certificate revocation checking
- Using locally imported CRLs on the StoreFront server
- XML authentication using delivery controllers
- Configure an XML authentication service for certificate revocation checking
- Windows Event Viewer errors to expect