Category: Citrix Gateway 13

Self-Service Password Reset (SSPR) – Citrix ADC

Last Modified: Dec 28, 2020 @ 5:49 am

33 Comments

Navigation

SSPR Flow

The SSPR feature in Citrix ADC is completely unrelated to the SSPR in Citrix StoreFront. They are separate registrations.

  • ADC SSPR registration is stored in an Active Directory user attribute.

SSPR is available in Citrix ADC 12.1 build 51.16 and higher.

SSPR requires nFactor, which is only available in Citrix ADC Advanced Edition and Premium Edition. You can use nFactor with Citrix Gateway.

The first factor is a Login Schema that has an optional Forgot Password link. The Login Schema file named SingleAuthPasswordResetRem.xml has this link. There are other built-in Login Schemas for Username Only and Dual Auth that also have the link.

If the user logs in normally, then ADC checks if the user has been enrolled in SSPR or not. If not enrolled, then the user is prompted to select questions and provide answers. This is a custom Login Schema that you can create from the ADC GUI as described later.

If the user clicks the Forgot Password link, then the user is prompted to answer two of the previously enrolled questions.

  • Optionally, the user might be prompted to retrieve a One-time password (OTP) sent to an Alternate Email address. The user might not have access to corporate email, so the OTP should be sent to the user’s personal email address. The user enters the alternate email address during SSPR registration.

  • Finally, the user is prompted to enter a new password.

Here’s what a sample SSPR nFactor configuration looks like:

# ** nFactor Visualizer 
# ** ------------------ 
# ** AAA vserver: AAA-SSPR
# **    Login Schema Policy = lschema_password_reset
# **       Priority = 20
# **       Rule = true
# **       Login Schema XML = "/nsconfig/loginschema/LoginSchema/SingleAuthPasswordResetRem.xml"
# **    Adv Authn Policy = LDAP_Password_Reset
# **       Priority = 10
# **       Rule = "aaa.LOGIN.VALUE(\"passwdreset\").EQ(\"1\")"
# **       Action = ldapAction named LDAP-Corp_NoAuth
# **       Goto if failed = NEXT
# **       Next Factor if Success = kba_validation
# **          Login Schema Profile = LSCHEMA_INT
# **          Adv Authn Policy = kba_validation
# **             Priority = 10
# **             Rule = true
# **             Action = ldapAction named LDAP-Corp_NoAuth
# **             Goto if failed = NEXT
# **             Next Factor if Success = email_validation
# **                Login Schema Profile = LSCHEMA_INT
# **                Adv Authn Policy = email_validation
# **                   Priority = 10
# **                   Rule = true
# **                   Action = emailAction named EmailOTP
# **                   Goto if failed = NEXT
# **                   Next Factor if Success = password_reset
# **                      Login Schema Profile = LSCHEMA_INT
# **                      Adv Authn Policy = LDAP-Corp-Adv_NoAuth
# **                         Priority = 100
# **                         Rule = true
# **                         Action = ldapAction named LDAP-Corp_NoAuth
# **                         Goto if failed = NEXT
# **    Adv Authn Policy = LDAP-Corp-Adv
# **       Priority = 20
# **       Rule = true
# **       Action = ldapAction named LDAP-Corp
# **       Goto if failed = NEXT
# **       Next Factor if Success = check_for_sspr_registration
# **          Login Schema Profile = LSCHEMA_INT
# **          Adv Authn Policy = switch_to_kba_register
# **             Priority = 1
# **             Rule = "AAA.USER.ATTRIBUTE(\"kba_registered\").EQ(\"0\")"
# **             Action = NO_AUTHN
# **             Goto if failed = NEXT
# **             Next Factor if Success = kba_registration
# **                Login Schema Profile = lschema_KBARegistration
# **                Adv Authn Policy = first_time_login_forced_kba_registration
# **                   Priority = 1
# **                   Rule = true
# **                   Action = ldapAction named LDAP-Corp
# **                   Goto if failed = NEXT
# **          Adv Authn Policy = NoAuth
# **             Priority = 100
# **             Rule = true
# **             Action = NO_AUTHN
# **             Goto if failed = END

Active Directory User Attribute

Citrix ADC SSPR stores its configuration in an Active Directory User attribute.

The attribute must be dedicated to SSPR. You can’t use the same attribute that you might already be using for Citrix ADC One-time passwords (OTP).

  • In Active Directory Users and Computers, enable Advanced Features mode (from the View menu), double-click a user, switch to the Attribute Editor tab, and find a String attribute that is not being used. When you double-click an attribute, look for String in the window title.
  • Open the Active Directory Schema console. Under Attributes, find your candidate attribute and double-click it. Make sure the Maximum length is high (e.g. 32767). The extensionAttributes default to 1024 or 2048, which is not long enough.
  • You might want to uncheck the bottom boxes (e.g. Attribute is copied when duplicating a user) since each user has their own SSPR configuration.
  • ADC needs permissions to set this Attribute and reset user passwords. You can use the Delegate Control wizard to grant these permissions.

    1. Consider creating a group for SSPR Admins and delegating permissions to that group. You can add your LDAP Bind Account and your Service Desk accounts to this group.
    2. In the Tasks to Delegate page, change it to Create a custom task to delegate and click Next.
    3. In the Active Directory Object Type page, change the selection to Only the following objects in this folder and select User objects. Click Next.
    4. In the Permissions page, on the top of the page, check the box for Property-specific.
    5. In the Permissions list, check the box next to Reset password. Scroll down.
    6. Find the attribute you are using for SSPR and check the Read and Write boxes. Click Next.

Help Desk will need to be trained to reset a user’s SSPR registration by double-clicking the attribute and clicking the Clear button. The next time the user logs in, the user will be prompted to enroll for SSPR again.

ADC uses a certificate to encrypt the contents of the Attribute. It currently is not possible to configure the certificate from the GUI, so you’ll need to SSH to the ADC and run the following command. The certificate should already be installed on the ADC.

bind vpn global -userDataEncryptionKey MyCertificate

The ADC SSPR configuration needs two LDAP Policy/Servers: one with authentication enabled, and one without authentication. In both LDAP Servers, in the Other Settings section, enter the Attribute name into the Alternate Email field and in the KB Attribute field. The same attribute can be used for both. However, you cannot use the same attribute for the OTP Secret field.

SSPR KBA Registration Login Schema

When creating the KBA Registration Login Schema you will be prompted to choose from a list of questions. This list is configured in the file KBQuestions.json located in /nsconfig/loginschema/LoginSchema.

  1. In ADC GUI, on the left, expand Security, expand AAA – Application Traffic, and click Login Schema.
  2. On the right, switch to the Profiles tab.
  3. On the right, click the button labelled Add KBA Registration Login Schema.
  4. Give the new Schema a name. ADC will create a file with the same name.
  5. Configure at least two questions. Move questions from the left to the right. Note: the XML file that it creates has size limits so don’t choose too many questions.
  6. On the right, you can optionally change the labels for Question Field and Answer Field. If you don’t enter anything, then the labels are Question, and Answer, as shown earlier in this article. Scroll down.
  7. Near the bottom are two More links you can click.
  8. The first More link lets you allow users to enter their own questions.
  9. The second More link lets you enable Register Alternate Email.
  10. Click Create when done.
  11. ADC creates a file in /nsconfig/loginschema/LoginSchema that matches the Schema name you entered earlier.
  12. ADC also adds a Login Schema Profile with the same name you entered earlier.

LDAP Servers

You’ll need two LDAP Servers: one with Authentication enabled, and the other with Authentication unchecked. Other than the Authentication checkbox, they are identical. Configure them like normal LDAP Servers.

The NoAuth server has Authentication unchecked.

Configure both LDAP Servers with the SSPR attribute as detailed earlier.

Email Action and Policy

You can optionally configure an Email action to send the user a OTP before allowing the password reset.

  1. In the ADC GUI, the easy way to find Email Actions is to enter “email” in the top left search box.
  2. On the right, click Add.
  3. Give the Email Action a name.
  4. In the Username box, enter the From email address. The emails will look like they come from this address.
  5. Enter the SMTP password for this From address.
  6. In the Server URL box, enter a smtps URL with port number similar to smtps://mail01.corp.com:587. Gmail’s URL smtps://smtp-relay.gmail.com:587 also works.
  7. In the Content box, enter a string containing $code. ADC replaces $code with the OTP.
  8. In the Type box, enter SMTP.
  9. In the Email Address box, enter aaa.user.attribute("alternate_mail"). This expression pulls the destination email address from Alternate Email attribute you defined in your LDAP Server.
  10. Click Create.
  11. It does not appear to be possible to use the ADC GUI to create an Email Authentication Policy. SSH to your ADC and run something similar to the following command: 
    add authentication Policy email_validation -rule true -action EmailOTP

SSPR nFactor Configuration

AAA vServer and Login Schema

The first factor will be a Login Schema that has the Reset Password link. This section creates the following portion of the nFactor configuration:

# ** AAA vserver: AAA-SSPR
# **    Login Schema Policy = lschema_password_reset
# **       Priority = 20
# **       Rule = true
# **       Login Schema XML = "/nsconfig/loginschema/LoginSchema/SingleAuthPasswordResetRem.xml"

Do the following:

  1. Create a AAA vServer.
  2. It can be Non Addressable.
  3. Optionally bind a certificate to the AAA vServer so its status will be Green instead of Red.
  4. On the right, in the Advanced Settings column, click Login Schemas to move it to the left.
  5. On the left, in the Login Schemas section, click where it says No Login Schema.
  6. Next to the Select Policy field, click Add to create a new Login Schema Policy.
  7. Give the Login Schema Policy a name to indicate that this Login Schema includes a link for Self-Service Password Reset.
  8. Next to Profile, click Add to create a new Login Schema Profile.
  9. Give the Login Schema Profile a name.
  10. In the Authentication Schema field, click the edit icon.
  11. In the Login Schema Files section, click the LoginSchema folder.
  12. Highlight one of the PasswordReset files (e.g. SingleAuthPasswordResetRem.xml) and then click the blue Select button on the top right. You can also optionally modify the built-in files.
  13. The Create Authentication Login Schema window collapses and the Authentication Schema field shows the selected file. Click Create when done.
  14. Click Create to finish creating the Authentication Login Schema Policy.
  15. Click Bind to bind the Login Schema Policy to the AAA vServer.

SSPR Registration

Let’s start with the SSPR Registration flow. This section creates the following snippet of the full nFactor configuration:

# ** AAA vserver: AAA-SSPR
# **    Login Schema Policy = lschema_password_reset
# **       Priority = 20
# **       Rule = true
# **       Login Schema XML = "/nsconfig/loginschema/LoginSchema/SingleAuthPasswordResetRem.xml"
# **    Adv Authn Policy = LDAP-Corp-Adv
# **       Priority = 20
# **       Rule = true
# **       Action = ldapAction named LDAP-Corp
# **       Goto if failed = NEXT
# **       Next Factor if Success = check_for_sspr_registration
# **          Login Schema Profile = LSCHEMA_INT
# **          Adv Authn Policy = switch_to_kba_register
# **             Priority = 1
# **             Rule = "AAA.USER.ATTRIBUTE(\"kba_registered\").EQ(\"0\")"
# **             Action = NO_AUTHN
# **             Goto if failed = NEXT
# **             Next Factor if Success = kba_registration
# **                Login Schema Profile = lschema_KBARegistration
# **                Adv Authn Policy = first_time_login_forced_kba_registration
# **                   Priority = 1
# **                   Rule = true
# **                   Action = ldapAction named LDAP-Corp
# **                   Goto if failed = NEXT
# **          Adv Authn Policy = NoAuth
# **             Priority = 100
# **             Rule = true
# **             Action = NO_AUTHN
# **             Goto if failed = END

Do the following:

  1. In the AAA vServer, scroll down to the Advanced Authentication Policies section and click where it says No Authentication Policy.
  2. In the Select Policy field, select your normal LDAP policy. The Login Schema collects username and password and verifies it with the LDAP Policy that you select here.
  3. Change the Priority to 20 or similar. This binding must be a higher number than the Password Reset flow that we configure later.
  4. Next to the Select Next Factor field, click Add to create a Policy Label which will check if the user is registered or not.
  5. Name the Policy Label to indicate that this Policy Label checks if the user is registered or not.
  6. Leave the Login Schema set to LSCHEMA_INT (i.e. no schema), and click Continue.
  7. Next to the Select Policy field, click Add to create an Authentication Policy.
  8. Name this Authentication Policy to indicate that it does nothing more than check if the user is registered or not.
  9. In the Expression field, enter the following expression: 
    AAA.USER.ATTRIBUTE("kba_registered").EQ("0")
  10. Click Create.
  11. Back in the Policy Label Policy Binding window, next to the Select Next Factor field, click Add to create another Policy Label.
  12. Name the Policy Label to indicate that this factor performs the SSPR Registration (i.e. Knowledge-Based Authentication registration).
  13. In the Login Schema field, select the KBA Registration Login Schema that you created earlier.
  14. Click Continue.
  15. Next to the Select Policy field, click Add to create an Authentication Policy.
  16. Name the Authentication Policy to indicate that ADC uses this LDAP Server to store the KBA registration information in the Active Directory User attribute.
  17. Change Action Type to LDAP.
  18. Change Action to your normal authenticating LDAP Server that has the KB Attribute defined.
  19. For Expression, enter true.
  20. Click Create.
  21. Back in the Policy Label Policy Binding page, click Bind.
  22. Click Done to finish creating the Policy Label for KBA Registration.
  23. Back in the “Check for SSPR Registration” Policy Label Policy Binding page, click Bind.
  24. To handle users that are already registered, click Add Binding.
  25. Next to the Select Policy field, click Add to create an Authentication Policy.
  26. Name the Policy to indicate that no authentication is occurring. This policy always returns true and is necessary to avoid errors for users that are already registered.
  27. Change Action Type to NO_AUTHN.
  28. In the Expression box, enter true.
  29. Click Create.
  30. Back in the Policy Label Policy Binding screen, click Bind.
  31. Click Done to close the “Check for SSPR Registration” Policy Label.
  32. Click Bind to bind the LDAP Policy and “Check for SSPR Registration” factor to the AAA vServer.

Password Reset

This section creates the following snippet of the full nFactor configuration:

# ** AAA vserver: AAA-SSPR
# **    Login Schema Policy = lschema_password_reset
# **       Priority = 20
# **       Rule = true
# **       Login Schema XML = "/nsconfig/loginschema/LoginSchema/SingleAuthPasswordResetRem.xml"
# **    Adv Authn Policy = LDAP_Password_Reset
# **       Priority = 10
# **       Rule = "aaa.LOGIN.VALUE(\"passwdreset\").EQ(\"1\")"
# **       Action = ldapAction named LDAP-Corp_NoAuth
# **       Goto if failed = NEXT
# **       Next Factor if Success = kba_validation
# **          Login Schema Profile = LSCHEMA_INT
# **          Adv Authn Policy = kba_validation
# **             Priority = 10
# **             Rule = true
# **             Action = ldapAction named LDAP-Corp_NoAuth
# **             Goto if failed = NEXT
# **             Next Factor if Success = email_validation
# **                Login Schema Profile = LSCHEMA_INT
# **                Adv Authn Policy = email_validation
# **                   Priority = 10
# **                   Rule = true
# **                   Action = emailAction named EmailOTP
# **                   Goto if failed = NEXT
# **                   Next Factor if Success = password_reset
# **                      Login Schema Profile = LSCHEMA_INT
# **                      Adv Authn Policy = LDAP-Corp-Adv_NoAuth
# **                         Priority = 100
# **                         Rule = true
# **                         Action = ldapAction named LDAP-Corp_NoAuth
# **                         Goto if failed = NEXT

Do the following to create the Password Reset flow:

  1. In the AAA vServer, in the Advanced Authentication Policies section, click where it says 1 Authentication Policy
  2. Note the Priority number of the existing binding. Our new binding will need a lower priority number so it is evaluated first. Click Add Binding.
  3. Next to the Select Policy field, click Add to create an Authentication Policy.
  4. Name the Authentication Policy to indicate that this policy only applies if the user clicked the Forgot Password link in the Login Schema.
  5. Change Action Type to LDAP.
  6. Change Action to the your LDAP Server that has Authentication unchecked (i.e. not enabled).
  7. In the Expression box, enter the following expression that returns true if the user clicked the link: 
    aaa.LOGIN.VALUE("passwdreset").EQ("1")
  8. Click Create.
  9. Back in the Policy Binding page, change the Priority to a number that is lower than the existing Policy Binding.
  10. Next to the Select Next Factor field, click Add to create a Policy Label (i.e. factor)
  11. Name the Policy Label to indicate that this factor will verify the user’s questions and answers.
  12. Leave the Login Schema set to the default LSCHEMA_INT (i.e. no schema) and click Continue.
  13. Next to the Select Policy field, click Add to create an Authentication Policy.
  14. Name the Authentication Policy to indicate that this policy verifies the user’s KBA questions and answers.
  15. Change Action Type to LDAP.
  16. Change Action to your LDAP Server that does not require authentication.
  17. In the Expression box, enter true.
  18. Click Create.
  19. Back in the Policy Label Policy Binding page, if you wish to add email validation, then next to Select Next Factor, click Add to create another Policy Label (factor).
  20. Name the Policy Label to indicate that this factor will perform Email OTP verification.
  21. Leave the Login Schema set to the default LSCHEMA_INT (i.e. no schema) and click Add.
  22. In the Policy Label Policy Binding section, click where it says Click to select.
  23. Click the small circle next to the email policy that you created earlier from the ADC’s command line. It’s not possible to use the GUI to create the email policy.
  24. At the top of the screen, click the blue Select button.
  25. Back in the Policy Label Policy Binding screen, next to the Select Next Factor field, click Add to create another Policy Label (i.e. factor).
  26. Name this Policy Label to indicate that this factor performs the password reset.
  27. Leave the Login Schema set to the default LSCHEMA_INT (i.e. no schema) and click Continue.
  28. In the Policy Label Policy Binding section, next to the Select Policy field, click Add to create an Authentication Policy.
  29. Name the Authentication Policy to indicate that this is your LDAP Policy that has Authentication unchecked (not enabled).
  30. Change Action Type to LDAP.
  31. Change Action to your LDAP Server that has Authentication unchecked.
  32. In the Expression field, enter true.
  33. Click Create.
  34. That’s it for the AAA configuration. Now click Bind and Done several times to return to the AAA vServer.






  35. Click Close to finish the AAA vServer’s Authentication Policy bindings.

Bind to Citrix Gateway

If you are using nFactor configuration with Citrix Gateway, then configure the Authentication Profile like normal.

  1. Go to Citrix Gateway > Virtual Servers and edit a Gateway.
  2. On the right, in the Advanced Settings column, click Authentication Profile to move it to the left.
  3. On the left, in the Authentication Profile section, click Add.
  4. Name the Authentication Profile to indicate that this nFactor Flow does Self-Service Password Reset.
  5. In the Authentication Virtual Server field, click where it says Click to select.
  6. Click the small circle next to the AAA vServer that is configured with your SSPR flow.
  7. At the top of the page, click the blue Select button.
  8. Click Create.
  9. Click OK to select the Authentication Profile.

CLI Commands

Here’s a full sample ADC CLI configuration:

# Certs
# -----
add ssl certKey WildcardCorpCom.cer_CERT_KE_ic1 -cert WildcardCorpCom.cer_ic1 -passcrypt b217e266 -encrypted -encryptmethod ENCMTHD_3

add ssl certKey WildcardCorpCom.cer_CERT_KEY -cert WildcardCorpCom.pfx -key WildcardCorpCom.pfx -inform PFX -passcrypt 52e54af -encrypted -encryptmethod ENCMTHD_3 -expiryMonitor DISABLED

add ssl certKey CorpIntermediate -cert CorpIntermediate.cer -inform DER -passcrypt cc9675 -encrypted -encryptmethod ENCMTHD_3 -expiryMonitor DISABLED

# Cert Links
# ----------
link ssl certKey WildcardCorpCom.cer_CERT_KEY CorpIntermediate

link ssl certKey CorpIntermediate WildcardCorpCom.cer_CERT_KE_ic1


# AAA Global Settings
# -------------------
enable ns feature AAA


# LDAP Actions
# ------------
add authentication ldapAction LDAP-Corp -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn ctxsvc@corp.local -ldapBindDnPassword 868d22c -encrypted -encryptmethod ENCMTHD_3 -ldapLoginName sAMAccountName -groupAttrName memberOf -subAttributeName cn -secType SSL -passwdChange ENABLED -nestedGroupExtraction ON -groupNameIdentifier sAMAccountName -groupSearchAttribute memberOf -groupSearchSubAttribute CN -KBAttribute extensionAttribute1 -alternateEmailAttr extensionAttribute1

add authentication ldapAction LDAP-Corp_NoAuth -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn ctxsvc@corp.local -ldapBindDnPassword a4ffb4 -encrypted -encryptmethod ENCMTHD_3 -ldapLoginName sAMAccountName -groupAttrName memberOf -subAttributeName cn -secType SSL -authentication DISABLED -passwdChange ENABLED -nestedGroupExtraction ON -groupNameIdentifier sAMAccountName -groupSearchAttribute memberOf -groupSearchSubAttribute CN -KBAttribute extensionAttribute1 -alternateEmailAttr extensionAttribute1


# Email (SSPR) Actions
# --------------------
add authentication emailAction EmailOTP -userName admin@corp.local -password 7868e -encrypted -encryptmethod ENCMTHD_3 -serverURL "smtps://mail01.corp.local:587" -content "Your OTP is $code" -emailAddress "aaa.user.attribute(\"alternate_mail\")"


# Advanced Authentication Policies
# --------------------------------
add authentication Policy LDAP-Corp-Adv -rule true -action LDAP-Corp

add authentication Policy kba_validation -rule true -action LDAP-Corp_NoAuth

add authentication Policy LDAP_Password_Reset -rule "aaa.LOGIN.VALUE(\"passwdreset\").EQ(\"1\")" -action LDAP-Corp_NoAuth

add authentication Policy NoAuth -rule true -action NO_AUTHN

add authentication Policy switch_to_kba_register -rule "AAA.USER.ATTRIBUTE(\"kba_registered\").EQ(\"0\")" -action NO_AUTHN

add authentication Policy email_validation -rule true -action EmailOTP

add authentication Policy first_time_login_forced_kba_registration -rule true -action LDAP-Corp

add authentication Policy EmailOTP -rule true -action EmailOTP

add authentication Policy LDAP-Corp-Adv_NoAuth -rule true -action LDAP-Corp_NoAuth


# Login Schemas
# -------------
add authentication loginSchema lschema_KBARegistration -authenticationSchema "/nsconfig/loginschema/LoginSchema/lschema_KBARegistration.xml"

add authentication loginSchema lschema_password_reset -authenticationSchema "/nsconfig/loginschema/LoginSchema/SingleAuthPasswordResetRem.xml"


# Login Schema Policies
# ---------------------
add authentication loginSchemaPolicy lschema_password_reset -rule true -action lschema_password_reset


# Authentication Policy Labels
# ----------------------------
add authentication policylabel kba_registration -loginSchema lschema_KBARegistration

bind authentication policylabel kba_registration -policyName first_time_login_forced_kba_registration -priority 1 -gotoPriorityExpression NEXT

add authentication policylabel check_for_sspr_registration -loginSchema LSCHEMA_INT

bind authentication policylabel check_for_sspr_registration -policyName switch_to_kba_register -priority 1 -gotoPriorityExpression NEXT -nextFactor kba_registration

bind authentication policylabel check_for_sspr_registration -policyName NoAuth -priority 100 -gotoPriorityExpression END

add authentication policylabel password_reset -loginSchema lschema_noschema

bind authentication policylabel password_reset -policyName LDAP-Corp-Adv_NoAuth -priority 100 -gotoPriorityExpression NEXT

add authentication policylabel email_validation -loginSchema lschema_noschema

bind authentication policylabel email_validation -policyName email_validation -priority 10 -gotoPriorityExpression NEXT -nextFactor password_reset

add authentication policylabel kba_validation -loginSchema lschema_noschema

bind authentication policylabel kba_validation -policyName kba_validation -priority 10 -gotoPriorityExpression NEXT -nextFactor email_validation


# Authentication Virtual Servers
# ------------------------------
add authentication vserver AAA-SSPR SSL 0.0.0.0

bind authentication vserver AAA-SSPR -portaltheme RfWebUI

bind authentication vserver AAA-SSPR -policy lschema_password_reset -priority 20 -gotoPriorityExpression END

bind authentication vserver AAA-SSPR -policy LDAP_Password_Reset -priority 10 -nextFactor kba_validation -gotoPriorityExpression NEXT

bind authentication vserver AAA-SSPR -policy LDAP-Corp-Adv -priority 20 -nextFactor check_for_sspr_registration -gotoPriorityExpression NEXT


# Authentication Profiles
# -----------------------
add authentication authnProfile SSPR -authnVsName AAA-SSPR


# NetScaler Gateway Global Bindings
# ---------------------------------
bind vpn global -userDataEncryptionKey WildcardCorpCom.cer_CERT_KEY


# NetScaler Gateway Virtual Servers
# ---------------------------------
add vpn vserver gateway2 SSL 10.2.4.220 443 -Listenpolicy NONE -tcpProfileName nstcp_default_XA_XD_profile -httpProfileName http2 -deploymentType ICA_STOREFRONT -authnProfile SSPR -vserverFqdn gateway3.corp.com

bind vpn vserver gateway2 -portaltheme RfWebUI

bind vpn vserver gateway2 -policy PL_OS_10.2.4.120 -priority 100

bind vpn vserver gateway2 -policy PL_WB_10.2.4.120 -priority 100


# SSL Virtual Servers
# -------------------
bind ssl vserver gateway2 -certkeyName WildcardCorpCom.cer_CERT_KEY

bind ssl vserver AAA-SSPR -certkeyName WildcardCorpCom.cer_CERT_KEY

RADIUS Authentication – Citrix Gateway

Last Modified: Mar 29, 2021 @ 11:28 am

215 Comments

This article applies to Citrix Gateway 13.0, Citrix Gateway 12.1, and NetScaler Gateway 12.0. Citrix ADC is the new name for NetScaler. Citrix Gateway is the new name for NetScaler Gateway.

Navigation

Change Log

RADIUS Overview

One method of two-factor authentication to Citrix Gateway is the RADIUS protocol with a two-factor authentication product (tokens) that has RADIUS enabled.

  • Another common two-factor authentication method is SAML to an Identity Provider, like Azure Active Directory or Okta. SAML is detailed in the Federated Authentication Service article.

RADIUS Clients and Source IP – On your RADIUS servers, you’ll need to add the ADC appliances as RADIUS Clients. When ADC uses a local (same appliance) load balanced Virtual Server for RADIUS authentication, the traffic is sourced from the ADC SNIP (Subnet IP). When ADC uses a direct connection to a RADIUS Server without going through a load balancing Virtual Server, or uses a remote (different appliance) Load Balancing Virtual Server, the traffic is sourced from the ADC NSIP (ADC Management IP). Use the correct IP(s) when adding the ADC appliances as RADIUS Clients. And adjust firewall rules accordingly.

  • For High Availability pairs, if you locally load balance RADIUS, then you only need to add the SNIP as a RADIUS Client, since the SNIP floats between the two appliances. However, if you are not locally load balancing RADIUS, then you’ll need to add the NSIP of both appliances as RADIUS Clients. Use the same RADIUS Secret for both appliances.

Links:

Some two-factor products (e.g. SMS Passcode) require you to hide the 2nd password field. Receiver 4.4 and newer supports hiding the 2nd field if you configure a Meta tag in index.html.

Two-factor Policies Summary

ADC has two methods of configuring multi-factor authentication:

  • Citrix Gateway Virtual Server has bind points for Primary and Secondary authentication. This functionality is available in all ADC Editions and is detailed in this post.
    • This is the older method of configuring authentication also known as Classic authentication policies. One challenge with Classic policies is that Citrix Workspace app requires the LDAP and RADIUS fields to be swapped.
  • nFactor Authentication supports unlimited factors, but requires ADC Advanced Edition (formerly known as Enterprise Edition) or ADC Platinum Edition.
    • nFactor is the newer authentication configuration method also known as Advanced authentication policies. With nFactor, there’s no need to swap the LDAP and RADIUS fields for Citrix Workspace app.

Workspace app authentication with a Classic Policy configuration looks like a Window that is very difficult to customize.

Workspace app authentication with an nFactor configuration looks like a webpage that is fully customizable.

See the ADC menu page for additional authentication mechanisms supported by Citrix Gateway. Some require nFactor.

When configuring the Citrix Gateway Virtual Server, you can specify both a Primary authentication policy, and a Secondary authentication policy. Users are required to successfully authenticate against both policies before being authorized for Citrix Gateway.

For browser-based StoreFront, you need two authentication policies:

  • Primary = LDAPS authentication policy pointing to Active Directory Domain Controllers.
  • Secondary = RADIUS authentication policy pointing to RSA servers with RADIUS enabled.

For Citrix Workspace app, the classic authentication policies need to be swapped. There’s no need to swap them if doing nFactor (Advanced) policies.

  • Primary = RADIUS authentication policy pointing to RSA servers with RADIUS enabled.
  • Secondary = LDAPS authentication policy pointing to Active Directory Domain Controllers.

With Classic Authentication Policies, if you need to support two-factor authentication from both web browsers and Citrix Workspace app, then you’ll need at least four authentication policies as shown below.

Primary:

  • Priority 90 = RADIUS policy. Expression = REQ.HTTP..HEADER User-Agent CONTAINS CitrixReceiver
  • Priority 100 = LDAP policy. Expression = REQ.HTTP..HEADER User-Agent NOTCONTAINS CitrixReceiver

Secondary:

  • Priority 90 = LDAP policy. Expression = REQ.HTTP..HEADER User-Agent CONTAINS CitrixReceiver
  • Priority 100 = RADIUS policy. Expression = REQ.HTTP..HEADER User-Agent NOTCONTAINS CitrixReceiver

LDAP Server/Action

See the LDAP post for instructions to create an LDAP Server/Action. Only the LDAP server/action is needed. The Policies will be created later.

RADIUS Server/Action

Create a RADIUS Server/Action:

  1. On the left, expand Authentication, and click Dashboard.
  2. On the right, click Add.
  3. Change Choose Server Type to RADIUS.
  4. Give the server a name.
  5. Specify the IP address of the RADIUS load balancing Virtual Server.
  6. Enter the secret key specified when you added the ADCs as RADIUS clients on the RADIUS server. Click Test RADIUS Reachability.
  7. Scroll down, and click More.
  8. Find the Password Encoding drop-down. Change it to mschapv2 if your RADIUS server supports it, c. Microsoft NPS requires mschapv2 to support changing expired Active Directory passwords. 💡
  9. If you want ADC to receive AAA Group information from RADIUS, see CTX222260 Radius Group Extraction from Windows Server 2008/2012 with NetScaler/CloudBridge.
    • RADIUS attribute = 26 (Vendor-Specific)
    • Vendor Code = 3845 (Citrix)
    • Vendor-assigned attribute number = any number (e.g. 1). Configure RADIUS policy on ADC with same attribute number.
    • Attribute value = Group Name
  10. Click Create.

    add authentication radiusAction RSA -serverIP 10.2.2.210 -serverPort 1812 -authTimeout 60 -radKey Passw0rd -passEncoding mschapv2

Advanced Authentication (nFactor) Policies for LDAP and RADIUS

For the older Classic Authentication policies, jump ahead to the Classic Policies section.

Create Advanced Authentication Policies:

  1. In the left menu, go to Security > AAA – Application Traffic > Policies > Authentication > Advanced Policies > Policy.
  2. On the right, click Add.
  3. In the Create Authentication Policy window:
    1. Change the Action Type to RADIUS.
    2. Select your RADIUS Action.
    3. Give the policy a name.
    4. Expression = true.
  4. Click Create.
  5. Create another Authentication Policy.
    1. Set Action Type to LDAP.
    2. Select your LDAP Action/Server.
    3. Give the policy a name.
    4. Expression = true.
  6. Click Create.

Create a Policy Label for the second factor, which is typically the RADIUS policy. The first factor (LDAP) does not need a Policy Label.

  1. In the left menu, click Policy Label.
  2. On the right, click Add.
  3. Give the Policy Label a name.
  4. Leave Login Schema set to LSCHEMA_INT. The Login Schema in the first factor will collect both password and passcode in one form so there’s no need for the second factor to collect it again.
  5. Click Continue.
  6. In the Select Policy field, select your RADIUS policy.
  7. Click Bind at the bottom of the page.
  8. Click Done to finish creating the Policy Label.

Create a Login Schema to collect the password and passcode on the same form.

  1. In the left menu, click Login Schema.
  2. On the right, switch to the tab named Profiles and then click Add.
  3. Give the Login Schema a name (e.g. DualAuth).
  4. Click the pencil icon and then open the LoginSchema folder.
  5. Click the DualAuth.xml file on the left. On the right, make sure you click the blue Select button. It’s too easy to miss this step.
    • See my nFactor article for some info on how to customize the Login Schema.
  6. Then click Create.
  7. On the right, switch to the tab named Policies.
  8. Give the Login Schema Policy a name.
  9. Select the Login Schema Profile you just created.
  10. Set the Rule field to true.
  11. Click Create.

Create an Authentication (AAA) Virtual Server to link the factors together.

  1. In the left menu, under AAA – Application Traffic, click Virtual Servers.
  2. On the right, click Add.
  3. Change the IP Address Type to Non Addressable.
  4. Give the AAA vServer a name and then click OK.
  5. In the Certificate section, you can optionally bind a certificate. It doesn’t matter what certificate you choose (typically the Gateway cert). The only thing this certificate binding does is make the AAA vServer show as UP instead of DOWN. Otherwise it has no effect on functionality. Click Continue.
  6. In the Advanced Authentication Policies section, click where it says No Authentication Policy.
  7. In the Select Policy field at the top of the window, select the LDAP policy.
  8. Near the bottom, in the Select Next Factor field, click where it says Click to select.
  9. Select your RADIUS Policy Label and then click Bind. After LDAP is done, nFactor will then move to your RADIUS Policy Label.
  10. Click Continue.
  11. On the right, in the Advanced Settings column, click Login Schemas.
  12. On the bottom left, click where it says No Login Schema.
  13. Select the DualAuth Login Schema you created earlier and then click Bind.
  14. Click Done at the bottom of the page.

Link the AAA vServer to your Gateway vServer:

  1. In the left menu, expand Citrix Gateway and then click Virtual Servers.
  2. On the right, edit your Gateway vServer.
  3. On the right, in the Advanced Settings column, click Authentication Profile.
  4. On the bottom left, in the Authentication Profile section, click the Add button.
  5. Select the AAA vServer you created earlier.
  6. Give the Profile a name and then click Create.
  7. Back in the Gateway vServer, make sure you click OK in the Authentication Profile section. If you forget to click OK then the Authentication Profile won’t be bound.

If you point your Workspace app to the Gateway that has nFactor configured, the authentication window will look like a web page.

Classic Authentication Policies for LDAP and RADIUS

For Advanced Authentication (nFactor) policies, jump back to the Advanced Policies section.

  1. Go to Citrix Gateway > Policies > Authentication > RADIUS.
  2. On the right, in the Policies tab, click Add.
  3. In the Create Authentication RADIUS Policy page:
    1. Name the policy RSA-ReceiverSelfService or similar.
    2. Select the RADIUS server created earlier.
    3. Enter an expression. You will need two policies with different expressions. The expression for Receiver Self-Service is REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver.
      Note: Citrix Gateway 12.1 does not natively support binding of Advanced Authentication Policies so you’ll have to create them as Basic Policies (classic expressions). You can only bind Advanced Authentication Policies using nFactor.
  4. Click Create.
  5. If you see a warning about deprecation, click OK, and ignore it.
  6. Create another RADIUS policy to match the ones shown below. Both RADIUS policies are configured with the same RADIUS server. The only difference between them is the expression (CONTAINS vs NOTCONTAINS):
    Name Expression Server
    RSA-ReceiverSelfService REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver RSA
    RSA-ReceiverForWeb REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver RSA

  7. Go to the Citrix Gateway\Policies\Authentication\LDAP node.
  8. On the Policies tab, create two policies with the expressions shown below. Both LDAP policies are configured with the same LDAP server. The only difference between them is the expression (CONTAINS vs NOTCONTAINS).
    Name Expression Server
    LDAP-Corp-ReceiverSelfService REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver LDAP-Corp
    LDAP-Corp-ReceiverForWeb REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver LDAP-Corp 

add authentication radiusPolicy RSA-ReceiverForWeb "REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver" RSA

add authentication radiusPolicy RSA-ReceiverSelfService "REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver" RSA

add authentication ldapPolicy Corp-Gateway-ReceiverForWeb "REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver" Corp-Gateway

add authentication ldapPolicy Corp-Gateway-ReceiverSelfService "REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver" Corp-Gateway

Bind Two-factor Policies to Gateway

  1. When you create or edit a Citrix Gateway Virtual Server, bind the Basic Authentication Policies as shown in the following table. Priority doesn’t matter because they are mutually exclusive.
    Policy Name Type Bind Point
    LDAP-Corp-ReceiverForWeb LDAP Primary
    RSA-ReceiverSelfService RADIUS Primary
    LDAP-Corp-ReceiverSelfService LDAP Secondary
    RSA-ReceiverForWeb RADIUS Secondary 

    bind vpn vserver gateway.corp.com -policy Corp-Gateway-ReceiverForWeb -priority 100

bind vpn vserver gateway.corp.com -policy RSA-ReceiverSelfService -priority 110

bind vpn vserver gateway.corp.com -policy RSA-ReceiverForWeb -priority 100 -secondary

bind vpn vserver gateway.corp.com -policy Corp-Gateway-ReceiverSelfService -priority 110 -secondary
  2. The Session Policy/Profile for Receiver Self-Service needs to be adjusted to indicate which authentication field contains the Active Directory password. On the Client Experience tab is Credential Index. This needs to be changed to SECONDARY. Leave the session policy for Web Browsers set to Primary.

    set vpn sessionAction "Receiver Self-Service" -ssoCredential SECONDARY
  3. On the StoreFront server, when creating the Citrix Gateway object, on the Authentication Settings page, change the Logon type to Domain and security token. This instructs Receiver / Workspace app to properly handle two-factor authentication. If you change this setting after Receiver / Workspace app has already performed discovery, then users might have to remove the Account from Receiver / Workspace app and re-add it.

Citrix Workspace app 2409.1

Last Modified: Dec 13, 2024 @ 9:53 am

689 Comments

Navigation

Workspace app is the new name for Receiver. This post applies to all Workspace app versions, including the Current Release version 2409.1 and the LTSR version 2402 CU2.

💡 = Recently Updated

Change Log

Workspace app Versions

Citrix Workspace app uses a YYMM (year/month) versioning format, of which version 2409.1 (24.9.1.207) is the newest Current Release. See Citrix Docs for the list of new features, some of which only apply to Citrix Cloud.

Workspace app 2311 and newer have a new installer interface. 

Workspace app 2303 and newer automatically install the App protection components with an option to start them after installation. Older Workspace apps have an option to install App protection and if you don’t select this and later want App protection then you must uninstall Workspace app and reinstall it.


  • See App Protection at Citrix Docs to enable App protection for the authentication screen. Workspace app 2305.1 and newer automatically start it for authentication if you have selected the Start App Protection check box during installation.

The newest Current Release version of Workspace app is version 2409.1.

The newest LTSR (Long Term Service Release) version of Workspace app is version 2402 Cumulative Update 2.

Workspace app Modules

The Workspace app installer deploys multiple modules. Here are the important ones:

  • ICA Engine (wfica.exe) – process that uses the ICA protocol to connect to published apps and desktops.
  • Self-Service (selfservice.exe) – gets icons from StoreFront and displays them in a Window. When an icon is clicked, Self-service passes the ICA file to the ICA Engine to establish a connection.
  • Single Sign-on (SSON) for ICA (ssonsvr.exe) – captures user credentials and submits them to VDAs after an ICA connection is established
  • Workspace Auto-Update (CitrixReceiverUpdater.exe) – Notifies users of Workspace app updates. The most recent name for this component is Citrix Workspace Update.

Custom ICA files are no longer supported. However, Ryan Butler has created a script that asks StoreFront for an ICA file. Explicit credentials are supported. Find the script at Github.

Workspace app Discovery and Beacon Process

If you are using Workspace app’s built-in user interface (instead of a web browser), then Workspace app first prompts you to perform discovery, which is also called Add Account.

Workspace app will contact the FQDN and request download of the StoreFront Provisioning File.

  • If you entered a StoreFront FQDN, then Workspace app will download the Provisioning File directly from the StoreFront server.
  • If you entered a Gateway FQDN, then Gateway will first prompt the user to authenticate. After authentication, Gateway will connect to its configured Account Services address, and download the Provisioning File from StoreFront. The Account Services address is configured in the NetScaler Gateway Session Profile on the Published Applications tab.

If your StoreFront server is configured with multiple stores, then the user will be prompted to select a store. Unfortunately, there’s no configuration option in NetScaler Gateway to force a particular store.

The Provisioning File downloaded from StoreFront is an XML document containing values for several items configured in the StoreFront console. You can export the Provisioning File from the StoreFront console by right-clicking a Store.

The ReceiverConfig.cr Provisioning File looks something like this:

Here are the values in the Provisioning File:

  • Address – the Base URL configured in StoreFront Console
  • Internal Beacon – as configured in StoreFront Console. This can be the Base URL, or a manually specified URL.
  • External Beacons – as configured in StoreFront Console
  • Gateways – as configured in StoreFront Console. If there are multiple Gateways, when enabling Remote Access on the Store, then only one Gateway is selected as Default
  • SRID – Store ID. An important value to consider for multi-datacenter configurations. The SRID is set when the Store is created. It can also be changed by editing C:\inetpub\wwwroot\Citrix\Roaming\web.config.

Workspace app reads the Provisioning File, and configures itself by inserting the file’s contents into the user’s registry. The values are located under HKCU\Software\Citrix\Dazzle\Sites and HKCU\Software\Citrix\Receiver\SR. If you performed discovery through NetScaler Gateway, notice that the internal Base URL is added to the user’s registry.

Once Workspace app is configured, it then performs the following steps:

  1. Attempt to connect to the Internal Beacon.
  2. If the Internal Beacon is reachable, connect directly to the StoreFront Base URL (Address).
  3. If the Internal Beacon is not reachable:
    1. Attempt to connect to the External Beacons. If the External Beacons are not reachable, then stop attempting to connect.
    2. Connect to the Gateway address configured in the Provisioning File. If there is more than one Gateway, connect to the Gateway that is marked as the Default.

Here are some interesting notes on this connection process:

  • The FQDN you entered during Discovery has absolutely nothing to do with how Workspace app connects to StoreFront or Gateway. The actual connection process is controlled by the contents of the Provisioning File, not the Discovery address.
  • If the Provisioning File has multiple Gateways defined, Workspace app uses whichever Gateway is marked as Default. Workspace app completely ignores whatever Gateway FQDN you entered during Discovery. To use a non-default Gateway, the user must manually select the other Gateway in Workspace app’s Advanced Preferences.

In StoreFront Console, if any configuration changes are performed that affect the Provisioning File, it takes an hour for Workspace apps to reconfigure themselves automatically. Or users can remove Accounts and re-add (or Reset Citrix Workspace) so that the updated Provisioning File is imported.

Here are some additional methods of performing Workspace app Discovery:

  • After exporting the Provisioning File from StoreFront Console, distribute it to users, and ask them to double-click it.


  • After logging in to Receiver for Web (StoreFront), at the top right, click the username, and click Activate. This downloads the receiverconfig.cr file, which is identical to the one you can export from StoreFront Console. The user then must run the downloaded file.

Virtual Monitors

In Workspace app 1812 and newer, when connected to a published desktop on a single monitor, you can split the screen into virtual monitors. This feature is intended for large 4K monitors.

  • In the desktop toolbar at the top of the screen, click Preferences.
  • Switch to the Monitor Layout tab.
  • On the bottom, select Horizontal or Vertical, then click somewhere in the blue box to draw a line. The single monitor will be split along this line. You can set different DPI for each portion of the virtual display.
  • Right-clicking one of the split sections changes that section to the primary display.
  • Click OK when done.
  • In the toolbar, click Window to resize it to a window, and then click Full Screen to cause your virtual monitor configuration to take effect.

Uninstall Old Clients

Workspace app installer can do a force uninstall of old clients before installing the new version:

  • In Workspace app 2309 and newer, run CitrixWorkspaceApp.exe /CleanInstall /Silent
  • In Workspace app 1909 and newer, run CitrixWorkspaceApp.exe /ForceInstall /Silent.
  • In Workspace app 1908 and older (including Receiver), run CitrixWorkspaceApp.exe /RCU /Silent or CitrixReceiver.exe /RCU /Silent.

Citrix CTX325140: How to Remove Client Files Remaining on System after Uninstalling Receiver for Windows.

Installation and Configuration

Administrator privileges – Administrator privileges are required to install any missing prerequisites.

Internet required – Recent versions of Workspace app download and install Microsoft Edge WebView2 Runtime, .NET Desktop Runtime 6.0.20, .NET Framework 4.8, and Visual C++. Internet access is required for the Workspace app installer to download these install files. Or there’s an Offline Installer for Workspace app 2309 and newer.

.NET Desktop Runtime 6.0.20 – Workspace app 2309 and newer will install x86 .NET Desktop Runtime 6.0.20 if it’s not already installed.

This section contains a summary of all common command line switches, registry keys, and policy settings for Workspace app.

Links:

Workspace app 2203 LTSR CU2 and Workspace app 2212 and newer fix security vulnerabilities.

CitrixWorkspaceApp.exe current release version 2409.1 or LTSR version 2402 CU2 can be installed by simply double-clicking it.

  • LTSR Workspace app does not support Browser Content Redirection.
  • Workspace app 2006 and newer do not support Windows 7.
  • Workspace app 2206 and newer enable DPI Matching by default. DPI Matching can be disabled through client-side group policy, or in the Advanced Preferences in Workspace app 2212 and newer. DPI Matching prevents connections to CVAD 7.15. Multi-session VDAs with version 1912, by default, have DPI Matching disabled, but can be enabled in the VDA’s registry. See CTX460068 for details.
  • Workspace app 2311 and newer have a new interface for installation.

  • Workspace app 2402 and newer ask if you want to install the Microsoft Teams VDI Plugin or not. This is for Teams 2.1 and newer.


Administrator vs non-administrator

  • Non-administrator – If a non-administrator installs Workspace app, then each non-administrator that logs in to the same workstation will have to reinstall Workspace app.
    • Non-administrator installations are installed to %USERPROFILE%\AppData\Local\Citrix\ICA Client for each user.
  • Administrator – If CitrixWorkspaceApp.exe is installed using an administrator account. then the Workspace app only needs to be installed once.
    • Administrator installations are installed to C:\Program Files (x86)\Citrix\ICA Client.
    • Administrator installations of Workspace app 1912 and newer can be manually upgraded by non-administrators by clicking Check for Updates. Older versions cannot be upgraded by non-administrators.
  • Conflicts – If an administrator install of Workspace app is performed on a machine that has non-administrator installs of Workspace app, then the two installations will conflict. Best option is to uninstall non-admin Workspace app and Receiver before installing admin Workspace app. Otherwise, the user’s profile probably has to be reset before Workspace app is functional again.

Global App Configuration Service

Global App Configuration Service (GACS) is a Citrix Cloud service that can push configurations to Workspace app clients. This Citrix Cloud service is now available to all on-premises customers even if you don’t own any Citrix Cloud entitlements.

  1. Login to https://citrix.cloud.com. If you don’t have a Citrix Cloud account, then login using your Citrix.com account credentials and it will create a Citrix Cloud account.
  2. Use the top left hamburger menu to go to Workspace Configuration.
  3. Switch to the tab named App Configuration.
  4. Click Switch URL.
  5. Near the bottom, click Claim URL.
  6. Click Add URL to add your on-premises StoreFront/Gateway URL. See Citrix Docs for details. GACS uses this URL to determine which Workspace app clients should receive the settings that you configure.
  7. Back in the App Configuration page, you can now configure Workspace app settings as desired. Workspace apps that have stores under the claimed URL will then receive these settings.

Auto-Update

Workspace app supports auto-update.

Some notes:

  • If Workspace app 1912 or newer is installed as administrator, then non-administrators can click Check for Updates to manually update Workspace app. To prevent this, use group policy to disable Citrix Workspace Updates.

    • Older versions of Workspace app cannot be upgraded by non-administrators.
  • If Workspace app is installed on a VDA, auto-update is automatically disabled. This includes Remote PC.
  • Auto-update can be limited to LTSR updates only.
  • Auto-update is configurable through several mechanisms: group policy, StoreFront, Workspace app GUI, installer command line. See Configuring Citrix Workspace Updates at Citrix Docs.
  • Workspace app 2107 and later let users select an Update channel.

  • See George Spiers Citrix Receiver for Windows Auto-Update.

Auto-update is configured using Workspace app group policy under the Citrix Workspace Updates, or Auto-Update node.


Or use Global App Configuration Service.

Workspace app Splash Screen

Workspace app shows a Splash Screen on first launch with the text “Citrix Workspace app extends the capabilities of Citrix Receiver”.

To prevent this splash screen, set the following registry value: (source = Dennis Span on Twitter)

  • Key = HKEY_CURRENT_USER\SOFTWARE\Citrix\Splashscreen
    • Value (REG_SZ) = SplashscreenShown = 1

Add Account Wizard

After installation, Workspace app will launch and ask you to add an account. If Workspace app, notice the checkbox Do not show this window automatically at logon.

FTU (First Time Use aka Add Account Wizard) will be displayed only if a store is not configured. If a store is already configured via command line, GPO, or Citrix Studio, then FTU screen will not be available after installation. Otherwise, FTU can be suppressed by doing one of the following:

  • Rename CitrixWorkspaceApp.exe to CitrixWorkspaceAppWeb.exe.
  • Install using a command line switch:
    • CitrixWorkspaceApp.exe /ALLOWADDSTORE=N
  • Set the registry value: HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Citrix\EnableFTU=dword:00000000 (or EnableX1FTU =dword:0)
  • Disable the EnableFTU policy setting in Receiver.admx.
  • Change Registry values post installation to suppress the Add Account window. Under HKLM\Software\Wow6432Node\Citrix\Dazzle, set AllowAddStore value to N.
  • Set the registry value: HKEY_LOCAL_MACHINE\Software\Citrix\Receiver\NeverShowConfigurationWizard (REG_SZ) = true
  • Also see Suppressing Add Account dialog at Citrix Docs.

Discover Hidden Stores

When Workspace app is first launched, it must perform Discovery, which is the process of downloading the .xml provisioning file from StoreFront. Discovery is performed by entering a StoreFront FQDN or Gateway FQDN. To discover a hidden store (a store that’s not advertised), add ?StoreName to the end of the FQDN. CTX214819 How to configure Receiver to a Store that is not advertised.

CitrixWorkspaceApp.exe Command line switches

CTX227370 Citrix Workspace app Commandline Tool contains a GUI tool to build your installer command line.
image.png

For unattended installation of Workspace app, see CTA Dennis Span Citrix Workspace App unattended installation with PowerShell or Citrix Receiver unattended installation with PowerShell.

Installer Command Line Switches are detailed at Configure and install Receiver for Windows using command-line parameters at Citrix Docs. Common Command line switches include the following:

  • /silent
  • /includeSSON – enables pass-through authentication. GPO configuration is also required as detailed below. 
    CitrixWorkspaceApp.exe /includeSSON
  • /ALLOWADDSTORE=A – by default, only SSL (HTTPS) stores are accepted. To allow non-SSL stores: 
    CitrixWorkspaceApp.exe /ALLOWADDSTORE=A
  • /STORE0 – To add a store from the installation command line: 
    CitrixWorkspaceApp.exe STORE0="AppStore;https://Citrix.corp.com/Citrix/MyStore/discovery;on;App Store"
    • Workspace App can discover the Store through NetScaler Gateway. 
      CitrixWorkspaceApp.exe STORE0="AppStore;https://gateway.corp.com#MyStore;On;App Store"
  • /SELFSERVICEMODE=False – disables the Self-Service interface and enables shortcut-only mode: 
    CitrixWorkspaceApp.exe /SELFSERVICEMODE=False
  • /AutoUpdateCheck=auto /AutoUpdateStream=LTSR – enables Citrix Workspace Update notifications and sets it to LTSR Branch only. AutoUpdateCheck can also be set to manual or disabled. AutoUpdateStream can also be set to Current. See Configuring Citrix Workspace Updates at Citrix Docs. 
    CitrixWorkspaceApp.exe /AutoUpdateCheck=auto /AutoUpdateStream=LTSR
  • /ENABLEPRELAUNCH=True – enables prelaunch: 
    CitrixWorkspaceApp.exe /ENABLEPRELAUNCH=True
  • /ALLOW_CLIENTHOSTEDAPPSURL=1 – enables Local App Access: 
    CitrixWorkspaceApp.exe /ALLOW_CLIENTHOSTEDAPPSURL=1

Registry values

HKLM\Software\Wow6432Node\Citrix\Dazzle on the Workspace app machine. All are of type REG_SZ (string) unless specified. Note: several of these are configurable using the Reciever.admx group policy template.

  • SelfServiceMode (REG_SZ) = False – Turns off Workspace app’s Self-Service interface.
  • PutShortcutsOnDesktop (REG_SZ) = True – If Self-Service interface is disabled, places all shortcuts on desktop.
  • UseDifferentPathsforStartmenuAndDesktop (REG_SZ) = True
    • UseCategoryAsStartMenuPath (REG_SZ) = True or False
    • UseCategoryAsDesktopPath (REG_SZ) = True or False
  • StartMenuDir (REG_SZ) = name of folder on Start Menu where shortcuts are placed.
  • DesktopDir (REG_SZ) = name of folder on Desktop where shortcuts are placed
  • EnablePreLaunch (REG_SZ) = True – If SSON is enabled then PreLaunch is already enabled by default.
  • AllowAddStore (REG_SZ) = A – Only if using http (instead of https) to connect to StoreFront.
  • AllowSavePwd (REG_SZ) = A – Only if using http (instead of https) to connect to StoreFront.
  • UserDomainName (REG_SZ) = pre-filled domain name
  • InitialRefreshMinMs (REG_SZ) = 1 – minimizes the launch delay before contacting store
  • InitialRefreshMaxMs (REG_SZ) = 1 – minimizes the launch delay before contacting store
  • RefreshMs (REG_SZ) = 3600000 (1 hour) – interval for Receiver icon refreshes. 1 hour is the default value.
  • MaxSimultaneousFetches (REG_DWORD) = 6  – improves the time of loading icons in Start Menu
  • MaxSimultaneousSubscribes (REG_DWORD) = 6 – improves the time of loading icons in Start Menu
  • DontWarnOfRemovedResources (REG_SZ) = True – prevents dialog boxes when resources are removed from the server. (or False)
  • SilentlyUninstallRemovedResources (REG_SZ) = True – prevents dialog boxes when resources are removed from the server
  • PreferTemplateDirectory (REG_SZ) = UNC path or local path containing shortcuts copied by the prefer keyword. Give the shortcuts a short name.
  • PnaSSONEnabled (REG_SZ) = True – Enables Single Sign-on for PNAgent (Web Interface).
  • WSCReconnectMode (REG_SZ) = 3 (default) – If this Workspace app is running inside a VDA published desktop, set it to 0.
  • AlwaysUseStubs (REG_SZ) = True. Workspace app and Receiver 4.3.100 and newer don’t create .exe stubs by default. Set this to create .exe stubs. Also see Citrix CTX211893 Controlling Shortcut behavior in Receiver 4.3.100.
  • DontCreateAddRemoveEntry (REG_SZ) = True – don’t create “Delivered by Citrix” entries in Programs and Features
  • DesktopNameFormatString = format string for shortcut names – For example “{0}_{1}_{2}_{3}”. See the link for details.
  • SelfServiceFlags (REG_DWORD) = 4 – prevents duplicate shortcuts when roaming and Desktop is redirected.
  • ReEvaluateNetwork (REG_SZ) = true – for Beacon detection with Single FQDN

To prevent the Win+G popup on Windows 10 machines:

  • HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows\GameDVR
    • AllowGameDVR (REG_DWORD) = 0

To allow adding non-HTTPS stores to Workspace app:

  • HKLM\Software\Wow6432Node\Citrix\AuthManager
    • ConnectionSecurityMode (REG_SZ) = Any

To increase ICA bandwidth consumption over high latency links, set:

  • HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\ICA Client\Engine\Configuration\Advanced\Modules\TCP/IP

To prevent beacon probing from using proxy, set:

  • HKEY_LOCAL_MACHINE\Software\WOW6432Node\Citrix\Receiver\inventory
    • BeaconProxyEnabled (REG_DWORD) = 0

To enable foreground progress bar, set:

  • HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\ICA Client
    • ForegroundProgressBar (REG_DWORD) = 1

For client-to-server file type redirection, set:

  • HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\ICA Client\Engine\Configuration\Advanced\Modules\ClientDrive
    • NativeDriveMapping=”TRUE”

To fix USB devices that emulate a keyboard, set:

  • HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\ICA Client\Engine\Lockdown Profiles\All Regions\Lockdown\Virtual Channels\Keyboard
    • KeyboardTimer=”10”

To remember manually mapped USB devices when auto-connection is enabled, set: (2409 and newer)

  • HKLM\SOFTWARE\Citrix\ICA Client\GenericUSB (same path for 32-bit and 64-bit, create the keys)
    • RememberConnections (DWORD) = 0x1

To override the devices that are mapped using optimized channels instead of generic USB, see Citrix CTX123015 How to Configure Automatic Redirection of USB Devices

Group Policy Settings

Copy the Workspace app ADMX template (C:\Program Files (x86)\Citrix\ICA Client\Configuration\receiver.admx) to C:\Windows\PolicyDefinitions (or Sysvol). Also copy receiver.adml to C:\Windows\PolicyDefinitions\en-us (or Sysvol).

Edit a GPO that applies to client machines, go to Computer Configuration | Policies | Administrative Templates | Citrix Components | Citrix Workspace and configure the following:

  • To enable pass-through authentication: go to | User Authentication |.
  • To add a store, go to | StoreFront |
    • StoreFront Accounts List – see the help text
  • To enable Auto-Update, go to | AutoUpdate | or | Citrix Workspace Updates |. (the node was renamed in 4.11 and Workspace app)
    • Enable or Disable AutoUpdate or
    • Citrix Workspace Updates
  • To modify the desktop viewer toolbar, go to | Client Engine |
    • Desktop Viewer Toolbar Options (2409 and newer)
  • To enable Local App Access, go to | User Experience |
    • Local App Access Settings
  • To prevent the endpoint from sleeping while session is active, go to | User Experience |
    • Power Management (2405 and newer)
  • To configure the Self-Service interface, go to | SelfService |
    • Set Manage SelfServiceMode to Disabled to completely disable the Self-Service window. This causes all icons to be placed on the Start Menu.
    • Enable Manage App Shortcut and configure it as desired.
      • To allow the Self-Service window, but prevent it from automatically opening (reside in systray), tick Prevent Citrix Workspace performing a refresh of the application list when opened. Source
    • Enable Control when Workspace attempts to reconnect to existing sessions. If this is a VDA published desktop, set it to Disabled. Otherwise configure it as desired.
    • Set Enable FTU to Disabled  to prevent the Add Account wizard from displaying.
    • Enable Allow/Prevent users to publish unsafe content if publishing content that’s opens a file or file share.

Enable automatic client drive and client microphone mapping:

  • In a client-side GPO, add the GPO ADM template from http://support.citrix.com/article/CTX133565.
  • Enable the setting Create Client Selective Trust Keys. See Below for details.
  • Configure the FileSecurityPermission setting in one or more of the regions.
  • Configure the MicrophoneAndWebcamSecurityPermission setting in one or more of the regions.

Citrix CTX203658 Start Menu Icons Set to Default (Blank Document) After Update to Receiver 4.3.100 – Windows 8 and newer

  • Computer Configuration | Policies | Administrative Templates | Windows Components | File Explorer
    • Allow the use of remote paths in file shortcut icons = enabled

For Single Sign-on in Windows 11 24H2 and newer, enable the following GPO setting:

  • Computer Configuration | Policies | Administrative Templates | Windows Components | Windows Logon Options
    • Enable MPR notifications for the System = enabled

Deploy Workspace app using Active Directory

To deploy Workspace app using Active Directory, configure a GPO with a computer startup script that runs the Workspace app installer executable. Citrix provides sample scripts that can be downloaded from one of the Workspace app download pages (Workspace app current release version 2409.1, or LTSR version 2402 CU2, by expanding Downloads for Admins (Deployment Tools).

Also see CTA Dennis Span Citrix Receiver unattended installation with PowerShell.

Change Workspace App’s Store Configuration, including Reset Citrix Workspace

You can change Workspace app’s configured Store/Account with a couple command lines:

"C:\Program Files (x86)\Citrix\ICA Client\SelfServicePlugin\SelfService.exe" -deleteproviderbyname Corporate 
"C:\Program Files (x86)\Citrix\ICA Client\SelfServicePlugin\SelfService.exe" -init -createprovider Corporate https://storefront.corp.com/Citrix/Store/discovery

 

It is sometimes necessary to Reset Citrix Workspace by right-clicking the Workspace app systray icon, clicking Advanced Preferences, and clicking the Reset link. You can do this from the command line by running "C:\Program Files (x86)\Citrix\ICA Client\SelfServicePlugin\CleanUp.exe" -cleanUser -silent. See CTX140149 How to Reset Receiver Using the Command Line.

Workspace app Group Policy ADMX Template

Many of the Workspace app configuration settings must be configured in group policy. These Workspace app settings are only available after installing the GPO templates.

Alternatively, Citrix Cloud customers can use Global App Configuration Service to configure Workspace app. Today it’s a REST API, but Citrix has started adding a GUI at Workspace Configuration > App Configuration.

For GPO configuration:

  1. From a machine that has Workspace app installed, find the .admx and .adml files in the C:\Program Files (x86)\Citrix\ICA Client\Configuration.
    • You can also download the ADMX files from one of the Workspace app download pages (Workspace app current release version 2409.1, LTSR version 2402 CU2, by expanding Downloads for Admins (Deployment Tools).
  2. Copy the CitrixBase.admx and receiver.admx files. Also copy the en-US folder. In Workspace app, the files are still named receiver.admx.
  3. Go to your domain’s SYSVOL share and in the Policies folder look for a PolicyDefinitions folder. If one exists, paste the .admx file directly into the PolicyDefinitions folder. If this folder doesn’t exist in SYSVOL, instead copy the .admx file to C:\Windows\PolicyDefinitions. Overwrite any existing Receiver ADMX files.
  4. The GPO settings can then be found at one of the following:
    • Computer Configuration > Policies > Administrative Templates > Citrix Components > Citrix Workspace
    • Computer Configuration > Policies > Administrative Templates > Citrix Components > Citrix Receiver
  5. For example, you can disable Customer Experience Improvement Program (CEIP) from here.
  6. See https://www.carlstalhood.com/delivery-controller-cr-and-licensing/#ceip for additional places where CEIP is enabled.
  7. Workspace app 1905 and newer has a setting to Disable sending data to 3rd party (e.g., Google Analytics).
  8. Workspace app 1905 and newer let you disable embedded browser caching.
  9. Workspace app 1905 and newer have NetScaler LAN Proxy under Network routing > Proxy.
  10. Workspace app 1808 and newer have User authentication | Single Sign-on for NetScaler Gateway.
  11. Citrix Workspace Updates, (aka AutoUpdate) can be configured using group policy. See Configuring Citrix Workspace Updates at Citrix Docs.
  12. Workspace app 1912 and newer can be configured to require in-memory ICA files only. The setting called Secure ICA file session launch is under the Client Engine node. See Citrix Docs for details on in-memory ICA files instead of writing ICA files to disk.
  13. The DPI node has a setting called High DPI that lets you disable DPI matching, which is enabled by default in Workspace App 2206 and newer.

    • Workspace app 2210 and newer let you use the GUI to re-enable High DPI.
    • Native resolution means DPI matching, whereas Yes means force high DPI.
  14. Workspace app has settings to hide Advanced Preferences, enable/disable showing the DPI option, and enable/disable H265.
  15. Workspace app 4.8 and newer have SplitDevices GPO setting under Citrix Workspace | Remoting client devices | Generic USB Remoting. See Configuring composite USB device redirection at Citrix Docs.
  16. Workspace app 2212 and newer by default disable App Protection for the authentication screen and icons list. To enable them, configure User authentication | Manage App Protection and SelfService | Manage App Protection.

  17. Workspace app 2303 and newer have Anti-DLL Injection for App Protection. It is disabled by default. Enable it in a GPO at Citrix Components | Citrix Workspace | App Protection | Anti-DLL Injection. See Citrix Docs for details.
    App running

Pass-through Authentication

Citrix blog post – A Comprehensive Guide to Enabling Pass-Through Authentication with XenDesktop 7.5

  1. Run the command
    Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $True from a Windows PowerShell command prompt on a Delivery Controller.

  2. Login to the PC as an administrator.
  3. If installing Workspace app, as an administrator, during installation, on the Enable Single Sign-on page, check the box next to Enable Single Sign-on. Then finish the installation.

  4. To verify that SSON is installed, go to C:\Program Files (x86)\Citrix\ICA Client and look for the file ssonsvr.exe.
  5. And if you open regedit and go to HKLM\SYSTEM\CurrentControlSet\Control\NetworkProvider\Order, you should see PnSson in the ProviderOrder.
  6. Install the receiver.admx (and .adml) template into PolicyDefinitions if you haven’t already.
  7. Edit a GPO that is applied to the client PCs where the Workspace app is installed.
  8. Go to Computer Configuration > Policies > Administrative Templates > Citrix Components > Citrix Workspace.
  9. Expand Citrix Workspace and click User authentication.
  10. On the right, double-click Local user name and password.
  11. Select Enabled and then check the box next to Allow pass-through authentication for all ICA connections. Click OK.
  12. In Workspace app 1808 and newer, you can enable Single Sign-on for NetScaler Gateway.
  13. Ensure that the internal StoreFront FQDN is in the Local Intranet zone in Internet Explorer. You can use a GPO to configure this on the client side.
  14. Local Intranet zone should have Automatic logon only in Intranet zone enabled.
  15. For Windows 11 24H2 and newer, make sure the GPO setting Enable MPR notifications for the System is enabled at Computer Configuration | Policies | Administrative Templates | Windows Components | Windows Logon Options. Make sure HKLM\Software\Microsoft\Windows\CurrentVersion\Policies\System\EnableMPRNotifications is set to 1 on the Workspace app machine.
  16. Logoff Windows and log back on. In Task Manager you should now see ssonsvr.exe. This won’t appear unless you logoff and log back on.
  17. If Workspace app won’t connect or is slow to enumerate icons, then you might have to disable Automatically detect settings in IE.
  18. Right-click the Workspace app icon and click Advanced Preferences.
  19. Click Configuration Checker.
  20. Check the box next to SSONChecker and click Run.
  21. The lines with red x will indicate the issue and corrective action.

StoreFront Accounts

You can use a client-side GPO to add a store (Account) to Workspace app Self-Service.

  1. Install the receiver.admx (and .adml) template into PolicyDefinitions if you haven’t already.
  2. Edit a GPO that applies to endpoint devices that have Citrix Workspace app installed.
  3. Go to Computer Configuration > Administrative Templates > Policies > Citrix Components > Citrix Workspace > StoreFront.
  4. On the right, double-click NetScaler Gateway URL/StoreFront Accounts List.
  5. Select Enabled, and then click Show.
  6. Enter a store path based on the example shown in the Help box. Workspace app lets you enter a Gateway path. Then click OK.
  7. Note: Gateway paths work in GPO, but might not work when specified in the CitrixWorkspaceApp.exe installation command line.

Published Shortcuts and Reconnect

Citrix CTX200924 How to Customize App Shortcuts with Receiver for Windows

Workspace app has a user interface for setting Shortcut Paths. Right-click the Workspace app systray icon, click Advanced Preferences, and then click Shortcuts and Reconnect, or Settings Option.


From Citrix Docs Configuring application delivery: There are several methods of controlling how Workspace app displays shortcuts on the Start Menu and Desktop as detailed below:

  • Workspace app Registry values
  • receiver.admx GPO Template
  • From StoreFront in C:\inetpub\wwwroot\Citrix\Roaming\web.config
  • Published App Keywords (e.g. prefer).
  • Workspace app and Receiver 4.2.100 and newer supports published app Delivery configuration for adding the shortcut to the desktop. This only works if the app is a Favorite, or if Favorites are disabled, or Mandatory Store.

Under HKLM\Software\Wow6432Node\Citrix\Dazzle (or HKCU\Software\Wow6432Node\Citrix\Dazzle) are several registry values related to shortcuts. Some of the settings only apply if SelfServiceMode is set to False. Here are some common options:

  • SelfServiceMode – set to False so Receiver disables the Self-Service interface and automatically places all published shortcuts on the Start Menu and/or Desktop. More details in Configuring application delivery at Citrix Docs.
  • PutShortcutsOnDesktop – set to True to place every app on the desktop
  • DesktopDir – Workspace app places every shortcut on the desktop so it’s probably best to place them in a folder.
  • StartMenuDir – If there is potentially a conflict between local apps and remote apps, then you should place the Start Menu shortcuts in a folder.
  • PreferTemplateDirectory (with KEYWORDS:prefer=shortcutname) – copies the shortcutname from the template directory to the Start Menu and/or Desktop.

If you import the receiver.admx (and .adml) into the PolicyDefinitions folder, under Computer Configuration > Administrative Templates > Citrix Components > Citrix Workspace (or Receiver) is a node called SelfService.

Disable the Manage SelfServiceMode setting to hide the Workspace app Window.

Enable the Manage App shortcut setting to control placement of shortcuts.

Workspace app and Receiver 4.2.100 and newer have the ability to configure (or disable) Workspace Control using group policy. Enable the setting Control when Citrix Workspace attempts to reconnect to existing sessions and configure it as desired.

Prelaunch

Staring with Receiver 4.2, prelaunch is automatically enabled if Workspace app is installed with SSON enabled. Otherwise, set registry values to enable prelaunch. Receiver 4.2.100 prevents the prelaunch icon from appearing on the Start Menu.

  • HKLM\Software\[Wow6432Node\]Citrix\Dazzle
    • EnablePreLaunch (REG_SZ) = true or false

Additional customizations can be configured at:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\ICA Client\Prelaunch

  • Name: State
    • REG_SZ: 0 = disable, 1 = just-in-time pre-launch, 2 = scheduled pre-launch
  • Name: Schedule
    • REG_SZ: HH:MM|M:T:W:TH:F:S:SU where HH and MM are hours and minutes. M:T:W:TH:F:S:SU are the days of the week. For example, to enable scheduled pre-launch on Monday, Wednesday, and Friday at 1:45 p.m., set Schedule as Schedule=13:45|1:0:1:0:1:0:0 . The session actually launches between 1:15 p.m. and 1:45 p.m.
  • Name: UserOverride
    • REG_SZ: 0  = HKLM overrides HKCU, 1 = HKCU overrides HKLM

Device Access Behavior (Client Selective Trust)

When connecting to a XenApp/XenDesktop session, you might see the following:

To configure the default behavior, see the Citrix Knowledgebase article How to Configure Default Device Access Behavior of Receiver, XenDesktop and XenApp. Note: there is a bug fixed in Receiver 4.2.100 and newer.

  1. Download the ADMX file from http://support.citrix.com/article/CTX133565.
  2. Copy the .admx and .adml files to PolicyDefinitions (Sysvol, or C:\Windows).
  3. The .adml file goes in the en-US folder.
  4. Edit a GPO that applies to the endpoint devices that are running Receiver.
  5. Go to Computer Configuration | Policies | Administrative Templates | Citrix Components | Citrix Workspace (or Receiver) |  Citrix Client Selective Trust (x64).
  6. Enable the setting Create Client Selective Trust Keys.

  7. Then expand the regions, and configure the permission settings as desired.

Desktop Lock

As an alternative to Workspace app Desktop Lock, see Transformer in Citrix Workspace Environment Manager.

External links:

Use Studio to configure Workspace app Accounts in Published Desktop

In published desktops, Workspace app can be used for placement of shortcuts on the user’s Start Menu and Desktop. Use group policy to hide the common program groups and then use Workspace app to place published applications back on the Start Menu and Desktop based on user’s group membership and subscription preference.

  1. In Citrix Studio, on the left, expand the Configuration node, right-click StoreFront and click Add StoreFront.
  2. Enter a descriptive name for the StoreFront server.
  3. Enter the internal https URL of the load balanced StoreFront servers. Add the path to your store (e.g. /Citrix/Store) and then /discovery on the end of the URL. The full URL would be similar to https://citrix.corp.com/Citrix/Store/discovery. Click OK.
  4. Edit a Delivery Group that has a published desktop and Citrix Workspace app installed.
  5. On the StoreFront page, change the selection to Automatically, using the StoreFront servers selected below, and then check the box next to the StoreFront URL. Click OK. Now when users launch the published desktop, Workspace app will be automatically configured with this URL.

Published Desktop – use Workspace app to control Shortcuts

If you install Workspace app inside a published desktop (Workspace app on a VDA), then Workspace app can get icons from StoreFront and put those icons on the user’s published desktop Start Menu and Desktop. This is an alternative to using a User Experience Management product to control shortcut placement.

Note: Workspace app tends to be slow to create Start Menu shortcuts, so make sure you perform a Proof of Concept to determine how this functionality impacts logon times.

Configuration of Workspace app inside a published desktop is simplified if you have the following minimum versions:

  • Workspace app installed inside the VDA
  • VDA 7.17 or newer
  • StoreFront 3.14 or newer

If you meet these minimum version requirements, then Workspace app installed in the VDA automatically tries to launch published applications on the same local VDA rather than trying to launch them from a different VDA (aka double-hop). This feature is called vPrefer.

Do the following for all versions of Workspace app, VDA, and StoreFront, whether using the Prefer keyword or not:

  1. Make sure Workspace app or Receiver version 4.11 or newer is installed on the VDA.
  2. Install the Workspace app ADMX files if you haven’t already. For vPrefer, make sure they are the ADMX files from Workspace app.
  3. Enable the Group Policy setting Remove common program groups from Start Menu and apply it to non-administrators.
    • This removes all Public (aka All Users) Start Menu shortcuts. Workspace app will re-add the shortcuts based on user group membership.
  4. On the VDA, configure the following Workspace app Registry keys (or corresponding settings in the receiver.admx GPO template):
    • HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\Dazzle\WSCReconnectMode=”0″ so Workspace app doesn’t try to reconnect to the published desktop you’re already running.
    • HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\Dazzle\SelfServiceMode to False. This turns off the Workspace app Self-Service GUI and acts like all icons are subscribed. Otherwise, only subscribed (favorited) icons would be placed on the Start Menu and Desktop.
    • HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\Dazzle\UseCategoryAsStartMenuPath = True. This creates a Start Menu folder based on the published app’s configured Category.
  5. Configure each desired published app to Add shortcut to user’s desktop.

    • Or, configure HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\Dazzle\PutShortcutsOnDesktop = True to place all icons on the desktop.
  6. To control icon placement, configure the following registry values:
    • HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\Dazzle\StartMenuDir to place published applications in a sub-folder. Note: Windows Server 2012 and Windows 10 and newer only supports a single level of Start Menu folders, so setting this effectively turns off published app categories.
    • HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\Dazzle\DesktopDir to place published applications in a sub-folder on the desktop.
  7. Pass-through authentication:
    1. In a GPO that applies to the VDA, import the receiver.admx file, and set Local user name and password to Enabled. Check the box next to Allow pass-through authentication for all ICA connections.
    2. If you’re using Gateway internally, and if Workspace app 1808 or newer, then also enable Single Sign-on for NetScaler Gateway.
    3. In a user-level GPO that applies to the VDA, add the StoreFront FQDN to the Local Intranet zone. Make sure it is not in the Trusted Sites zone, or enable Automatic logon with current user name and password for the Trusted Sites zone.
    4. Make sure ssonsvr.exe is running after you login to the VDA. If not, troubleshoot it.
  8. When configuring Citrix Profile Management, make sure !ctx_startmenu! is not excluded from roaming.
  9. In Citrix Studio, configure a Delivery Group with delivery type = Desktop and Applications. Assign users to the delivery group, and the individual published applications (if visibility is limited).
    1. In Citrix Studio, edit each published application, and on the Delivery tab, specify a category. This will become the Start Menu folder name.
    2. If Workspace app Self Service Mode (GUI) is enabled, in Studio, edit each application, and add KEYWORDS:Auto and/or KEYWORDS:Mandatory to the published application description. This forces the applications to be subscribed/favorited. Only subscribed (or Favorite) apps are displayed in the Start Menu and Desktop. Unless you disable Workspace app’s SelfService interface as described earlier.
    3. Another option is to go to the StoreFront Console, click Stores on the left, and on the right, click Configure Store Settings, and click Disable User Subscriptions. This causes all apps to appear on the Start Menu and/or Desktop depending on Workspace app configuration.
  10. Create a group policy that applies to VDAs, and configure the group policy to define the Store URL for Workspace app similar to https://citrix.corp.com/Citrix/Store/discovery. Replace the FQDN with your load balanced StoreFront FQDN. Also replace the path to the store with your store path. Make sure there is /discovery on the end. By default, Workspace app and Receiver only support https.
    1. Your StoreFront store probably delivers both application and desktop icons. If you want to filter out the desktop icons, then create a new StoreFront store, and configure the Workspace app on the VDA to connect to the new Store.
    2. In StoreFront Console, click the store for VDAs, and click Configure Store Settings. On the Advanced Settings page, in the Filter resources by type row, choose Citrix.MPS.Desktop.
  11. For vPrefer in Workspace app, VDA 7.17 (or newer), and StoreFront 3.14 (or newer), edit a GPO that applies to the VDAs.
    1. Go to Computer Configuration | Policies | Administrative Templates | Citrix Components | Citrix Workspace (or Receiver) | SelfService.
    2. Edit the setting vPrefer. This setting is only in Workspace app ADMX templates from Workspace app.
    3. Set it to Allow all apps. Source = 7.17 vPrefer – not working with 32Bit Apps at Citrix Discussions.
  12. On your Delivery Controller, in PowerShell, run set-brokersite -TrustRequestsSentToTheXmlServicePort $true
    • This is required for Pass-through Authentication from Workspace app.
  13. Configure your client devices to connect to the published desktop.
    1. When users connect to the published desktop, Workspace app will auto-launch and hopefully auto-login.
    2. If Workspace app Self-Service Mode is disabled, all published applications should automatically appear in the Start Menu and Desktop.
    3. If Workspace app Self-Service Mode is enabled, then only applications with KEYWORDS:Auto and/or KEYWORDS:Mandatory in the published application description will be displayed. Users can open the systray icon to subscribe to more applications.
    4. Users can copy icons from the Start Menu to the desktop. Make sure the user Copies the icon and doesn’t Move it.
    5. Users can then launch applications directly from the Start Menu, from the Desktop, or from the Workspace app (if the Self-Service interface is enabled).
    6. If Workspace app 4.11 (or newer), VDA 7.17 (or newer), and StoreFront 3.14 (or newer), then vPrefer is enabled by default. When launching an app icon that came from Workspace app, Workspace app checks the local VDA machine to see if the application can be launched on the local VDA instead of by creating a new Citrix double-hop session.
    7. If the application is installed locally on the VDA then the local application shortcut should launch quickly. If the application is on a different delivery group then a second (double-hop) Citrix HDX/ICA connection will be established.
    8. If the user deletes Workspace app shortcuts from the Start Menu, you can get them back by going to the systray icon and refreshing the applications. Or sometimes you have to reset Workspace app.

If you are running components older than Receiver 4.11, VDA 7.17, and StoreFront 3.14, then you’ll need to configure the prefer keyword to get Receiver delivered icons to launch on the local VDA instead of in a new double-hop Citrix connection.

  1. Enable the Group Policy setting Remove common program groups from Start Menu and apply it to non-administrators.
    1. For applications that are installed on the same VDA that is publishing the desktop, configure Group Policy Preferences to recreate the application shortcuts based on Active Directory group membership. Applications on other delivery groups are handled by Receiver.
    2. Or use the prefer keyword to copy shortcuts from the PreferTemplateDirectory.
  2. On the VDA, configure the following Receiver Registry keys (or corresponding settings in the receiver.admx GPO template):
    • HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\Dazzle\PreferTemplateDirectory = a UNC path or local path containing shortcuts to be copied by the prefer keyword. This can point to C:\ProgramData\Microsoft\Windows\Start Menu.
  3. In Citrix Studio, configure a Delivery Group with delivery type = Desktop and Applications. Assign users to the Delivery Group and the applications (if visibility is limited).
    1. In Studio, edit each application and change KEYWORDS:Prefer to KEYWORDS:prefer. Notice the lower case p. It doesn’t work with uppercase P.
      • With the prefer keyword, if you publish an application that is also created using Group Policy Preferences, the Group Policy Preferences icon will take precedence. This is good. Otherwise the Receiver published application icon would result in a new Citrix double-hop session.
      • See Ralph Jansen Citrix Receiver 4.1 Prefer keyword examples
    2. If using the prefer keyword with the PreferTemplateDirectory, enter it as KEYWORDS:prefer=shortcutname where shortcutname is the name of the shortcut that is copied from the Template directory.
  4. Configure your client devices to connect to the published desktop.
    1. When users connect to the published desktop, Group Policy Preferences will create shortcuts to local applications.
    2. Receiver will auto-launch and hopefully auto-login.
    3. If Receiver Self-Service Mode is disabled, all published applications should automatically appear in the Start Menu and Desktop.
    4. If Receiver Self-Service Mode is enabled then only applications with KEYWORDS:Auto and/or KEYWORDS:Mandatory in the published application description will be displayed. Users can open the systray icon to subscribe to more applications.
    5. For published applications with KEYWORDS:prefer=shortcutname, Receiver should copy icons from the template directory to the Start Menu and/or Desktop. See below for considerations.
    6. Users can copy icons from the Start Menu to the desktop. Make sure the user Copies the icon and doesn’t Move it.
    7. Users can then launch applications directly from the Start Menu, from the Desktop, or from the Receiver (if Self-Service interface is enabled).
    8. If a local shortcut (e.g. Group Policy Preferences shortcut, or copied from template directory) matches a published application with KEYWORDS:prefer then the local shortcut will override the published application icon.
    9. If the application is installed locally on the VDA then the local application shortcut should launch quickly. If the application is on a different delivery group then a second (double-hop) Citrix HDX/ICA connection will be established.
    10. If the user deletes Receiver shortcuts from the Start Menu, you can get them back by going to the systray icon and refreshing the applications. Or sometimes you have to reset Receiver.

Notes regarding Prefer Template Directory

  • Prefer Template Directory can point to C:\ProgramData\Microsoft\Windows\Start Menu, which is the All Users Start Menu.
  • The shortcuts copied from the Prefer Template Directory are renamed to match the published app name.
  • For prefer local apps, any command line parameters specified in the published app are ignored. If you need these command line parameters, add them to the shortcut in the Prefer Template Directory.
  • If you have multiple published apps pointing to the same prefer local shortcut, then only one copy will be made, and it will have the name of only one of the published apps. To workaround this, in the Prefer Template Directory, create separate shortcuts for each published app, and adjust the published app prefer keyword accordingly.
  • Jan Hendrik Meier Automatic Shortcut generation for local installed applications in a Citrix XenDesktop / XenApp 7.x environment has a script that can create shortcuts based on the published apps with prefer keyword. These shortcuts can then be copied to your Prefer Template Directory.

How to Script/Automate Workspace app and Receiver Self-Service

From Citrix Knowledgebase article Driving the Citrix Receiver Self-Service Plug-in Programmatically: by default, Workspace app Self-Service (SSP) activities are driven by user interaction. However, SSP exposes sufficient information for its activities to be scripted.

When SSP builds a shortcut, it builds it to a small stub application in a file %appdata%\Citrix\SelfService\app-name-with-spaces-removed.exe for each resource. These files allow SSP to create a fake ‘install’ record for Add/Remove Software. Running these .exe files causes the application to launch. Note: Workspace app and Receiver 4.3.100 and newer don’t create stubs by default. To enable, set HKLM\Software\Wow6432Node\Citrix\Dazzle\AlwaysUseStubs (REG_SZ) = true.

If you want to drive SSP directly for launch instead of through an .exe stub, look at the keys under HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall. There will be keys in there named farm-name@@server-farm-name.app-friendly-name. In these keys you’ll find a LaunchString value that shows the relevant parameters. These parameters are user-independent and can therefore be cloned from a reference user to a general case. You can copy and reuse these parameters without interpretation.

Running the command selfservice.exe –init –ipoll –exit starts SSP, performs a refresh (interactive poll) from the current provider, and forces a clean exit.

Additional command line parameters are detailed at Driving the Citrix Receiver Self-Service Plug-in Programmatically.

 

Citrix Workspace app come with a .dll file that implements the Citrix Common Connection Manager SDK. You can use the CCM SDK to do the following:

  • Launch Sessions
  • Disconnect Sessions
  • Logoff Sessions
  • Get Session Information

Citrix was kind enough to develop a PowerShell module that calls functions from the .dll. Get the CCMPowershellModule from Github. The PowerShell module contains functions like the following:

  • CCMTerminateApplication
  • CCMLaunchApplication
  • CCMGetActiveSessionCount
  • CCMDisconnectAllSessions

Launcher Scripts

Ryan C Butler Storefront ICA file creator at Github. See Create an ICA File from Storefront using PowerShell or JavaScript for more info.

Stan Czerno – Powershell Script to launch one or more Published Applications from Citrix Storefront 2.x through 3.11: the script launches a browser, connects to StoreFront (or NetScaler Gateway), logs in, and launches an icon. This is a very well-written script that uses a .dll file from Citrix Workspace app to display session information.

Citrix Solutions Lab StoreFront Launcher Script at Github. It attempts to closely resemble what an actual user would do by:

  1. Opening Internet Explorer.
  2. Navigating directly to the Receiver for Web site or NetScaler Gateway portal.
  3. Completing the fields.
  4. Logging in.
  5. Clicking on the resource.
  6. Logging off the StoreFront site.

David Ott StoreFront App/Desktop Launch Testing Script uses Internet Explorer to login to StoreFront and launch a resource. Sends email with the result. Uses wficalib.dll to get session information.

Microsoft Teams

Citrix and Microsoft jointly support the delivery of Microsoft Teams from Citrix Virtual Apps and Desktops using optimization for Microsoft Teams. The Teams optimization components are built into VDA and Workspace app. There is no need to install anything separately. The feature is based on Browser Content Redirection so don’t exclude that feature when installing the VDA.

Microsoft Teams optimization/offloading requires the following:

  • Newest version of Microsoft Teams machine-wide installation (ALLUSER=1)
  • Newest version of Citrix VDA
  • Newest version of Citrix Workspace app.

Feature matrix and version support at Citrix Docs shows the required versions of Teams, Citrix VDA, and Citrix Workspace app for various Teams features.

See Citrix Docs Optimization for Microsoft Teams.

Skype for Business

Citrix has a HDX RealTime Optimization Pack for Workspace app that enables offloading of Skype for Business media protocols to the client device. Here are the available versions:

The HDX RealTime Optimization Pack comes in two pieces: the Connector (on the VDA), and the Media Engine (on the Workspace app machine). Usually both pieces must be the same version, but versions 2.3 and higher now allow version mixing.

24-page Citrix PDF Delivering Microsoft Skype for Business to XenApp and XenDesktop Users.

For Skype for Business Location Based Routing, you’ll need the following: (Source = Citrix Derek Thorslund at Location based routing at Citrix Discussions)

  • Microsoft added support for Location Based Routing (LBR) with the virtualized Skype for Business 2016 client (and HDX RTOP 2.1 and above) in the Click-to-Run (C2R) download quite a long time ago, but it hasn’t yet been introduced in the MSI package.
  • It requires setting IsLBRInVDIEnabled on the Skype for Business Server to True: 
    $x = New-CsClientPolicyEntry -Name "IsLBRInVDIEnabled" -Value "true"
Set-CsClientPolicy -Identity "<ClientPolicyName>” -PolicyEntry @{Add=$x}

When offloading voice and video to Workspace app machines, don’t forget to configure QoS on the client machines. See Citrix Blog Post Implementing the Citrix HDX RealTime Optimization Pack: Don’t Forget About QoS/DSCP.

Citrix CTX222459 RealTime Optimization Pack Capability Checker: It will list out endpoint hardware/software information which will be used to process audio and video. The tool is independent of RealTime Optimization Pack version and runs any Windows machine.

Citrix CTX214237 LOPper – Lync Optimization Pack Log Parser: parses log files generated by Citrix HDX RealTime Optimization Pack (HROP) when an audio/video call is made using Lync 2013/Skype for Business (SfB) and shows relevant information in a UI.

Troubleshooting – Citrix QuickLaunch

Citrix CTX219718 QuickLaunch Tool (Testing Application and Desktop Launch) lets you launch Citrix sessions directly from a Controller without needing StoreFront.

You enter a Controller address, credentials, and then it shows you the published resources. You can pick a resource, edit properties on the other tabs, and then Connect. This allows you to easily try different connection properties.

If you run into problems launching a session, use Sysinternals DebugView while running CQL in Debug mode (/debug switch).

Troubleshooting – Workspace app Logging

In Workspace app 2309 and newer, if you right-click the Workspace app icon in the system tray, there’s a Troubleshooting menu with a Collect Logs option.

You can also access Log Collection from Advanced Preferences.

There are a couple methods of logging Workspace app for Windows operations. One method is CTX141751 Citrix Receiver Diagnostics Tool – For Windows, which creates a CDF trace that can be parsed by CDFControl.

Another method is CTX132883 How to Enable Logging on Receiver for Windows Using Registry Entries. The logfiles in %USERPROFILE%\Appdata\Local\Citrix\ are human readable. And CTX206102 Enable SSON Logging Using Registry Key.

Instead of creating the registry keys manually, you can use the following .reg file provided by Wolfgang Thürr:

Windows Registry Editor Version 5.00

;only for x64 windows os
;import with admin rights
;restart your computer to activate the logging and tracing settings
;create C:\TEMP for the launch ICA log and SSON logn (no environment variables can be used)

;general Workspace app and Receiver logging
;************************
;logpath: %USERPROFILE%\Appdata\Local\Citrix\Receiver
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix]
"ReceiverVerboseTracingEnabled"=dword:00000001

;Authentication Manager logging
;******************************
;logpath: %USERPROFILE%\Appdata\Local\Citrix\AuthManager
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\AuthManager]
"LoggingMode"="verbose"
"TracingEnabled"="True"
"SDKTracingEnabled"="True"

;Self Service logging
;********************
;logpath: %USERPROFILE%\Appdata\Local\Citrix\SelfService
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\Dazzle]
"Tracing"="True"
"AuxTracing"="True"
"DefaultTracingConfiguration"="global all –detail"

;save launch ICA
;***************
;logpath: C:\TEMP\ica.log (no environemnt variables allowed)
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\ICA Client\Engine\Configuration\Advanced\Modules\Logging]
"LogConfigurationAccess"="true"
"LogConnectionAuthorisation"="true"
"LogEvidence"="true"
"LogICAFile"="true"
"LogFile"="C:\\TEMP\\ica.log"
"LogStartup"="true"

;Receiver Always On Tracing
;**************************
;generates ETL Files for analyzing with CDFControl see CTX111961 for details
;can be configured or overruled by GPOs (icaclient.admx)
;path %USERPROFILE%\AppData\Local\Temp\CTXReceiverLogs
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Citrix\ICA Client\AoLog]
"EnableTracing"=dword:00000001

;Single Sign-on Logging
;**************************
;https://support.citrix.com/article/CTX206102
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\Install\SSON]
"DebugEnabled"="true"
"LogPath"="C:\\Temp"

Troubleshooting – Duplicate Stores

Stores are sometimes duplicated in Workspace app, especially if you are running Workspace app inside a VDA. (h/t Dan High)

StoreFront URLs can be defined in several places:

  1. In Studio, go to Configuration > StoreFront and delete all URLs configured here.
  2. Look in GPOs for Computer Configuration > Administrative Templates > Policies > Citrix Components > Citrix Workspace > StoreFront > NetScaler Gateway URL/StoreFront Accounts List. Remove any URLs configured here.
  3. In the client-side registry, at HKLM\Software\Wow6432Node\Citrix\Dazzle\Sites, you might see store addresses that were specified during a command line installation of Workspace app.
  4. When Citrix Workspace app switches between StoreFront servers in multiple datacenters, it’s possible for each datacenter to be treated as a separate Workspace app site. This can be prevented by doing the following. From Juan Zevallos at Citrix Discussions:
    1. Match the Base URL in all datacenters.
    2. Match the SRID in all datacenters – The SRID can be safely edited in the C:\inetpub\wwwroot\Citrix\Roaming\web.config. Make sure to propagate changes to other servers in the group.
    3. Match the Delivery Controller names under “Manage Delivery Controllers” – The XML brokers can be different, but the actual name of the Delivery Controller/Farm must be identical.

If you are running Workspace app on a VDA, once you’ve removed the configured URLs shown above, do the following to clean up the VDAs:

  1. On the VDA, HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Citrix – Delete the number folders representing policy entries.
  2. On session host VDAs, HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\Terminal Server\Install\Software\Citrix – Remove the entries for storefront in the following folders.
    1. Under \receiver\ctxaccount delete all entries.
    2. Under \SR\Store delete the entries.
  3. On the VDA, C:\ProgramData\CitrixCseCache – Delete all files
  4. On the VDA, C:\ProgramData\Citrix\GroupPolicy – Delete all folders and files.
  5. Run gpupdate and logoff.
  6. In the user’s registry, HKEY_CURRENT_USER or the profile registry hive. Possible profile reset.
    1. Under Software\Citrix\Dazzle\Sites – Delete all entries.
    2. Under Software\Citrix\Receiver\ctxaccount – delete all entries.
    3. Under Software\Citrix\SR\Store – delete the entries.
  7. Verify no cached profile folders for user on server.