Product documentation
Citrix Virtual Apps and Desktops
Service Current Release 2407 2402 LTSR 2311 2308 2305 2303 2212 2209 2206 2203 LTSR 1912 LTSR
View PDF

Manage security keys

June 13, 2024
Contributed by: 
C L

Note:

  • You must use this feature in combination with StoreFront 1912 LTSR CU2 or later.

  • The Secure XML feature is only supported on Citrix ADC and Citrix Gateway release 12.1 and later.

This feature lets you allow only approved StoreFront and Citrix Gateway machines to communicate with Citrix Delivery Controllers. After you enable this feature, any requests that do not contain the key are blocked. Use this feature to add an extra layer of security to protect against attacks originating from the internal network.

A general workflow to use this feature is as follows:

  1. Enable Studio to show the feature settings.

  2. Configure settings for your site.

  3. Configure settings in StoreFront.

  4. Configure settings in Citrix ADC.

Enable Studio to show the feature settings

By default, settings for security keys are hidden from Studio. To enable Studio to show them, use the PowerShell SDK as follows:

  1. Run the Citrix Virtual Apps and Desktops PowerShell SDK.
  2. In a command window, run the following commands:
    • Add-PSSnapIn Citrix*. This command adds the Citrix snap-ins.
    • Set-ConfigSiteMetadata -Name "Citrix_DesktopStudio_SecurityKeyManagementEnabled" -Value "True"

For more information about the PowerShell SDK, see SDKs and APIs.

Configure settings for the site

You can use Studio or PowerShell to configure security key settings for your site.

Use the Studio console

  1. Navigate to Studio > Settings > Manage security key and click Edit. The Manage Security Key window appears.

    Manage Security Key wizard

    Important:

    • There are two keys available for use. You can use the same key or different keys for communications over the XML and STA ports. We recommend that you use only one key at a time. The unused key is used only for key rotation.
    • Do not click the refresh icon to update the key already in use. If you do, service interruption will occur.

  2. Click the refresh icon to generate new keys.

  3. Select where a key is required:

    • Require key for communications over XML port (StoreFront only). If selected, require a key to authenticate communications over the XML port. StoreFront communicates with Citrix Cloud over this port. For information about changing the XML port, see Knowledge Center article CTX127945.

    • Require key for communications over STA port. If selected, require a key to authenticate communications over the STA port. Citrix Gateway and StoreFront communicate with Citrix Cloud over this port. For information about changing the STA port, see Knowledge Center article CTX101988.

  4. Click Save to apply your changes and to exit the window.

Use PowerShell

The following are PowerShell steps equivalent to Studio operations.

  1. Run the Citrix Virtual Apps and Desktops Remote PowerShell SDK.

  2. In a command window, run the following command:
    • Add-PSSnapIn Citrix*
  3. Run the following commands to generate a key and set up Key1:
    • New-BrokerXmlServiceKey
    • Set-BrokerSite -XmlServiceKey1 <the key you generated>
  4. Run the following commands to generate a key and set up Key2:
    • New-BrokerXmlServiceKey
    • Set-BrokerSite -XmlServiceKey2 <the key you generated>
  5. Run one or both of the following commands to enable the use of a key in authenticating communications:
    • To authenticate communications over the XML port:
      • Set-BrokerSite -RequireXmlServiceKeyForNFuse $true
    • To authenticate communications over the STA port:
      • Set-BrokerSite -RequireXmlServiceKeyForSta $true

See the PowerShell command help for guidance and syntax.

Configure settings in StoreFront

After completing the configuration for your site, you need to configure relevant settings in StoreFront by using PowerShell.

On the StoreFront server, run the following PowerShell commands:

To configure the key for communications over the XML port, use command [Set-STFStoreFarm https://developer-docs.citrix.com/en-us/storefront-powershell-sdk/current-release/Set-STFStoreFarm.html]. For example 
$store = Get-STFStoreService -VirtualPath [Path to store]
$farm = Get-STFStoreFarm -StoreService $store -FarmName [Resource feed name]
Set-STFStoreFarm -Farm $farm -XMLValidationEnabled $true -XMLValidationSecret [secret]
<!--NeedCopy-->

Enter the appropriate values for the following parameters:

  • Path to store
  • Resource feed name
  • secret

To configure the key for communications over the STA port, use the New-STFSecureTicketAuthority and Set-STFRoamingGateway commands. For example:

$gateway = Get-STFRoamingGateway -Name [Gateway name]
$sta1 = New-STFSecureTicketAuthority -StaUrl [STA1 URL] -StaValidationEnabled $true -StaValidationSecret [secret]
$sta2 = New-STFSecureTicketAuthority -StaUrl [STA2 URL] -StaValidationEnabled $true -StaValidationSecret [secret]
Set-STFRoamingGateway -Gateway $gateway -SecureTicketAuthorityObjs $sta1,$sta2
<!--NeedCopy-->

Enter the appropriate values for the following parameters:

  • Gateway name
  • STA URL
  • Secret

See the PowerShell command help for guidance and syntax.

Configure settings in Citrix ADC

Note:

Configuring this feature in Citrix ADC is not required unless you use Citrix ADC as your gateway. If you use Citrix ADC, follow the steps below.

  1. Ensure that the following prerequisite configuration is already in place:

    • The following Citrix ADC related IP addresses are configured.

      ADC management IP address

      • Subnet IP (SNIP) address for enabling communication between the Citrix ADC appliance and the back-end servers. For details, see Configuring Subnet IP Addresses.
      • Citrix Gateway virtual IP address and load balancer virtual IP address to log in to the ADC appliance for session launch. For details, see Create a virtual server.

      Subnet IP address

    • The required modes and features in the Citrix ADC appliance are enabled.
      • To enable the modes, in the Citrix ADC GUI navigate to System > Settings > Configure Mode.
      • To enable the features, in the Citrix ADC GUI navigate to System > Settings > Configure Basic Features.
    • Certificates related configurations are complete.

      Create a CSR certificate

      Install server certificate

      Install CA certificate

      Gateway for virtual desktops

  2. Add a rewrite action. For details, see Configuring a Rewrite Action.

    1. Navigate to AppExpert > Rewrite > Actions.
    2. Click Add to add a new rewrite action. You can name the action as “set Type to INSERT_HTTP_HEADER”.

    Add rewrite action

    1. In Type, select INSERT_HTTP_HEADER.
    2. In Header Name, enter X-Citrix-XmlServiceKey.
    3. In Expression, add <XmlServiceKey1 value> with the quotes. You can copy the XmlServiceKey1 value from your Desktop Delivery Controller configuration.

    XML service key value

  3. Add a rewrite policy. For details, see Configuring a Rewrite Policy.

    1. Navigate to AppExpert > Rewrite > Policies.

    2. Click Add to add a new policy.

    Add rewrite policy

    1. In Action, select the action created in the earlier step.
    2. In Expression, add HTTP.REQ.IS_VALID.
    3. Click OK.

  4. Set up load balancing. You must configure one load balancing virtual server per STA server. If not the sessions fail to launch.

    For details, see Set up basic load balancing.

    1. Create a load balancing virtual server.
      • Navigate to Traffic Management > Load Balancing > Servers.
      • On the Virtual Servers page, click Add.

      Add a load balancing server

      • In Protocol, select HTTP.
      • Add the load balancing virtual IP address and in Port select 80.
      • Click OK.
    2. Create a load balancing service.
      • Navigate to Traffic Management > Load Balancing > Services.

      Add a load balancing service

      • In Existing Server, select the virtual server created in the previous step.
      • In Protocol, select HTTP and in Port select 80.
      • Click OK, and then click Done.
    3. Bind the service to the virtual server.
      • Select the virtual server created earlier and click Edit.
      • In Services and Service Groups, click No Load Balancing Virtual Server Service Binding.

      Bind service to a virtual server

      • In Service Binding, select the service created earlier.
      • Click Bind.
    4. Bind the rewrite policy created earlier to the virtual server.
      • Select the virtual server created earlier and click Edit.
      • In Advanced Settings, click Policies, and then in Policies section click +.

      Bind rewrite policy

      • In Choose Policy, select Rewrite and in Choose Type, select Request.
      • Click Continue.
      • In Select Policy, select the rewrite policy created earlier.
      • Click Bind.
      • Click Done.
    5. Set up persistence for the virtual server, if necessary.
      • Select the virtual server created earlier and click Edit.
      • In Advanced Settings, click Persistence.

      Set persistence

      • Select persistence type as Others.
      • Select DESTIP to create persistence sessions based on the IP address of the service selected by the virtual server (the destination IP address)
      • In IPv4 Netmask, add a network mask same as that of the DDC.
      • Click OK.
    6. Repeat these steps for the other virtual server as well.

Configuration changes if the Citrix ADC appliance is already configured with Citrix Virtual Desktops

If you have already configured the Citrix ADC appliance with Citrix Virtual Desktops, then to use the Secure XML feature, you must make the following configuration changes.

  • Before the session launch, change the Security Ticket Authority URL of the gateway to use the FQDNs of the load balancing virtual servers.
  • Ensure that the TrustRequestsSentToTheXmlServicePort parameter is set to False. By default, the TrustRequestsSentToTheXmlServicePort parameter is set to False. However, if the customer has already configured the Citrix ADC for Citrix Virtual Desktops, then the TrustRequestsSentToTheXmlServicePort is set to True.
  1. In the Citrix ADC GUI, navigate to Configuration > Integrate with Citrix Products and click XenApp and XenDesktop.

  2. Select the gateway instance and click the edit icon.

    Edit existing gateway configuration

  3. In the StoreFront pane, click the edit icon.

    Edit StoreFront details

  4. Add the Secure Ticket Authority URL.
    • If the Secure XML feature is enabled, then the STA URL must be the URL of the load balancing service.
    • If the Secure XML feature is disabled, then the STA URL must be the URL of STA (DDC’s address) and the TrustRequestsSentToTheXmlServicePort parameter on the DDC must be set to True.

    Add STA urls

Manage security keys
June 13, 2024
Contributed by: 
C L
June 13, 2024
Contributed by: 
C L

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.