Category: NetScaler Gateway 11.1

nFactor Authentication for NetScaler Gateway 11.1

Last Modified: Sep 2, 2018 @ 7:54 am

43 Comments

Navigation

💡 = Recently Updated

Change Log

Overview

nFactor lets you configure an unlimited number of authentication factors. You are no longer limited to just two factors. Each authentication factor performs the following tasks:

  • nFactor requests credentials from the user. These credentials can be anything supported by NetScaler including:
    • SAML
    • Certificate
    • oAuth
    • Kerberos
    • Forms-based authentication (traditional web-based logon page) for LDAP, RADIUS, etc.
      • Multiple passwords can be collected with one form.
      • Or prompt the user multiple times throughout the authentication chain.
      • The logon page can contain a domain drop-down.
  • nFactor evaluates the credentials. The results can be:
    • Authentication success
    • Authentication failure
    • Group extraction
    • Attribute extraction from SAML, Certificate, etc.
  • Based on the evaluation results, do one of the following:
    • Allow access
    • Use authentication evaluation results to select next factor
    • Deny access
  • Multiple factor evaluations can be chained together. The chosen next factor is based on the results of the prior factor. This can continue indefinitely. The next factor can do one of the following:
    • Prompt the user for more credentials
    • Evaluate the already entered next set of credentials
    • Use policy expression to select another next factor (no authentication). This is typically used with group extraction so that groups determine the next factor.
  • NetScaler Gateway can perform Endpoint Analysis (EPA) and use the scan results to select nFactor authentication factors.

Here are some nFactor use cases, but the combinations are almost limitless:

  • Authentication method based on Active Directory group: Logon screen asks for user name only. Extract user’s groups from Active Directory. Based on user’s Active Directory groups, either ask user for certificate, or ask user for LDAP password. If LDAP, the username doesn’t need to be entered again.
  • Ask for Certificate first:
    • If certificate, perform LDAP only.
    • If no certificate, perform LDAP + RADIUS
  • Two-factor with passwords checked in specific order: Logon screen with two password fields. Check the first password. If the first password succeeds, then check the second password. This lets you check RADIUS before LDAP.
  • Run Endpoint Analysis first:
    • If passes, perform LDAP only.
    • If fails, perform LDAP + RADIUS

You configure nFactor in the AAA feature, and then bind it to NetScaler Gateway Virtual Servers. Because of AAA, NetScaler Enterprise Edition is required.

  • Note: nFactor works with browser clients, but it does not work with Receiver Self-Service (native Receiver).

nFactor configuration summary (detailed instructions below):

  • Each factor is a combination of Advanced Authentication Policies and Login Schema.
    • Advanced policy means it uses an Advanced (Default Syntax) expression as opposed to the classic syntax expression traditionally used in NetScaler Gateway authentication policies.
    • Login Schema is a custom HTML form where users enter credentials.
  • The first factor (Advanced Authentication Policies and Login Schema) is bound directly to a AAA Virtual Server.
  • Next factors are bound to Authentication Policy Labels. These Labels are then chained to Advanced Authentication Policies in prior factors.
  • Authentication Profile links AAA nFactor with NetScaler Gateway.

Also see Citrix CTX222713 Concepts, Entities and Terms used for nFactor Authentication through NetScaler.  💡

AAA Virtual Server

Create AAA Virtual Server

To use nFactor with NetScaler Gateway, you first configure it on a AAA Virtual Server. Then you later bind the AAA Virtual Server to the NetScaler Gateway Virtual Server.

  1. If AAA feature is not already enabled, go to Security > AAA, right-click AAA, and Enable Feature.
  2. Go to Security > AAA > Virtual Servers.
  3. On the right, click Add.
  4. Give the Virtual Server a name.
  5. If you are only using this AAA Virtual Server for NetScaler Gateway, then you can change the IP address Type to Non Addressable. It’s also possible to content switch to AAA.
  6. Click OK.
  7. In the Certificates section, click where it says No Server Certificate.
  8. Click to select.
  9. Select a certificate for the AAA Virtual Server, and click Select. Since this AAA Virtual Server is not directly addressable, the chosen certificate doesn’t matter.
  10. Click Bind.
  11. Click Continue.
  12. You probably don’t have any Advanced Authentication Policies yet, so just click Continue.

AAA Portal Theme

If this AAA Virtual Server is used not just for NetScaler Gateway, but also for traffic management (Load Balancing, Content Switching), then you might want to change the AAA Portal theme.

  1. Go to NetScaler Gateway > Portal Themes and add a theme.
  2. After adjusting it as desired, at the top of the portal theme editing page, Click to Bind and View Configured Theme.
  3. Change the selection to Authentication.
  4. Use the Authentication Virtual Server Name drop-down to select the AAA Virtual Server, and click Bind and Preview.

Client Certificate Authentication

If one of your authentication Factors is certificate, then you must perform some SSL configuration on the AAA Virtual Server:

  1. Go to Traffic Management > SSL > Certificates > CA Certificates, and install the root certificate for the issuer of the client certificates. Root certificates do not have a key file.
  2. Go to Security > AAA > Virtual Servers, and edit an existing AAA Virtual Server.
  3. On the left, in the SSL Parameters section, click the pencil icon.
  4. If you don’t see this section, then Default SSL Profiles are probably enabled. You’ll need to create a custom SSL Profile at System > Profiles > SSL Profile. Unfortunately, it’s not possible to bind the custom SSL Profile to AAA vServer using the GUI, but you can do it using the CLI (set ssl vserver MyAAAvServerName -sslProfile MySSLProfileName)
  5. Check the box next to Client Authentication.
  6. Make sure Client Certificate drop-down is set to Optional, and click OK.
  7. On the left, in the Certificates section, click where it says No CA Certificate.
  8. Click to select.
  9. Select the root certificate for the issuer of the client certificates, and click Select.
  10. Click Bind.

Login Schema

Login Schema XML File

Login Schema is an XML file providing the structure of forms-based authentication logon pages.

nFactor implies multiple authentication Factors that are chained together. Each Factor can have different Login Schema pages/files. In some authentication scenarios, users could be presented with multiple logon screens.

Or you can have one Factor gather information that can be passed on to later Factors, so that the later Factors don’t need to display another Login Schema. This is particularly useful for traditional two-password logon screens (LDAP + RADIUS), since each password is evaluated in a separate Factor:

  • The first password is evaluated in the first factor (e.g. LDAP). If successful, then proceed to the second factor.
  • The second factor (e.g. RADIUS) evaluates the second password. However, the second password has already been entered, so there’s no need to ask the user for it again. To prevent a Login Schema from being shown to the user, select noschema (LSCHEMA_INT) in the Authentication Policy Label.

Several Login Schema .xml files are included with NetScaler under /nsconfig/loginschema/LoginSchema.

NetScaler 11.1 lets you edit the labels from within the GUI. When the labels are changed, NetScaler copies the Login Schema to a new .xml file.

Or you can use WinSCP to connect to the appliance, duplicate one of the existing .xml files, and edit it as desired. For example, you can configure fields (InitialValue tag) to pre-fill information from previous Factors, as shown below:

The login schema can also contain a domain drop-down. See CTX201760 nFactor – Domain Drop-Down in First Factor then Different Policy Evaluations Based on Groups for a sample configuration.

CTX219545 Custom Login Labels in NetScaler nFactor Authentication: add a Requirement element with a Label sub-element to the Login Schema .xml file. Then use Javascript to populate the label with any desired HTML. For example:

Login Schema Profile

To configure a Login Schema Profile:

  1. Create or Edit a Login Schema .XML file based on your nFactor design.
  2. Go to Security > AAA > Login Schema.
  3. On the right, switch to the Profiles tab, and click Add.
  4. In the Authentication Schema field, click the pencil icon.
  5. Click the LoginSchema folder to see the files in it.
  6. Select one of the files. You can see a preview on the right. The labels can be changed by clicking the Edit button on the top right.
  7. When you Save the changes, a new file is created under /nsconfig/LoginSchema.
  8. On the top right, click Select.
  9. Give the Login Schema a name, and click More.
  10. You typically need to use the entered credentials elsewhere. For example, you might need to use the username and one of the passwords to later Single Sign-on to StoreFront. Near the bottom of the Login Schema Profile, enter unique values for the indexes. These values can be between 1 and 16.
  11. You can also configure these values on your noschema profiles so that passwords received from a previous factor can be put into a different Index.
  12. Later you reference these index values in a Traffic Policy/Profile by using the expression HTTP.REQ.USER.ATTRIBUTE(#).
  13. Click Create.
  14. Note: if you later edit the Login Schema .xml file, the changes might not be reflected until you edit the Login Schema Profile and select the .xml file again

Login Schema Policy

Login Schemas can be bound directly to a AAA Virtual Server. If one of the Advanced Authentication policies bound directly to the AAA Virtual Server is forms-based, then bind the Login Schema directly to the AAA Virtual Server. If you are binding the Login Schema directly to a AAA Virtual Server, then you must first create a Login Schema Policy expression that is linked to the Login Schema Profile.

Or Login Schemas can be bound to an Authentication Policy Label (described later). If you are binding a Login Schema to an Authentication Policy Label, then there’s no need to create a Login Schema policy expression.

To create and bind a Login Schema Policy:

  1. On the left, go to Security > AAA > Login Schema.
  2. On the right, switch to the Policies tab, and click Add.
  3. Use the Profile drop-down to select the Login Schema Profile you already created.
  4. Enter a Default Syntax expression in the Rule box, and click Create.
  5. On the left, go to Security > AAA > Virtual Servers, and edit an existing AAA Virtual Server.
  6. On the right, in the Advanced Settings column, click Login Schemas.
  7. On the left, in the Login Schemas section, click where it says No Login Schemas.
  8. Click to select.
  9. Select the Login Schema policy, and click Select. Only Login Schema Policies appear in this list. Login Schema Profiles (without a policy) do not appear.
  10. Click Bind.

Advanced Authentication Policies

Authentication policies are a combination of policy expression and policy action. If the expression is true, then evaluate the action.

The Action is always an authentication server (LDAP, RADIUS, etc.).

The policy expression can be either in classic syntax, or in the newer default syntax.

The policy type is either Basic or Advanced. Basic policies can only use classic syntax. Advanced policies only use the newer default syntax. Both types of policies use the same Actions (authentication servers).

nFactor requires Advanced Authentication Policies; Basic policies won’t work.

Create Advanced Authentication Policy

You will need Authentication Actions/Servers (e.g. LDAP, RADIUS, CERT, SAML, etc.)

When creating an Advanced Authentication Policy, there’s a plus icon that lets you create Authentication Actions/Servers.

Or you can create Authentication Actions prior to creating the Advanced Authentication Policy. The Authentication Actions are located under the Security > AAA > Policies > Basic Policies > <Action Type> node. On the right, switch to the Servers tab to create the Actions/Servers. Once the Actions are created, use the instructions below to create the Advanced Authentication Policy. There’s no need to create a Basic Authentication Policy.

To create an Advanced Authentication Policy:

  1. Go to Security > AAA > Authentication > Advanced Policies > Policy.
  2. On the right, click Add. You typically create at least one Authentication Policy for each Factor. When you create multiple Authentication Policies for one Factor, NetScaler checks each policy in priority order until one of them succeeds.
  3. Use the Action Type drop-down to select the Action Type (e.g. LDAP). The Action Type depends on your nFactor flow design.
  4. If you don’t currently have any Actions configured, of if you want to create a new one, click the plus icon next to the Action drop-down. The Actions/Servers are created in the normal fashion.
  5. In the Expression box, enter an expression using the Default Syntax. ns_true won’t work because that’s Classic syntax. There’s an Expression Editor link on the right. Or hit Ctrl+Space to see your options. true is a valid Default expression. Click Create when done.
  6. Create more Advanced Authentication Policies as needed for your nFactor design.

Bind Advanced Authentication Policy to AAA

Only the Advanced Authentication Policies for the first Factor are bound directly to the AAA Virtual Server. The Advanced Authentication Policies for the remaining Factors are bound to Authentication Policy Labels as detailed in the next section.

  1. Go to Security > AAA > Virtual Servers.
  2. Edit an existing AAA Virtual Server.
  3. On the left, in the Advanced Authentication Policies section, click where it says No Authentication Policy.
  4. Click to select.
  5. Select the Advanced Authentication Policy, and click Select.
  6. The Select Next Factor field can optionally point to an Authentication Policy Label as detailed in the next section. The Next Factor is only evaluated if this Advanced Authentication Policy succeeds.
  7. If this Advanced Authentication Policy fails, then the Goto Expression determines what happens next. If it is set to NEXT, then the next Advanced Authentication Policy bound to this Factor is evaluated. If it is set to END, of if there are no more Advanced Authentication Policies bound to this Factor, then authentication is finished and marked as failed.
  8. Click Bind.

LDAP Group Extraction

Sometimes you only want to extract a user’s groups from Active Directory, but have don’t actually want to authenticate with LDAP. These groups can then be used to select the next authentication Factor.

To configure an LDAP Action/Server for only group extraction:

  1. When creating or editing an LDAP Server, make sure Authentication is unchecked.
  2. Make sure Group Attribute and Sub Attribute Name are filled in.

Authentication Policy Label

When configuring the first Factor, you bind two objects to the AAA Virtual Server:

  • Login schema – for forms-based authentication
  • Advanced Authentication Policy

When binding the Advanced Authentication Policy to the AAA Virtual Server, there’s a field to Select Next Factor. If the Advanced Authentication Policy succeeds, then the Next Factor is evaluated.

The Next Factor is actually an Authentication Policy Label.

Authentication Policy Labels contain three objects:

  • Login Schema
  • Advanced Authentication Policies
  • Next Factor – the next Authentication Policy Label

Here’s the flow:

  1. User connects to AAA or NetScaler Gateway Virtual Server.
  2. If forms-based authentication, the Login Schema bound to the AAA Virtual Server is displayed.
  3. Advanced Authentication Policies bound to the AAA Virtual Server are evaluated.
    1. If the Advanced Authentication Policy is successful, go to the configured Next Factor, which is an Authentication Policy Label.
      1. If Next Factor is not configured, then authentication is complete and successful.
    2. If the Advanced Authentication Policy fails, and if Goto Expression is Next, then evaluate the next bound Advanced Authentication Policy.
    3. If none of the Advanced Authentication Policies are successful, then authentication failed.
  4. If the Next Factor Authentication Policy Label has a Login Schema bound to it, display it to the user.
  5. Evaluate the Advanced Authentication Policies bound to the Next Factor Authentication Policy Label.
    1. If the Advanced Authentication Policy is successful, go to the configured Next Factor, which is an Authentication Policy Label.
      1. If Next Factor is not configured, then authentication is complete and successful.
    2. If the Advanced Authentication Policy fails, and if Goto Expression is Next, then evaluate the next bound Advanced Authentication Policy.
    3. If none of the Advanced Authentication Policies are successful, then authentication failed.
  6. Continue evaluating the Next Factor Authentication Policy Label until authentication succeeds or fails. You can chain together an unlimited number of Authentication Policy Labels.

If you are binding a Login Schema to an Authentication Policy Label, then you only need the Login Schema Profile. There’s no need to create a Login Schema Policy.

Not every Factor needs a Login Schema (logon page). It’s possible for a prior Factor to gather all of the credential information and simply pass it on to the next Factor. If you don’t need a Login Schema for a particular Authentication Policy Label, simply select LSCHEMA_INT, which is mapped to noschema. Or create a new Login Schema Profile based on noschema.

Create Authentication Policy Label

To create an Authentication Policy Label:

  1. Authentication Policy Labels are configured at Security > AAA > Policies > Authentication > Advanced Policies > PolicyLabel.
  2. On the right, click Add.
  3. Give the Policy Label a name.
  4. Select a Login Schema Profile. This can be one that is set to noschema if you don’t actually want to display anything to the user. Then click Continue.
  5. In the Policy Binding section, Click to select.
  6. Select an Advanced Authentication Policy that evaluates this Factor. Click Select.
  7. Use the Goto Expression drop-down to select NEXT or END. If you want to bind more Advanced Authentication Policies to this Factor, then select NEXT.
  8. In the Select Next Factor field, if you chain another Factor, Click to select, and bind the next Authentication Policy Label (Next Factor).
  9. Or don’t select anything, and if this Advanced Authentication Policy succeeds, then authentication is successful and complete. This ends the chaining.
  10. Click Bind when done.
  11. You can click Add Binding to add more Advanced Authentication Policies to this Policy Label (Factor). Or you can bind Advanced Authentication Policies to the next Policy Label (Next Factor). Click Done.

Bind Authentication Policy Label

Once the Policy Label (Factor) is created, you bind it to an existing Advanced Authentication Policy binding. This is how you chain Factors together.

  1. Either edit an existing AAA Virtual Server that has an Advanced Authentication Policy already bound to it.
  2. Or edit a different Authentication Policy Label.
  3. On the left, in the Advanced Authentication Policies section, click the bindings.
  4. Click the ellipsis next to an existing binding, and click Edit Binding.
  5. In the Select Next Factor field, Click to select.
  6. Select the Policy Label for the Next Factor, and click Select.
  7. Click Bind.
  8. Click Close.

nFactor for NetScaler Gateway

AAA Authentication Profile

Authentication Profile lets you bind a AAA Virtual Server to NetScaler Gateway. This is what enables nFactor on NetScaler Gateway.

  1. Go to NetScaler Gateway > Virtual Servers.
  2. On the right, edit an existing Gateway Virtual Server.
  3. Note: the new RfWebUI theme seems to interfere with Login Schema rendering. Consider changing your Gateway Portal Theme to X1 instead.
  4. On the right, in the Advanced Settings section, click Authentication Profile.
  5. On the left, click the plus icon next to the Authentication Profile drop-down.
  6. Give the Authentication Profile a name.
  7. In the Authentication Virtual Server field, Click to select.
  8. Select the AAA Virtual Server that has Login Schema, Advanced Authentication Policy, and Authentication Policy Labels configured. The AAA Virtual Server does not need an IP address. Click Select.
  9. Then click Create.
  10. And click OK.
  11. If one of your Factors is client certificates, then you’ll need to configure SSL Parameters and CA certificate as detailed in the next section.
  12. When you browse to your Gateway, you’ll see the nFactor authentication screens.

Unified Gateway

If you have Unified Gateway (Content Switch in front of NetScaler Gateway), then edit the Content Switching policy and add the following expression:

|| HTTP.REQ.URL.STARTSWITH("/nf")

Gateway Client Certificate Authentication

If one of your authentication Factors is certificate, then you must perform some SSL configuration on the NetScaler Gateway Virtual Server:

  1. Go to Traffic Management > SSL > Certificates > CA Certificates, and install the root certificate for the issuer of the client certificates. Certificate Authority certificates do not need key files.
  2. Go to NetScaler Gateway > Virtual Servers, and edit an existing NetScaler Gateway Virtual Server that is enabled for nFactor.
  3. On the left, in the SSL Parameters section, click the pencil icon.
  4. Check the box next to Client Authentication.
  5. Make sure Client Certificate drop-down is set to Optional, and click OK.
  6. On the left, in the Certificates section, click where it says No CA Certificate.
  7. Click to select.
  8. Select the root certificate for the issuer of the client certificates, and click Select.
  9. Click Bind.

nFactor Single Sign-on to StoreFront

When performing Single Sign-on to StoreFront, nFactor defaults to using the last entered password. If LDAP is not the last entered password, then you need to create a Traffic Policy/Profile to override the default nFactor behavior.

  1. Go to NetScaler Gateway > Policies > Traffic.
  2. On the right, switch to the Traffic Profiles tab.
  3. Click Add.
  4. Give the Traffic Profile a name.
  5. In the Protocol section, select HTTP.
  6. Enable Single Sign-on. Scroll down.
  7. In the SSO Expression fields, enter an HTTP.REQ.USER.ATTRIBUTE(#) expression that matches the indexes specified in the Login Schema.
  8. Click Create.
  9. On the right, switch to the Traffic Policies tab, and click Add.
  10. Give the policy a name.
  11. Select the previously created Traffic Profile.
  12. Enter a classic expression (e.g. ns_true) and click Create.
  13. Edit an existing NetScaler Gateway Virtual Server.
  14. Scroll down to the Policies section and click the plus icon.
  15. Select Traffic > Request, and click Continue.
  16. Select the previously created Traffic Policy and click Bind.

Endpoint Analysis and nFactor

When combining nFactor with NetScaler Gateway (or Universal Gateway), you can use Endpoint Analysis scans to control nFactor flow.

  1. Create a Preauthentication Profile (NetScaler Gateway > Policies > Preauthentication > Preauthentication Profiles).
  2. In the Default EPA Group field, enter a new group name. If the EPA scan succeeds, users are added to this group. This group name can then be used later in policy expressions (e.g. HTTP.REQ.USER.IS_MEMBER_OF(“Corporate”))
  3. Switch to the Preauthentication Policies tab and add a policy.
  4. Give the policy a name and select the Preauthentication Profile.
  5. Configure the EPA expression by using the OPSWAT EPA Editor or Expression Editor links on the right. More details at https://www.carlstalhood.com/smartaccess-smartcontrol-netscaler-11-1/#epa.
  6. You can create a Preauthentication Policy with expression ns_true to capture all failed EPA scans. The Preauthentication Profile would place users in EPA group that indicates the scans failed.
  7. Edit your Gateway vServer, scroll to the Policies section, and click the plus icon to bind the Preauthentication policies.

  8. If you have a catchall (ns_true) Preauthentication Policy, make sure it has the highest priority number so it is evaluated last.
  9. In your 1st factor AAA Advanced Authentication Policies, use expressions similar to HTTP.REQ.USER.IS_MEMBER_OF(“MyEPAGroup”). The group name should match whatever group name you specified in the Preauthentication Profile.
  10. For the 1st factor, bind the Advanced Authentication Policies directly to the AAA vServer. Configure the Next Factor based on your nFactor design (e.g. Next Factor = RADIUS if EPA fails).
  11. In your Login Schema Policies (1st factor), use the same type of expression.
  12. For the 1st factor, bind the Login Schema Policies directly to the AAA vServer.
  13. See below for a sample EPA / nFactor configuration.

Note: if the user skips the EPA scan, then this message will be displayed. This appears to be a limitation of EPA with nFactor.

Sample Configurations

From Citrix Docs: Sample deployments using nFactor authentication:

  • Get two passwords up-front, pass-through in next factor. Read
  • Username and 2 passwords with group extraction in third factor. Read
  • Configure nFactor to process the second password before the first password, Read
  • Modify first factor username for second factor. Read
    • NO_AUTHN authentication policy expression checks first factor POST Body login value for UPN format. If true, Next Factor is noschema Login Schema with User Expression that transforms the HTTP.REQ.USER.NAME to DOMAIN\Username before passing to second factor authentication policy.
  • Group extraction followed by certificate or LDAP authentication, based on group membership. Read

  • SAML followed by LDAP or certificate authentication, based on attributes extracted during SAML. Read
  • SAML in first factor, followed by group extraction, and then LDAP or certificate authentication, based on groups extracted. Read
  • Capture email address in first factor, and then choose one of multiple SAML iDP based on email address suffix. Read (Manuel Kolloff)

  • Prefill user name from certificate. Read
  • Certificate authentication followed by group extraction for 401 enabled traffic management virtual servers. Read
  • Certificate fallback to LDAP in same cascade; one virtual server for both certificate and LDAP authentication. Read
  • LDAP in first factor and WebAuth in second factor. Read
  • WebAuth in first factor, LDAP in second factor. Read
  • Domain drop down in first factor, then different policy evaluations based on group. Read
  • Google reCAPTCHA first factor, LDAP second. Read (George Spiers)
  • Supporting reCaptcha with NetScaler nFactor. Read
  • CTX225938 nFactor – Customizing UI to Display Images – e.g. Swivel
  • Configure EULA (End User License Agreement) as an Authentication Factor. Read
  • Show a drop-down box in the logon form and automatically hide or show certain fields based on drop-down selection. Read

  • Step-up authentication – i.e. one Unified Gateway website needs single factor, while other website needs multi-factor. Read

Certificate auth: If Successful, LDAP only. If Failure, LDAP+RADIUS

This scenario is described in Citrix Blog Post Configuration Notes on nFactor

The authentication process flows like this:

  1. User connects to NetScaler Gateway.
  2. NetScaler Gateway asks user for certificate.
  3. If user selects a certificate, NetScaler Gateway compares certificate signature to the CA certificate that is bound to the NetScaler Gateway. If it doesn’t match, then user certificate is ignored.
  4. Bound to the NetScaler Gateway Virtual Server is an Authentication Profile, which links NetScaler Gateway to AAA nFactor.
  5. Certificate authentication: The lowest priority number authentication policy on the AAA Virtual Server is Certificate. If there’s a valid user certificate:
    1. Extract the user’s userPrincipalName from the certificate.
    2. Next Factor = policy label that displays a logon screen (Single-factor Login Schema)
    3. The username field is pre-populated with the userPrincipalName attribute extracted from the certificate.
    4. User is prompted to enter the LDAP password only.
    5. LDAP policy/server is configured to use userPrincipalName to login to LDAP.
    6. If successful, NetScaler Gateway authentication is complete. Next step is to Single Sign-on to StoreFront.
    7. If LDAP authentication fails, then NetScaler Gateway authentication fails, and the user is prompted to try LDAP-only authentication again.
  6. LDAP authentication: If certificate authentication fails, try next authentication policy bound to the AAA Virtual Server, which is a different LDAP Policy.
    1. Bound to the AAA Virtual Server is a Dual Factor Login Schema that asks for username, LDAP password, and RADIUS password.
    2. LDAP policy/server is configured to use sAMAccountName to login to LDAP. SAMAccountName means users don’t have to enter full userPrincipalName.
    3. If LDAP authentication is successful:
      1. Put username in Credential Index 1 and put password in Credential Index 2. These will later be used by a Traffic Policy to Single Sign-on to StoreFront.
      2. Proceed to next factor (Policy Label), which is RADIUS.
    4. If LDAP authentication fails, NetScaler Gateway login fails, and the user is prompted to try two-factor authentication again.
  7. RADIUS authentication: the second factor Policy Label is configured with Noschema. This means no additional logon form is displayed because the RADIUS password was already collected in the previous factor.
    1. When multiple passwords are collected, they are tried in order. The first password was used by the previous factor. The second password is tried by this factor (Policy Label).
    2. RADIUS policy/profile attempts authentication.
    3. If RADIUS authentication is successful, NetScaler Gateway authentication is complete. Next step is Single Sign-on to StoreFront.
    4. If RADIUS authentication fails, NetScaler Gateway login fails, and the user is prompted to try two-factor authentication again.
  8. Single Sign-on to StoreFront: NetScaler Gateway uses the last password collected by nFactor to Single Sign-on with StoreFront. If the last password is LDAP, then no additional configuration is needed. If the last password is not LDAP, then a Traffic Policy/Profile is needed.
    1. Bound to the NetScaler Gateway Virtual Server is a Traffic Policy.
    2. The Traffic Policy/Profile users Credential Index 1 for username and Credential Index 2 for Password. These are the same indexes configured in the Dual Factor Login Schema.

The order of configuration doesn’t match the authentication flow because some objects have to be created before others.

# Create Auth vServer, bind server cert, bind CA cert for client certificates
# Enable Optional client certificates
add authentication vserver nFactorAAA SSL 0.0.0.0 443
bind ssl vserver nFactorAAA -certkeyName WildCorpCom
bind ssl vserver nFactorAAA -certkeyName CorpRoot -CA -ocspCheck Optional
set ssl vserver nFactorAAA -clientAuth ENABLED -clientCert Optional -ssl3 DISABLED

# Create auth policy for LDAP-UPN. UPN is extracted from certificate.
add authentication ldapAction Corp-UserPrincipalName -serverIP 10.2.2.220 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn "corp\\ctxsvc" -ldapBindDnPassword "MyPassword" -ldapLoginName userPrincipalName -groupAttrName memberOf -subAttributeName CN -secType SSL -passwdChange ENABLED
add authentication Policy Corp-UserPrincipalName -rule true -action Corp-UserPrincipalName

# Create PolicyLabel LDAPPasswordOnly with Single-factor Login Schema
# Login Schema has InitialValue with username from certificate.
add authentication loginSchema SingleAuth -authenticationSchema "/nsconfig/loginschema/LoginSchema/SingleAuth-Corp.xml"
add authentication policylabel LDAPPasswordOnly -loginSchema SingleAuth
bind authentication policylabel LDAPPasswordOnly -policyName Corp-UserPrincipalName -priority 100 -gotoPriorityExpression NEXT

# Create Cert policy and bind to AAA vServer with LDAPPasswordOnly PolicyLabel as Next Factor
# Cert policy must have lower priority number (higher priority) than LDAP-SAM policy
# Cert is evaluated first. If succeed, ask for LDAP password. If fails, ask for two factor.
add authentication certAction Cert_Auth_Profile -userNameField SubjectAltName:PrincipalName
add authentication Policy Cert_Auth_Policy -rule true -action Cert_Auth_Profile
bind authentication vserver nFactorAAA -policy Cert_Auth_Policy -priority 100 -nextFactor LDAPPasswordOnly -gotoPriorityExpression NEXT

# Create LDAP-SAM Auth Policy for two-factor
# Only evaluated if cert auth fails. Login Schema asks for user, password, and passcode.
add authentication ldapAction Corp-Gateway -serverIP 10.2.2.220 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn "corp\\ctxsvc" -ldapBindDnPassword "MyPassword" -ldapLoginName samaccountname -groupAttrName memberOf -subAttributeName CN -secType SSL -passwdChange ENABLED
add authentication Policy Corp-SAMAccountName -rule true -action Corp-Gateway

# Create RADIUS Auth Policy for two-factor
add authentication radiusAction RADIUS-Action -serverIP 10.2.2.42 -serverPort 1812 -radKey MyKey
add authentication Policy RADIUS-Policy -rule true -action RADIUS-Action

# Create Dual-factor Login Schema and bind directly to AAA vServer
# This Login Schema is only shown if Cert auth fails
add authentication loginSchema DualAuth -authenticationSchema "/nsconfig/loginschema/LoginSchema/DualAuth.xml" -userCredentialIndex 1 -passwordCredentialIndex 2
add authentication loginSchemaPolicy DualAuth -rule true -action DualAuth
bind authentication vserver nFactorAAA -policy DualAuth -priority 100 -gotoPriorityExpression END

# Create RADIUS Policy Label with noschema and RADIUS Auth Policy
# Already got passcode from previous factor so don't show Login Schema again
add authentication loginSchema Noschema -authenticationSchema noschema
add authentication policylabel NoSchema-RADIUS -loginSchema Noschema
bind authentication policylabel NoSchema-RADIUS -policyName RADIUS-Policy -priority 100 -gotoPriorityExpression NEXT

# Bind LDAP-SAM Auth Policy to AAA vServer with RADIUS as next factor
# LDAP-SAM Auth Policy must have higher priority number (lower priority) than Cert Policy
bind authentication vserver nFactorAAA -policy Corp-SAMAccountName -priority 110 -nextFactor NoSchema-RADIUS -gotoPriorityExpression NEXT

# Create Authentication Profile to link AAA with Gateway. Bind to Gateway.
add authentication authnProfile nFactor -authnVsName nFactorAAA -AuthenticationHost aaa.corp.com
add vpn vserver gateway.corp.com SSL 10.2.2.220 443 -icaOnly ON -dtls ON -Listenpolicy NONE -tcpProfileName nstcp_default_XA_XD_profile -appflowLog ENABLED -authnProfile nFactor

# Enable Optional Client certs on Gateway
set ssl vserver gateway.corp.com -clientAuth ENABLED -clientCert Optional -ssl3 DISABLED
bind ssl vserver gateway.corp.com -certkeyName CorpRoot -CA -ocspCheck Optional

# Create Traffic Policy to SSON to StoreFront. Bind to Gateway.
add vpn trafficAction nFactorSSO http -kcdAccount NONE -userExpression "http.req.user.attribute(1)" -passwdExpression "http.req.user.attribute(2)"
add vpn trafficPolicy nFactorSSO ns_true nFactorSSO
bind vpn vserver gateway.corp.com -policy nFactorSSO -priority 100

Enpoint Analysis Scan: If succeed, LDAP only. If fails, LDAP+RADIUS.

The authentication process flows like this:

  1. User connects to NetScaler Gateway.
  2. The Gateway has Preauthentication Policies, which causes Endpoint Analysis scan to occur.
  3. Preauthentication Profiles put users in different AAA Groups depending on results of the scan.
  4. The Login Schema Policies bound to the AAA vServer have user group expressions based on the Preauthentication Profile EPA Groups.
    1. If scan passed (Corporate group), show Login Schema with one password only.
    2. If scan failed (NonCorporate group), show Login Schema with two password fields.
  5. The Advanced Authentication Policies bound to the AAA vServer have user group expressions based on the Preauthentication Profile EPA Groups.
    1. If scan passed (Corporate group), evaluate LDAP password only. No Next Factor.
    2. If scan failed (NonCorporate group), evaluate LDAP, then Next Factor to RADIUS Policy Label.

Here’s a sample config:

# Two Login Schema Profiles - one with one password only, one with two passwords
add authentication loginSchema TwoFactor -authenticationSchema "/nsconfig/loginschema/DualAuth_new.xml" -userCredentialIndex 1 -passwordCredentialIndex 2
add authentication loginSchema LDAPOnly -authenticationSchema "/nsconfig/loginschema/LoginSchema/SingleAuth.xml"
# Login Schema Policies based on EPA Groups
add authentication loginSchemaPolicy NonCorporateSchema -rule "http.REQ.USER.IS_MEMBER_OF(\"NonCorporate\")" -action TwoFactor
add authentication loginSchemaPolicy CorporateSchema -rule "http.REQ.USER.IS_MEMBER_OF(\"Corporate\")" -action LDAPOnly

# LDAP Action
add authentication ldapAction LDAP-Corp -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn ctxsvc@corp.local -ldapBindDnPassword "MyPassword" -ldapLoginName sAMAccountName -groupAttrName memberOf -subAttributeName cn -secType SSL -passwdChange ENABLED -nestedGroupExtraction ON -groupNameIdentifier sAMAccountName -groupSearchAttribute memberOf -groupSearchSubAttribute CN
# Two LDAP Policies based on EPA Groups. Same Action for each.
add authentication Policy NonCorporateLDAP -rule "http.REQ.USER.IS_MEMBER_OF(\"NonCorporate\")" -action LDAP-Corp
add authentication Policy CorporateLDAP -rule "http.REQ.USER.IS_MEMBER_OF(\"Corporate\")" -action LDAP-Corp

# RSA Action
add authentication radiusAction RSA -serverIP 10.2.2.42 -serverPort 1812 -radKey MyKey -accounting ON
add authentication Policy RSAAdv -rule true -action RSA
# RSA Policy Label for Next Factor
add authentication policylabel Non-Corporate-RADIUS -loginSchema LSCHEMA_INT
bind authentication policylabel Non-Corporate-RADIUS -policyName RSAAdv -priority 100 -gotoPriorityExpression NEXT

# AAA vServer
add authentication vserver aaanFactor SSL 0.0.0.0
# AAA vServer - bind Login Schema Policies
bind authentication vserver aaanFactor -policy CorporateSchema -priority 100 -gotoPriorityExpression END
bind authentication vserver aaanFactor -policy NonCorporateSchema -priority 110 -gotoPriorityExpression END
# AAA vServer - bind LDAP Auth Policies. Failed EPA has Next Factor configured.
bind authentication vserver aaanFactor -policy CorporateLDAP -priority 100 -gotoPriorityExpression NEXT
bind authentication vserver aaanFactor -policy NonCorporateLDAP -priority 110 -nextFactor Non-Corporate-RADIUS -gotoPriorityExpression NEXT

# Preauth Profiles have EPA Groups (AAA Groups) defined
add aaa preauthenticationaction Corporate ALLOW -defaultEPAGroup Corporate
add aaa preauthenticationaction NonCorporate ALLOW -defaultEPAGroup NonCorporate
# Preauth Policies use EPA Expressions. ns_true captures all failed EPA scans.
add aaa preauthenticationpolicy CorporateEPA "CLIENT.SYSTEM(\'DOMAIN_SUFFIX_anyof_corp.local[COMMENT: Domain check]\') EXISTS" Corporate
add aaa preauthenticationpolicy NonCorporate ns_true NonCorporate

# Authentication Profile
add authentication authnProfile nFactor-Gateway -authnVsName aaanFactor

# Gateway vServer - Create and bind Auth Profile
add vpn vserver UG_VPN_UG SSL 0.0.0.0 -dtls ON -loginOnce ON -Listenpolicy NONE -tcpProfileName nstcp_default_XA_XD_profile -appflowLog ENABLED -authnProfile nFactor-Gateway
# Gateway vServer - Bind Preauthentcation Policies
bind vpn vserver UG_VPN_UG -policy CorporateEPA -priority 100
bind vpn vserver UG_VPN_UG -policy NonCorporate -priority 110
# Gateway vServer - Bind Traffic Policy for SSON to StoreFront
bind vpn vserver UG_VPN_UG -policy nFactorSSO -priority 100
# Gateway vServer - remaining configuration is normal (session policies, STA, SSL cert, etc.)

SmartAccess / SmartControl – NetScaler 11.1

Last Modified: Nov 6, 2020 @ 7:30 am

24 Comments

Navigation

💡 = Recently Updated

SmartAccess / SmartControl

SmartAccess and SmartControl let you change ICA connection behavior (e.g. disable client device mappings) based on how users connect. Decisions are based on NetScaler Gateway Virtual Server name, Session Policy name, and Endpoint Analysis scan success or failure.

SmartAccess can also control application/desktop icon visibility.

Prerequisites

Both SmartAccess and SmartControl have the same prerequisites. You can configure SmartAccess in XenApp/XenDesktop at any time, but it won’t work, until you do the following:

  1. NetScaler appliance license – SmartAccess works with all editions of NetScaler appliances.  However, SmartControl only works with NetScaler Platinum Edition.
  2. On the NetScaler, go to System > Licenses and make sure you have NetScaler Gateway Universal Licenses allocated to the appliance.
    1. NetScaler 11.1 build 49 and later come with built-in Gateway Universal licenses: NetScaler Standard Edition = 500 licenses, NetScaler Enterprise Edition = 1000 licenses, and NetScaler Platinum Edition = unlimited licenses.
    2. The Universal licenses are allocated to the hostname of the appliance (click the gear icon), not the MAC address. In a High Availability pair, if each node has a different hostname, then you can allocate the licenses to one hostname, then reallocate to the other hostname.

  3. After installing licenses, go to NetScaler Gateway > Global Settings.
  4. On the top right, click Change authentication AAA settings.
  5. At the top of the page, change the Maximum Number of Users to match your installed license count. Then click OK. In NetScaler 11.1 build 49 and newer, this value should already match the number of licensed users. In older builds, you must manually configure this setting, and if not configured, then it defaults to only 5 concurrent connections.

  6. On a XenApp/XenDesktop Controller, run PowerShell as Administrator.
  7. Run asnp citrix.* to load the snapins.
  8. Run Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $true to enable Trust XML.
  9. In StoreFront Console, edit the existing Gateway object.
  10. Make sure a Callback URL is configured. The Callback URL must resolve to a NetScaler Gateway VIP on the same appliance that authenticated the user. The Callback Gateway’s certificate must match the FQDN entered here. If you are configuring Single FQDN for internal and external, then the Callback FQDN must be different than the Single FQDN.
  11. On the NetScaler, go to NetScaler Gateway > Virtual Servers, and edit your Gateway Virtual Server.

  12. In the Basic Settings section, click the pencil icon.
  13. Click More.
  14. Uncheck the box next to ICA Only, and click OK. This tells NetScaler Gateway to start using Universal licenses, and enables the SmartAccess and SmartControl features.

Once the prerequisites are in place, do the following as detailed below:

Endpoint Analysis

Endpoint Analysis scans are completely optional. You can configure SmartControl and SmartAccess without implementing any Endpoint Analysis.

Endpoint Analysis is supported on Windows and Mac devices. Other devices, like iOS and Android, do not support Endpoint Analysis. If you want to allow mobile device connectivity, then make sure you have an access mechanism (e.g. ICA Proxy) that works if the Endpoint Analysis scan fails.

There are two methods of Endpoint Analysis: pre-authentication and post-authentication. For pre-authentication, configure an Endpoint Analysis expression in a Preauthentication Policy. For post-authentication, configure the Endpoint Analysis expression on one or more Session Policies.

  • With a Preauthentication Policy, if the Endpoint Analysis scan fails, then users can’t login.
  • With a Postauthentication Policy, Endpoint Analysis doesn’t run until after the user logs in. Typically, you create multiple Session Policies. One or more Session Policies has Endpoint Analysis expressions. Leave one policy without an Endpoint Analysis expression so there’s a fallback in case the client device doesn’t support Endpoint Analysis (e.g. mobile devices). The name of the Session Policy is then used later in Citrix Policies and Citrix Delivery Groups.

NetScaler has two Endpoint Analysis engines: the classic Client Security engine, and the newer OPSWAT Advanced EPA engine.

To configure OPSWAT Advanced EPA expressions:

  1. When creating a Preauthentication Policy or Session Policy, click the OPSWAT EPA Editor link.
  2. Use the drop-down menus to select the scan criteria. Then click Done.

Additional EPA Info – See the following links for more Advanced EPA information:

To configure Client Security expressions:

  1. When creating a Preauthentication Policy or Session Policy, click the Expression Editor link.
  2. Change the Expression Type to Client Security.
  3. Use the Component drop-down to select a component. A common configuration is to check for domain membership as detailed at CTX128040 How to Configure a Registry-Based Scan Expression to Look for Domain Membership.

You can also use EPA expressions when configuring a Quarantine Group.

Once the Preauthentication and/or Session Policies are created, bind them to your NetScaler Gateway Virtual Server:

  1. Edit a NetScaler Gateway Virtual Server.
  2. Scroll down to the Policies section, and click the plus icon.
  3. Select either Preauthentication or Session, and select the policy you already created. Then click Bind.

EPA Troubleshooting

Citrix CTX209148 Understanding/Configuring EPA Verbose Logging Feature:

  1. Go to NetScaler Gateway > Global Settings.
  2. On the right, click Change Global Settings.
  3. On the Security tab, click Advanced Settings.
  4. Scroll down, check the box next to Enable Client Security Logging, and click OK.
  5. When the scan fails, the user is presented with a Case ID.
  6. You can then grep /var/log/ns.log for the Case ID. Or search your syslog.

 

To determine why your EPA scans fail, on the client machine, go to HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Secure Access Client.
Make a DWORD value named “EnableEPALogging“, and set the value to 1.

After attempting the scan again, you’ll find the file %localappdata%\Citrix\AGEE\epaHelper_epa_plugin.txt with details for each scan expression.

 

NetscalerAssasin EPA OPSWAT Packet flow and Troubleshooting shows a Wireshark trace of an EPA scan.

SmartControl

The SmartControl feature lets you configure some of the SmartAccess functionality directly on the appliance. See Configuring SmartControl at Citrix Docs for detailed instructions.

Note: SmartControl requires NetScaler Platinum Edition.

  1. If you are using a Preauthentication Policy to run an Endpoint Analysis scan, edit the Preauthentication Profile.
  2. Configure the Default EPA Group with a new group name. You’ll use this group name later.
  3. If you are instead using a Session Policy/Profile to run the post-authentication Endpoint Analysis scan, edit the Session Profile, on the Security tab, use the Smartgroup field to define a group name for users that pass the scan. You’ll use this group name later.
  4. On the left, expand NetScaler Gateway, expand Policies, and click ICA.
  5. On the right, switch to the Access Profiles tab, and click Add.
  6. Configure the restrictions as desired, and click Create.
  7. Switch to the ICA Action tab, and click Add.
  8. Give the Action a name. Select the ICA Access Profile. Click Create.
  9. Switch to the ICA Policies tab, and click Add.
  10. Select the previously created ICA Action.
  11. Enter an expression. You can use HTTP.REQ.USER.IS_MEMBER_OF(“MyGroup”).NOT where MyGroup is the name of the SmartGroup you configured in the session profile or preauth scan. Click Create when done.
  12. Edit your Gateway Virtual Server.
  13. Scroll down to the Policies section, and click the plus icon.
  14. Change the Policy Type to ICA, and click Continue.
  15. Select the SmartControl policy you created earlier, and click Bind.

SmartAccess

CTX138110 How to Configure the SmartAccess feature on Access Gateway Enterprise Edition Appliance

In XenApp/XenDesktop, edit a Citrix policy, and add the Access Control filter. If you are using GPO to deliver Citrix Policies, then only Citrix Policies in the user half of the GPO support Access Control filters.

You can leave the default wildcards for farm name and condition to match all NetScaler Gateway connections. Or you can match specific NetScaler Gateway / Session Policy connections:

  • AG farm name = name of the NetScaler Gateway Virtual Server.
  • Access condition = name of the NetScaler Gateway Session Policy.

You typically create a Citrix policy to turn off all client device mappings for all external users. Then you create a higher priority Citrix policy that re-enables client device mappings for those users that passed the Endpoint Analysis scan expression on a particular Session Policy.

If you edit a Delivery Group, there’s an Access Policy page where you can hide or show the Delivery Group for all NetScaler Gateway connections, or for specific NetScaler Gateway Virtual Server / Session Policy connections.

  • Site or Farm name = NetScaler Gateway Virtual Server name
  • Filter = NetScaler Gateway Session Policy name

This configuration is only available at the entire Delivery Group. It is not possible to perform this configuration for only specific published applications, unless they are on different Delivery Groups.

 

When connected to a session, Director shows SmartAccess Filters on the session Details page. Notice the Farm Name (vServer name) and Filter Name (Session Policy name)

Related Pages

NetScaler Gateway 11.1 – RDP Proxy

Last Modified: Sep 2, 2018 @ 7:52 am

67 Comments

RDP Proxy

NetScaler supports RDP Proxy through NetScaler Gateway. No VPN required. In 11.1 and newer, RDP can connect to Gateway on 443. In older NetScaler, RDP connects on 3389.

There are several ways of launching RDP sessions through NetScaler Gateway RDP Proxy:

  • Bookmarks on the Clientless Access portal page.
    • Bookmarks can be defined by the administrator.
    • Or users can add their own RDP bookmarks.
  • After logging in, change the URL in the browser to /rdpproxy/MyRDPServer. MyRDPServer can be IP or DNS.
  • In the RfWebUI Portal Theme, the Add Bookmark link lets users enter an RDP address, and click Go.

The easy configuration is for one Gateway to do both authentication and RDP Proxy. Alternatively, you can have one Gateway vServer that authenticates the user and a different Gateway vServer to proxy the RDP connection. The Gateways use Secure Ticket Authority (STA) for mutual authentication. See Stateless RDP Proxy at docs.citrix.com for more information.

Links:

Here are some requirements for RDP Proxy:

  • NetScaler Enterprise Edition or Platinum Edition.
  • NetScaler Gateway Universal Licenses for each user.
    • NetScaler 11.1 build 49 and later come with built-in Gateway Universal licenses: NetScaler Standard Edition = 500 licenses, NetScaler Enterprise Edition = 1000 licenses, and NetScaler Platinum Edition = unlimited licenses.
  • TCP 443 opened to the NetScaler Gateway Virtual Server. If older NetScaler, open TCP 3389 to the Gateway.
  • TCP 3389 opened from the NetScaler SNIP to the RDP Servers.

Do the following to configure RDP Proxy:

  1. Go to System > Settings, and click Configure Advanced Features.
  2. Check the box for RDP Proxy, and click OK.
  3. Expand NetScaler Gateway, expand Policies, and click RDP.
  4. On the right, switch to the Client Profiles tab, and click Add.
  5. Give the Client Profile a name, and configure it as desired. Scroll down.
  6. It is no longer necessary to configure a Pre shared key or RDP Host. Just click Create.
  7. It is no longer necessary to create a RDP Server Profile.
  8. If you want to put RDP bookmarks on the Clientless Access portal page, on the left, expand NetScaler Gateway, expand Resources, and click Bookmarks.
  9. Alternatively, Simon Gottschlag Publish RDP Proxy Link via StoreFront shows how NetScaler Rewrite can insert an RDP Proxy link into a StoreFront web page.
  10. On the right, click Add.
  11. Give the Bookmark a name.
  12. For the URL, enter rdp://MyRDPServer using IP or DNS.
  13. Check the box next to Use NetScaler Gateway As a Reverse Proxy, and click Create.
  14. Create more bookmarks as desired.
  15. Create or edit a Session Profile/Policy.
  16. On the Security tab, set Default Authorization Action to ALLOW. Or you can use Authorization policies to control access.
  17. On the Remote Desktop tab, Override Global and select the RDP Client Profile you created earlier.
  18. If you want to use Bookmarks, on the Client Experience tab, set Clientless Access to On.
  19. On the Published Applications tab, make sure ICA Proxy is OFF.
  20. Edit or Create your Gateway Virtual Server.
  21. In the Basic Settings section, click More.
  22. It is no longer necessary to bind a RDP Server Profile. Instead, RDP is proxied through 443 on the Gateway.
  23. Scroll down. Make sure ICA Only is not checked. This means you’ll need NetScaler Gateway Universal licenses for each user that connects through this Gateway.
  24. Bind a certificate.
  25. Bind authentication policies.
  26. Bind the session policy/profile that has the RDP Client Profile configured.
  27. You can bind Bookmarks to either the NetScaler Gateway Virtual Server, or to a AAA group. To bind to the NetScaler Gateway Virtual Server, on the right, in the Advanced Settings section, click Published Applications.
  28. On the left, in the Published Applications section, click where it says No Url.
  29. While editing your Gateway vServer, you can also enable the new RfWebUI Portal Theme. This requires StoreFront to be 3.6 or newer.
  30. Bind your Bookmarks.
  31. Since this NetScaler Gateway Virtual Server has ICA Only unchecked, make sure your NetScaler Gateway Universal licenses are configured correctly. On the left, expand NetScaler Gateway and click Global Settings.
  32. On the right, click Change authentication AAA settings.
  33. Change the Maximum Number of Users to your licensed limit. In NetScaler 11.1 build 49 and newer, this value should already match the number of licensed users. In older builds, you must manually configure this setting, and if not configured, then it defaults to only 5 concurrent connections.

  34. If you want to connect to RDP servers using DNS, make sure DNS servers are configured on the appliance (Traffic Management > DNS > Name Servers).
  35. If you want to use the short names instead of FQDNs, add a DNS Suffix (Traffic Management > DNS > DNS Suffix).
  36. Connect to your Gateway and login.
  37. If you configured Bookmarks, if RfWebUI theme, on the Apps tab, click Web and SaaS Apps.
  38. If X1 theme, the bookmarks are on the Web Apps page.
  39. Then click the Bookmark. If RfWebUI theme, you can also click Details to mark the Bookmark as a Favorite.
  40. Or you can change the address bar to /rdpproxy/MyRDPServer. You can enter an IP address (e.g. rdpproxy/192.168.1.50) or a DNS name (/rdpproxy/myserver).
  41. If you edit the downloaded .rdp file, notice that it’s connecting on port 443.
  42. Then open the downloaded .rdp file.
  43. You can view the currently connected users by going to NetScaler Gateway > Policies > RDP, and on the right is the Connections tab.
  44. If using the RfWebUI theme, another way to launch RDP sessions is to click the Add Bookmark link, enter a destination DNS/IP, check the box next to RDP Link, and click Go.
  45. You can also Save the bookmark.
  46. Then access the saved bookmark from Apps > Personal Bookmarks.

  47. Personal bookmarks are stored in /var/vpn/bookmark on the appliance. You might want to back these up and replicate them to other Gateway appliances participating in GSLB. See NetScaler 11.1 Personal Bookmarks at Citrix Discussions.
  48. The X1 theme has an Add button on the Web Apps page.
  49. But there is no Go button. Instead, you save the Bookmark and launch it from the list.

NetScaler Gateway 11.1 RADIUS Authentication

Last Modified: Sep 21, 2019 @ 3:48 pm

14 Comments

Navigation

RADIUS Overview

For two-factor authentication using Azure Multi-factor Authentication, see Jason Samuel How to deploy Microsoft Azure MFA & AD Connect with Citrix NetScaler Gateway

Citrix CTX125364 How to Configure Dual Authentication on NetScaler Gateway Enterprise Edition for Use with iPhone and iPad.

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 authentication to NetScaler Gateway requires the RADIUS protocol to be enabled on the two-factor authentication product.

On your RADIUS servers, you’ll need to add the NetScaler appliances as RADIUS Clients. When NetScaler uses a local (same appliance) load balanced Virtual Server for RADIUS authentication, the traffic is sourced from the NetScaler SNIP (Subnet IP). When NetScaler 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 NetScaler NSIP (NetScaler IP). Use the correct IP(s) when adding the 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.

Two-factor Policies Summary

When configuring the NetScaler 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 NetScaler 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 Receiver Self-service (native Receiver on mobile, Windows, and Mac), the authentication policies are swapped:

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

If you need to support two-factor authentication from both web browsers and Receiver Self-Service, 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

Create Two-factor Policies

Do the following to create the Two-factor policies:

  1. Create an LDAP server.
  2. For RADIUS, on the left, expand Authentication, and click Dashboard.
  3. On the right, click Add.
  4. Change Choose Server Type to RADIUS.
  5. Give the server a name.
  6. Specify the IP address of the RADIUS load balancing Virtual Server.
  7. Enter the secret key specified when you added the NetScalers as RADIUS clients on the RADIUS server. Click Test Connection.
  8. Scroll down and click Create.

    add authentication radiusAction RSA -serverIP 10.2.2.210 -serverPort 1812 -radKey Passw0rd
  9. Since you can’t create authentication policies from the authentication dashboard, go to NetScaler Gateway > Policies > Authentication > RADIUS.
  10. On the right, in the Policies tab, click Add.
  11. Name it RSA-ReceiverSelfService or similar.
  12. Select the RADIUS server created earlier.
  13. 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.
  14. Click Create.

    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
  15. Create another 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

  16. Go to the NetScaler Gateway\Policies\Authentication\LDAP node.
  17. 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

Bind Two-factor Policies to Gateway

  1. When you create or edit a NetScaler Gateway Virtual Server, bind the 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 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 NetScaler Gateway object, change the Logon type to Domain and security token.

NetScaler Gateway 11.1 Virtual Server

Last Modified: Nov 7, 2020 @ 6:34 am

26 Comments

Navigation

💡 = Recently Updated

Change Log

NetScaler Gateway Universal Licenses

For basic ICA Proxy connectivity to XenApp/XenDesktop, you don’t need to install any NetScaler Gateway Universal licenses on the NetScaler appliance.

However, if you need SmartAccess features (e.g. EPA scans), or VPN, then you must install NetScaler Gateway Universal licenses. These licenses are included with the Platinum editions of XenApp / XenDesktop, Advanced or Enterprise editions of XenMobile, and the Platinum edition of NetScaler.

  • NetScaler 11.1 build 49 and later come with built-in Gateway Universal licenses: NetScaler Standard Edition = 500 licenses, NetScaler Enterprise Edition = 1000 licenses, and NetScaler Platinum Edition = unlimited licenses.

When you create a NetScaler Gateway Virtual Server, the ICA Only setting determines if you need NetScaler Gateway Universal licenses or not. If the Virtual Server is set to ICA Only, then you don’t need licenses. But if ICA Only is set to false then you need a NetScaler Gateway Universal license for every user that connects to this NetScaler Gateway Virtual Server. Enabling ICA Only disables all non-ICA Proxy features, including: SmartAccess, SmartControl, and VPN.

If you don’t need any non-ICA Proxy features, then you don’t need any Gateway Universal licenses, and you can skip to the next section.

If you are running NetScaler Platinum Edition 11.1 build 49 or later, then you already have unlimited licenses and can skip to the next section.

For other NetScaler editions and older builds, you can install more Gateway Universal licenses. The Gateway Universal licenses are allocated to the case sensitive hostname of each appliance. If you have an HA pair, and if each node has a different hostname, allocate the Gateway Universal licenses to the first hostname, and then reallocate the same licenses to the other hostname.

To see the hostname, click your username on the top right.

To change the hostname:

  1. Click the gear icon on the top right.
  2. Then click the third section.

To upload the allocated Gateway Universal licenses to the appliance, go to System > Licenses. A reboot is required.

After NetScaler Gateway Universal licenses are installed on the appliance, they won’t necessarily be available for usage until you make a configuration change as detailed below:

  1. On the left, expand System, and click Licenses.
  2. On the right, in the Maximum NetScaler Gateway Users Allowed field is the number of licensed users for NetScaler Gateway Virtual Servers that are not set to ICA Only.
  3. On the left, under NetScaler Gateway, click Global Settings.
  4. In the right column of the right pane, click Change authentication AAA settings.
  5. Change the Maximum Number of Users to your licensed limit. In NetScaler 11.1 build 49 and newer, this value should already match the number of licensed users. In older builds, you must manually configure this setting, and if not configured, then it defaults to only 5 concurrent connections.

  6. If desired, check the box for Enable Enhanced Authentication Feedback. Click OK.

    set aaa parameter -enableEnhancedAuthFeedback YES -maxAAAUsers 200

Create Gateway Virtual Server

  1. Create a certificate for the NetScaler Gateway Virtual Server. The certificate must match the name users will use to access the Gateway.
  2. For email discovery in Citrix Receiver, the certificate must have subject alternative names (SAN) for discoverReceiver.email.suffix (use your email suffix domain name). If you have multiple email domains then you’ll need a SAN for each one.

  3. On the left, right-click NetScaler Gateway and click Enable Feature.
  4. On the left, expand NetScaler Gateway and click Virtual Servers.
  5. On the right, click Add.
  6. Name it gateway.corp.com or similar.
  7. Enter a new VIP that will be exposed to the Internet. Note: you can also set it to Non Addressable, which means you can place the Gateway behind a Content Switching Virtual Server.
  8. Click More.
  9. Check the box next to ICA Only. This option disables SmartAccess and VPN features but does not require any additional licenses.
  10. Check the box next to DTLS, and click OK.
  11. DTLS enables EDT protocol, UDP Audio, and Framehawk.  💡
  12. EDT requires UDP 443 on client side, and UDP 1494/2598 on server side.
  13. DTLS (including EDT), will not work if Mac Based Forwarding is enabled.  💡
  14. In the Certificates section, click where it says No Server Certificate.
  15. Click the arrow next to Click to select.
  16. Select a previously created certificate that matches the NetScaler Gateway DNS name and click Select.
  17. Click Bind.
  18. If you see a warning about No usable ciphers, click OK.
  19. Click Continue.
  20. In the Basic Authentication section, click the plus icon in the top right.
  21. Note: it’s also possible to disable authentication on Gateway and make StoreFront do it instead as described in Citrix CTX200066 How to Log On to StoreFront When Authentication is Disabled on NetScaler Gateway VIP. However, it’s more secure to require Gateway to authenticate the users before the user can communicate with StoreFront.
  22. Select LDAP, select Primary and click Continue.
  23. If you used the authentication dashboard to create the LDAP server then you probably haven’t created the corresponding policy yet. Click the plus icon to create a new policy.
  24. Use the Server drop-down to select the previously created LDAP server.
  25. Give the policy a name. The policy name can match the Server name.
  26. In the Expression box, enter ns_true, or select it from the Saved Policy Expressions drop-down. Click Create.
  27. Click Bind.
  28. Or for two-factor authentication, you will need to bind two policies to Primary and two polices to Secondary:
    • Primary = LDAP for Browsers (User-Agent does not contain CitrixReceiver)
    • Primary = RADIUS for Receiver Self-Service (User-Agent contains CitrixReceiver)
    • Secondary = RADIUS for Browsers (User-Agent does not contain CitrixReceiver)
    • Secondary = LDAP for Receiver Self-Service (User-Agent contains CitrixReceiver)
  29. Click Continue.
  30. Scroll down to the Profiles section and click the pencil icon.
  31. In the TCP Profile section, do one of the following:
    1. Follow the instructions at Citrix CTX232321 Recommended TCP Profile Settings for Full Tunnel VPN/ICAProxy from NetScaler Gateway 11.1 Onwards. In this case, there’s no need to change the TCP Profile.  💡
    2. In the TCP Profile drop-down, select nstcp_default_XA_XD_profile, and click OK.
  32. In the Policies section, click the plus icon near the top right.
  33. Select Session, select Request and click Continue.
  34. Click the arrow next to Click to select.
  35. Select one of the Receiver session policies and click Select. It doesn’t matter in which order you bind them.
  36. There’s no need to change the priority number. Click Bind.
  37. Repeat these steps to bind the second policy. In the Policies section, click the plus icon near the top right.
  38. Select Session, select Request and click Continue.
  39. Click Add Binding.
  40. Click the arrow next to Click to select.
  41. Select the other Receiver session policy and click Select.
  42. There’s no need to change the priority number. Click Bind.
  43. The two policies are mutually exclusive so there’s no need to adjust priority. Click Close.
  44. On the right, in the Advanced Settings section, click Published Applications.
  45. Click where it says No STA Server.
  46. Add a Delivery Controller in the https://<Controller_FQDN> or http://<Controller_FQDN> format, depending on if SSL is enabled on the Delivery Controller or not. This must be a FQDN or IP address. Short names don’t work.
  47. Click Bind.
  48. To bind another Secure Ticket Authority server, on the left, in the Published Applications section, click where it says 1 STA Server.
  49. Click Add Binding.
  50. Enter the URL for the second Controller and click Bind.
  51. This view shows if the STAs are reachable or not. To refresh the view, close the STA Bindings list and reopen it.

    add vpn vserver gateway.corp.com SSL 10.2.2.200 443 -icaOnly ON -dtls ON -tcpProfileName nstcp_default_XA_XD_profile

bind vpn vserver gateway.corp.com -policy "Receiver Self-Service" -priority 100

bind vpn vserver gateway.corp.com -policy "Receiver for Web" -priority 110

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

bind vpn vserver gateway.corp.com -staServer "http://xdc01.corp.local"
bind vpn vserver gateway.corp.com -staServer "http://xdc02.corp.local"

bind vpn vserver gateway.corp.com -portaltheme RfWebUI
  52. If you haven’t enabled the Default SSL Profile, then perform other normal SSL configuration including: disable SSLv3, bind a Modern Cipher Group, and enable Strict Transport Security. 
    bind ssl vserver MyvServer -certkeyName MyCert

set ssl vserver MyvServer -ssl3 DISABLED -tls11 ENABLED -tls12 ENABLED

unbind ssl vserver MyvServer -cipherName ALL

bind ssl vserver MyvServer -cipherName Modern

bind ssl vserver MyvServer -eccCurveName ALL

bind vpn vserver MyvServer -policy insert_STS_header -priority 100 -gotoPriorityExpression END -type RESPONSE

Verify SSL Settings

After you’ve created the Gateway Virtual Server, run the following tests:

  1. Citrix CTX200890 – Error: “1110” When Launching Desktop and “SSL Error” While Launching an Application Through NetScaler Gateway: You can use OpenSSL to verify the certificate. Run the command: openssl s_client -connect gateway.corp.com:443. Replace the FQDN with your FQDN. OpenSSL is installed on the NetScaler or you can download and install it on any machine.
  2. Go to https://www.ssllabs.com/ssltest/ and check the security settings of the website. Citrix Blogs – Scoring an A+ at SSLlabs.com with Citrix NetScaler – 2016 update.

Gateway Portal Theme

Citrix Blog Post Branding your Deployment Part 2: Matching NetScaler to StoreFront explains NetScaler Gateway Portal Themes, how to edit the Portal Theme CSS, and warns about GUI changes overwriting CSS file changes.

If you want the logon page for NetScaler Gateway to look more like StoreFront 3.0 and newer, enable the built-in RfWebUI or X1 theme. RfWebUI is optimized for Unified Gateway (Clientless VPN) since it provides the exact same appearance and user experience as StoreFront 3.x. The Unified Gateway RfWebUI theme can display RDP Links and Web Links (bookmarks) along with the familiar StoreFront apps and desktops. Note: RfWebUI requires StoreFront 3.6 or newer.

  1. Go to NetScaler Gateway > Virtual Servers and edit an existing Virtual Server.

  2. On the right, in the Advanced Settings section, click Portal Themes.
  3. On the left, Change the Portal Theme drop-down to RfWebUI. Click OK.
  4. Click Done.

    bind vpn vserver gateway.corp.com -portaltheme RfWebUI
  5. When you access the NetScaler Gateway login page you’ll see the theme.

Custom Theme

You can also your own theme by starting from one of the built-in themes:

  1. Go to NetScaler Gateway > Portal Themes.
  2. On the right, click Add.
  3. Give the theme a name, and select RfWebUI as the Template Theme. Click OK.
  4. In the Look and Feel section, there are two sub-sections: one for Home Page and one for Common Attributes.
  5. The Home Page is for Unified Gateway (aka VPN Clientless Access). Notice that the Websites Sections can be disabled.
  6. The Help Legend link shows you what the other fields modify.
  7. If you want to modify the logon page, use the Common Attributes sub-section.
  8. The Help Legend link shows you what the fields modify.
  9. Make changes as desired and click OK.
  10. After you click OK, the Language section appears.
  11. In the Language section, select a language and click OK.
  12. On the right, in the Advanced Settings section, click Login Page.
  13. Make changes as desired (e.g. Password Field Titles) and click OK.
  14. At the top of the screen, click the link to Click to Bind and View Configured Theme.
  15. Select a Gateway Virtual Server and click Bind and Preview.
  16. The logon page is displayed.
  17. You could go to /var/netscaler/logon/themes/MyTheme/css and make more changes to custom.css, but this file gets overwritten any time you make a change in the Portal Themes section of the NetScaler GUI.
  18. Citrix CTX209526 NetScaler; How to Copy a Portal Theme from the Device running version 11.0 to another Device running 11.0.

SSL Redirect

Use one of the following procedures to configure a redirect from http to https. Responder method is preferred.

Public DNS SRV Records

For email-based discovery, add a SRV record to each public email suffix DNS zone. Here are sample instructions for a Windows DNS server:

  1. In Server Manager, click Tools > DNS Manager
  2. In the left pane of DNS Manager, select your DNS domain in the forward or reverse lookup zones. Right-click the domain and select Other New Records.
  3. In the Resource Record Type dialog box, select Service Location (SRV) and then click Create Record.
  4. In the New Resource Record dialog box, click in the Service box and enter the host value _citrixreceiver.
  5. Click in the Protocol box and enter the value _tcp.
  6. In the Port number box, enter 443.
  7. In the Host offering this service box, specify the fully qualified domain name (FQDN) for your NetScaler Gateway Virtual Server in the form servername.domain (e.g. gateway.company.com)

Block Citrix VPN for iOS

Citrix CTX201129 Configuration for Controlled Access to Different VPN Plugin Through NetScaler Gateway for XenMobile Deployments: do one or both of the following:

  • Create an AppExpert > Responder > Policy with Action = DROP and Expression = HTTP.REQ.HEADER("User-Agent").CONTAINS("CitrixReceiver/NSGiOSplugin"). Either bind the Responder Policy Globally, or bind it to the Gateway vServers.
  • In your Gateway Session Policies, on the Client Experience tab, set the Plug-in Type to Java. If any of them are set to Windows/MAC OS X, then VPN for iOS is allowed.

View ICA Sessions

To view active ICA sessions, click the NetScaler Gateway node on the left, and then click ICA Connections on the right.

show vpn icaconnection

Customize Logon Page

Logon Page Labels

When two factor authentication is configured on NetScaler Gateway, the user is prompted for User name, Password, and Password 2.

The Password field labels can be changed to something more descriptive, such as Active Directory or RSA:

To change the labels, edit a Portal Theme:

  1. Go to NetScaler Gateway > Portal Themes and edit an existing theme. You can’t edit the built-in themes so you’ll have to create one if you haven’t already.
  2. On the right, in the Advanced Settings column, click Login Page.
  3. In the Login Page section, change the two Password fields to your desired text. Click OK.
  4. If using the RfWebUI theme, the default text size for the form field labels is 17px. However, the Portal Themes editor defaults to 12px. You can change it back to 16px or 18px by editing Form Font Size in the Look and Feel > Common Attributes section.
  5. In the Portal Theme section at the top of the page, you can Click to bind and View Configured Theme to Preview your changes.
  6. On Platinum Edition appliances, you might have to invalidate the loginstaticobjects Content Group (Optimization > Integrated Caching > Content Groups) before the changes appear. This seems to be true even if Integrated Caching is disabled.

 Logon Security Message (Disclaimer, EULA)

You can force users to agree to a EULA before they are allowed to login.

Clicking the Terms & Conditions link allows the user to view the EULA text that you have entered.

Do the following to configure the EULA:

  1. Go to NetScaler Gateway > Resources > EULA.
  2. On the right, click Add.
  3. Give the EULA a name and enter some text. You can even enter HTML code. See the example posted by Chris Doran at Citrix Discussions.
  4. Click Create.
  5. Edit a Gateway Virtual Server.
  6. On the right, in the Advanced Settings column, click EULA.
  7. Click where it says No EULA.
  8. Click the arrow next to Click to select.
  9. Select the EULA and click Select.
  10. Click Bind.
  11. Mike Roselli at Automatic EULA Acceptance by Cookie Rewrite Guide at Citrix Discussions details Rewrite policies that change the behavior so that users only have to accept the EULA once. It records acceptance in a cookie.
  12. Sam Jacobs Adding an EULA for AAA Login at CUGC explains how to enable the EULA on the AAA logon page.  💡

Theme File Customization

The original themes (Default, Green Bubble, and X1) use files from /netscaler/ns_gui/vpn/js and /var/netscaler/logon/themes. A commonly edited file is /netscaler/ns_gui/vpn/js/gateway_login_form_view.js since this file is responsible for rendering the logon form.

The new RfWebUI theme is different than the original themes, because it pulls files from /var/netscaler/logon/LogonPoint/receiver. This means the customizations for NetScaler 11.0 won’t work with the new RfWebUI theme. When reviewing customization guides for NetScaler 11, be aware that most of them won’t work for the RfWebUI theme.

Citrix CTX202444 How to Customize NetScaler Gateway 11 logon Page with Links shows how to add links to the NetScaler Gateway 11 logon page. This only works in the Default, Green Bubble, and X1 themes (no RfWebUI theme).

Other Customizations

CTP Sam Jacobs at Adding Text, Links and Other Elements to the NetScaler Logon Page – Part 2 at CUGC explains how to add text to the RfWebUI theme logon page. The process for RfWebUI is quite different than the older themes:

  • Text is stored in /var/netscaler/logon/themes/<theme>/strings.<language code>.json
  • Custom CSS is stored in /var/netscaler/logon/themes/<theme>/css/theme.css
  • Sample Logon Page:
    Logon screen with footer.jpg

CTP Sam Jacobs at Adding Text, Links and Other Elements to the NetScaler Logon Page – Part 1 at CUGC explains how to modify custom.css and en.xml to add text below the logon box on the Logon Page. No Rewrite policies or source code modifications needed.

Citrix CTX215817 NetScaler : How to Customize Footer of NetScaler Gateway Login Page. This article does not work with the RfWebUI theme, but it works with the X1 theme.

Mike Roselli at Netscaler 11 Theme Customization – How to Add Links and Verbiage at discussions.citrix.com has sample rewrite policies to customize the NetScaler Gateway logon page with additional HTML.

 

Craig Tolley Customising the NetScaler 11 User Interface – Adding Extra Content: add new sections to login page. These sections pull content from local HTML files.

 

Daniel Ruiz Set up a maintenance page on NetScaler Gateway: configure a Responder policy (see the blog post for sample HTML code). During maintenance, manually bind the Responder policy to the Gateway. Manually remove the policy after maintenance is complete.

 UDP Audio Through Gateway

From John Crawford at Citrix Discussions and Marius Sandbu Enabling Citrix Receiver audio over Netscaler Gateway with DTLS

Note: Enabling DTLS on the Gateway also enables Framehawk and EDT. See Citrix Policy Settings for Framehawk configuration.

Requirements for UDP Audio:

  • Citrix Receiver 4.2 or newer
  • NetScaler Gateway 10.5.e (enhancement build) or NetScaler 11 or newer
  • UDP 443 allowed to NetScaler Gateway Virtual Server
  • UDP 16500-16509 allowed from NetScaler SNIP to VDAs

To enable UDP Audio through Gateway, make changes on both the NetScaler Gateway Virtual Server and in Receiver:

  1. Edit the NetScaler Gateway Virtual Server. In the Basic Settings section click the edit (pencil) icon.
  2. Click More.
  3. Enable the DTLS option, and click OK.
  4. After enabling DTLS, it probably won’t work until you unbind the Gateway certificate and rebind it.

Client-side configuration

There are two methods of enabling RTP on the client side:

  • Edit default.ica on the StoreFront server
  • Use GPO to modify the client-side config

To edit the default.ica file on the StoreFront server (h/t Vipin Borkar): Edit the file C:\inetpub\wwwroot\Citrix\Store\App_Data\default.ica and add the following lines to the Application section:

EnableRtpAudio=true
EnableUDPThroughGateway=true
AudioBandwidthLimit=1

To use GPO to modify the client-side config:

  1. Copy the receiver.admx (and .adml) policy template into PolicyDefinitions if you haven’t already.
  2. Edit a GPO that applies to Receiver machines. You can also edit the local GPO on a Receiver machine.
  3. Go to Computer Configuration > Policies > Administrative Templates > Citrix Components > Citrix Receiver.
  4. Edit the setting Client audio settings.
  5. Enable the setting.
  6. Set audio quality as desired. Higher quality = higher bandwidth.
  7. Check to Enable Real-Time Transport.
  8. Check to Allow Real-Time Transport through Gateway. Click OK.

Next step

Configure StoreFront to use NetScaler Gateway

StoreFront – Rewrite X-Citrix-Via

When NetScaler Gateway communicates with StoreFront, it adds a header called X-Citrix-Via that contains the FQDN entered in the user’s address bar. StoreFront uses this header to find a matching Gateway object so StoreFront knows how to handle the authentication. In NetScaler 11.0 and newer, you can create a rewrite policy to change this header. This is useful when changing URLs or using DNS aliases for Gateways. See CTX202442 FAQ: Modify HTTP Header X-Citrix-Via on NetScaler for more details.

Here’s a sample rewrite policy for this header:

enable ns feature REWRITE

add rewrite action rwact_storefront replace "HTTP.REQ.HEADER(\"X-Citrix-Via\")" "\"mystorefront.mydomain.com\""

add rewrite policy rwpol_storefront "HTTP.REQ.HEADER(\"X-Citrix-Via\").NE(\"mystorefront.mydomain.com\")" rwact_storefront

bind vpn vserver mygateway-vs -policy rwpol_storefront -priority 100 -type REQUEST

NetScaler Gateway 11.1 – SSL VPN

Last Modified: Nov 7, 2020 @ 6:35 am

43 Comments

Navigation

💡 = Recently Updated

Overview

Here’s an overview of the NetScaler Gateway connection process:

  1. Users use SSL/TLS to connect to a NetScaler Gateway Virtual Server (VIP).
  2. NetScaler Gateway prompts the user for authentication.
  3. Once the user is authenticated, NetScaler Gateway uses Session Policies/Profiles to determine what happens next.

NetScaler Gateway supports five different connection methods:

  • ICA Proxy to XenApp/XenDesktop – the client is built into Citrix Receiver
  • SSL VPN – requires installation of NetScaler Gateway plug-in
  • Clientless – browser only, no VPN client, uses rewrite
  • Secure Browse – from MDX-wrapped mobile applications (XenMobile), uses rewrite
  • RDP Proxy – only RDP client is needed

You can configure NetScaler Gateway Session Policies/Profiles to only use one of the connection methods. Or NetScaler Gateway can be configured to let users choose between ICA Proxy, Clientless, and SSL VPN connection methods. Here’s a sample Client Choices screen using the RfWebUI theme:

Session Policies/Profiles have several settings that control the behavior seen after authentication:

  • ICA Proxy – ON or OFF
    • If ON, then ICA Proxy is the only connection method allowed, overriding the other connection methods.
    • ICA Proxy does not launch the VPN client. It only needs Citrix Receiver.
    • ICA Proxy shows the Webpage that’s configured in the Web Interface Address field of the Session Profile. This is typically the StoreFront Receiver for Web page, but technically it can be any internal website.
    • If OFF, that doesn’t mean ICA Proxy doesn’t work. You can still send ICA traffic to the NetScaler Gateway Virtual Server, and the NetScaler Gateway Virtual Server will still proxy it to internal VDAs.
    • Setting it to OFF allows the other connection methods to function. For example, Clientless Access can show both NetScaler Gateway Bookmarks and StoreFront published apps. If VPN is launched, then the portal page shown to the user after the tunnel is established can contain the StoreFront published applications.
  • Clientless Access – On, Off, Allow
    • If On, then Clientless is the only connection method allowed, assuming ICA Proxy is not set to ON. After the user logs in, the user is presented with a portal page that contains a list of bookmarks and/or StoreFront published icons. The VPN Client is not launched.
    • The Home Page setting in the Session Profile allows you to display an internal website instead of displaying the NetScaler Gateway Portal Page.
    • Bookmarks are configured at NetScaler Gateway > Resources > Bookmarks. You can bind the Bookmarks (Urls) to the NetScaler Gateway Virtual Server, or to AAA Groups.
    • Only Bookmarks configured for Clientless Access will work. The internal websites are rewritten so they are proxied through NetScaler Gateway. For example, if the internal website is http://intranet.corp.local, then Gateway rewrites them to https://gateway.corp.com/cvpn/http/internal.corp.local. This causes the web browser to send the HTTP Request to NetScaler Gateway, which then forwards the HTTP Request to the internal web server. No VPN needed.
  • Plug-in Type – Windows/MAC OS X
    • If both Clientless and ICA Proxy are set to Off, then the VPN Client will be downloaded and launched.
    • Once the VPN tunnel is established, the webpage configured in the Home Page setting is displayed. Or the NetScaler Gateway Portal Page (Clientless Access) is displayed if no Home Page is configured. The Bookmarks in the Portal Page can link to internal websites that are only accessible through a VPN tunnel. Or Bookmarks can be configured for Clientless Access.
    • Additional Gateway objects control VPN behavior including: DNS Suffix, Intranet Applications, Intranet IPs, and Authorization Policies.
  • Client Choices – checked or unchecked
    • If Client Choices is checked, then it displays a page containing up to three buttons corresponding to the connection methods shown above. The Network Access with the NetScaler Gateway Plug-in (VPN)  button is always displayed. The Clientless Access button is displayed if Clientless Access is set to On or Allow. The Virtual App and Desktop Access button is displayed if a Web Interface Address is configured.

Here are some characteristics of Session Policies/Profiles:

  • Policy Expression – If the Session Policy Expression is true, then the settings contained in the Session Profile are applied.
    • The Session Profile is also sometimes called the Action. That’s because all NetScaler policies follow a standard structure – if the expression evaluates to True, then perform the Action. For Session Policies in particular, the policy Action = Session Profile.
    • Session Policy Expressions are typically ns_true, which is always true, or an Endpoint Analysis (EPA) Scan created using the OPSWAT EPA Editor. In the latter case, the Session Profile only applies if the EPA scan succeeded.
  • Policy Bind Points – Session Policies can be bound to three different bind points – NetScaler Gateway Virtual Server, AAA Groups, and AAA User.
    • When bound to a NetScaler Gateway Virtual Server, the Session policy/profile applies to all users that log into that Virtual Server.
    • When bound to a AAA Group, the Session policy/profile only applies to members of the AAA group (Active Directory group or local group)
    • When  bound to a AAA User, the Session policy/profile only applies to the AAA user (Active Directory user or local user)
  • Profile Conflicts – Multiple Session Policies/Profiles could apply to a single session. In this case, the Profile settings are merged. But if there’s a conflict (e.g. one Session Profile enables Clientless access, but another Session Profile disables Clientless access), then which one wins?
    • Priority number – When you bind a Session Policy to a bind point, you specify a priority number. This priority number usually defaults to 100.
    • Lowest priority number wins – The Session Policy bind point that has the lowest priority number, wins. Session Policies bound with a priority of 80 will win over Session Policies bound with a priority of 100. Remember, for settings that don’t conflict, the two Profiles merge, but for settings that do conflict, the lower priority number policy/profile settings win.
    • Bind point types – The type of bind point doesn’t matter. If you bind a Session Policy to a AAA Group with a priority of 100, and you also bind a Session Policy to the NetScaler Gateway Virtual Server with a priority of 80, then the conflicting settings in the Session Policy bound to the NetScaler Gateway Virtual Server will win. You might think that AAA-bound policies always override Virtual Server-bound policies, but that is not the case.

AAA Groups are a critical component of NetScaler Gateway VPN configuration:

  • Group extraction – Make sure the LDAP Policy/Server is configured to extract to the user’s Active Directory Groups.
  • Create AAA Groups on the NetScaler that match exactly (case sensitive) with the user’s Active Directory Group Name.
  • You can then bind policies and other Gateway objects to the AAA Group, and these bindings only affect that particular AAA Group. These bindings include:
  • If the user belongs to multiple AAA Groups, then policies are applied as follows:
    • Session Policies – the settings are merged, unless there’s a conflict. If a conflict, then the policy with the lowest priority number wins.
    • Bookmarks, Intranet Applications, and Authorization Policies are merged.
    • Intranet IPs (IP Pool) are probably random allocation. It’s probably best to make sure a user only belongs to one AAA Group that assigns Intranet IPs.
  • You can also create local AAA Groups that are unrelated to Active Directory groups. There are several ways of getting users into these local AAA groups:
    • Create local AAA Users and assign them to the AAA Group
    • Configure Session Policy/Profile with a Client Security Check String (EPA Scan). If the scan succeeds, users are placed into local Authorization AAA Groups. If the scan fails, then users are placed into a local Quarantine AAA Group and removed from all other AAA Groups.
    • When users are authenticated with a particular authentication server, the authentication server can be configured to place users into a Default Authentication Group. This lets you apply different Session Policy/Profiles (and other Gateway objects) depending on how the user authenticated.

NetScaler Gateway supports Client Security Expressions (Endpoint Analysis expressions) at three different locations:

  • Preauthentication Policy Expression
    • If the EPA Scan succeeds, then the user is allowed to login.
    • If the EPA Scan fails, then the user is not allowed to login.
    • Preauthentication Policies are bound to NetScaler Gateway Virtual Servers only, and thus applies to all users of that Virtual Server.
  • Session Policy Expression –
    • This type of EPA Scan is configured in the Session Policy Expression, not the Profile.
    • If the EPA Scan succeeds, then the settings in the Session Profile are applied to the session.
    • If the EPA Scan fails, then the Session Profile is ignored. Other Session Policies expressions are still evaluated. Remember, Session Policy/Profiles merge, so all applicable Session Policies must be considered.
    • A limitation of this EPA method is that nothing negative happens. Instead, you typically design higher priority number (lower priority) Session Policies with restrictive settings so that if the EPA Scans fail, then users still get something. For example, youcan  configure your highest priority number Session Policy/Profile with StoreFront (ICA Proxy) only. In the lower priority number Session Policies/Profiles, VPN might be enabled, but only if the EPA scan succeeds. More restrictive Session Profiles usually uncheck Client Choices, and enable Clientless Access or ICA Proxy.
    • This method of EPA Scans is used in SmartAccess and SmartControl configurations.
  • Session Profile > Security > Advanced Settings > Client Security Check String
    • If the EPA Scan succeeds, add the user to the listed Authorization AAA Groups.
    • If the EPA Scan fails, add the user to the selected Quarantine Group, and remove the user from all other AAA Groups.
  • Assigning EPA scans to Session Policies and Session Profiles is also known as Post-Authentication EPA Scans.
  • If Endpoint Analysis is configured anywhere, then an Endpoint Analysis plug-in is downloaded to the Windows or Mac client.

Prerequisites

Except for ICA Proxy, all NetScaler Gateway connection methods require a NetScaler Gateway Universal License for each concurrent session. Go to System > Licenses and make sure NetScaler Gateway User licenses are installed.

Also make sure the maximum AAA users equals the number of licenses. Go to NetScaler Gateway > Global Settings > Change authentication AAA settings.

DNS usually needs to function across the VPN tunnel. Go to Traffic Management > DNS > Name Servers to add DNS servers.

Create Session Profile

To enable SSL VPN: first create the Session Profile. Then create a Session Policy.

You can create multiple session Policies/Profiles with different settings. Then you can bind these Session Policies to AAA groups and/or NetScaler Gateway Virtual Servers.

To enable SSL VPN in a Session Profile:

  1. On the left, expand NetScaler Gateway, expand Policies, and click Session.
  2. On the right, switch to the Session Profiles tab, and click Add.
  3. Name the profile VPN or similar.
  4. In Session Profiles, every line has an Override Global checkbox to the right of it. If you check this box next to a particular field, then the field in this session profile will override settings configured globally or in a lower priority session policy.
  5. Switch to the Network Configuration tab.
  6. You will find a setting that lets you select a DNS Virtual Server. Or if you don’t select anything, then the tunnel will use the DNS servers configured under Traffic Management > DNS > Name Servers.
  7. Switch to the Client Experience tab. This tab contains most of the NetScaler Gateway VPN settings.
  8. Override Plug-in Type and set it to Windows/Mac OS X.
  9. On the Client Experience tab, override Split Tunnel and make your choice. Setting it to OFF will force all traffic to use the tunnel. Setting it to ON will require you to create Intranet Applications so the NetScaler Gateway Plug-in will know which traffic goes through the tunnel, and which traffic goes directly out the client NIC (e.g. to the Internet). REVERSE means all traffic goes through the tunnel except for the addresses defined in Intranet Applications.
  10. On the Client Experience tab, there are timers that can be configured. Global Settings contains default timers, so you might want to configure this Session Profile to override the defaults and increase the timeouts. See Configuring Time-Out Settings at Citrix Docs for details.
    1. Client Idle Time-out is a NetScaler Gateway Plug-in timer that disconnects the session if there is no user activity (mouse, keyboard) on the client machine.
    2. Session Time-out is a NetScaler timer that disconnects the session if there is no network activity for this duration.
    3. In addition to these two timers, on the Network Configuration tab, under Advanced Settings, there’s a Forced Timeout setting.

  11. By default, once the VPN tunnel is established, a portal page appears containing bookmarks, and StoreFront published icons. An example of the portal page in the RfWebUI theme is shown below:
  12. The X1 theme is shown below:
  13. On the Client Experience tab, the Home Page field lets you override the the default portal page, and instead display a different webpage (e.g. Intranet). This homepage is displayed after the VPN tunnel is established (or immediately if connecting using Clientless Access).
  14. NetScaler Gateway 11.1 can now automatically start the VPN tunnel whenever the user is remote. Click the plus icon next to AlwaysON Profile Name.
  15. Give the profile name. Hover over the question marks to see what each of them does. Then click Create. More info at AlwaysON at Citrix Docs.
  16. Additional VPN settings can be found by clicking Advanced Settings near the bottom of the Client Experience tab.
  17. Under Client Experience > Advanced Settings, on the General tab, there are settings to run a login script at login, enable/disable Split DNS, and enable Local LAN Access. Use the question marks to see what they do. Reliable DNS occurs when Split DNS is set to Remote.
  18. Note: if Split Tunnel is OFF, and if Split DNS is set to REMOTE, NetScaler only returns one IP address to DNS queries. This behavior can be changed by following Citrix CTX200243 DNS Query Responds with Only One IP to Client PC When Connected Through NetScaler Gateway Full VPN.  💡
  19. Under Client Experience > Advanced Settings, on the General tab, is a checkbox for Client Choices. This lets the user decide if they want VPN, Clientless, or ICA Proxy (StoreFront). Without Client Choices, one of the connection methods will occur automatically, depending on what’s enabled.
  20. On the main Client Experience tab, if you enabled Client Choices, you can set Clientless Access to Allow to add Clientless to the list of available connection methods.
  21. An example of Client Choices is shown below:
  22. The Client Experience > Advanced Settings section has additional tabs. A commonly configured tab is Proxy, which allows you to enable a proxy server for VPN users.
  23. Back in the main Session Profile, switch to the Security tab.
  24. Set the default authorization to Allow or Deny. If Deny (recommended), you will need to create authorization policies to allow traffic across the tunnel. You can later create different authorization policies for different groups of users.
  25. On the Published Applications tab, set ICA Proxy to Off. This ensures VPN is used instead of ICA Proxy.
  26. Configure the Web Interface Address, to embed StoreFront into the default portal page. Note: for X1 theme, additional iFrame configuration is required on the StoreFront side as detailed below. RfWebUI theme does not need any StoreFront changes.
  27. From Michael Krasnove: if you configured the Session Policy to direct users to StoreFront, but aren’t using RfWebUI, then placing the following code in c:\inetpub\wwwroot\Citrix\StoreWeb\custom\script.js will cause StoreFront to end the VPN tunnel when the user logs off of StoreFront. 
    var LOGOFF_REDIRECT_URL = 'https://YourGatewayFQDN.com/cgi/logout';
 
// Prevent the default "logoff" screen from being displayed
CTXS.Controllers.LogoffController.prototype._handleLogoffResult = $.noop;
 
CTXS.Extensions.afterWebLogoffComplete = function () {
 window.location.href = LOGOFF_REDIRECT_URL;
};
  28. Click Create when you’re done creating the Session Profile.

Create Session Policy

Once the Session Profile is created, you need a Session Policy linked to it. The Session Policy contains an expression, where if true, then the Session Profile is applied.

If multiple Session Policies apply to a particular connection, then the settings in the policies are merged. For conflicting settings, the Session Policy with the highest priority (lowest priority number) wins. Session Policies bound to AAA groups only override Session Policies bound to NetScaler Gateway Virtual Servers if the AAA group bind point has a lower priority number. In other words, priority numbers are evaluated globally no matter where the Session Policy is bound. You can run the command nsconmsg –d current –g pol_hits to see which Session Policies are applying to a particular connection. See CTX214588 Understanding Session Policy Priority on Different Bind Points.

You can also bind Endpoint Analysis expressions to a Session Policy so that the Session Policy only applies to machines that pass the Endpoint Analysis scan.

To create a Session Policy that is linked to a Session Profile:

  1. In the right pane, switch to the Session Policies, tab and click Add.
  2. Give the policy a descriptive name.
  3. Change the Profile drop-down to the VPN Profile you just created.
  4. Add a policy expression. You can enter ns_true, which applies to all connections. This box uses classic expression syntax.
  5. Or you can add Endpoint Analysis scans. If the Endpoint Analysis scan succeeds, then the session policy is applied. If the Endpoint Analysis scan fails, then this session policy is skipped, and the next one is evaluated. This is how you can allow VPN if EPA scan succeeds, but all failed EPA scans will get a different session policy that only has ICA Proxy enabled.
  6. To add an Endpoint Analysis scan, use one of the Editor links on the right.
  7. Configure OPSWAT scans in the OPSWAT EPA Editor.
  8. Configure Client Security Expressions in the Expression Editor.
  9. You can combine multiple Endpoint Analysis scan expressions using Booleans (&&, ||, !). Click Create when done.

Bind Session Policy

Most of the NetScaler Gateway configuration objects can be bound to NetScaler Gateway Virtual Server, AAA Group, or both. This section details binding of Session Policies, but the other NetScaler Gateway objects (e.g. Authorization Policies) can be bound using similar instructions.

If you bind the Session Policy to a AAA group, only members of that Active Directory group will evaluate the policy expression and potentially receive the Session Profile settings.

Bind the new Session Policy to a NetScaler Gateway Virtual Server, or a AAA group.

  1. To bind to a NetScaler Gateway Virtual Server, edit a NetScaler Gateway Virtual Server (or create a new one).
  2. Click the pencil icon for the Basic Settings section.
  3. Click More.
  4. Make sure ICA Only is unchecked and click OK. If this box is checked then VPN, Clientless, and other features won’t work.
  5. Note: with this box unchecked, Gateway Universal licenses are now required for all users connecting through this Gateway vServer.
  6. Scroll down to the Policies section, and click the Plus icon.
  7. In the Choose Type page, select Session, Request and click Continue.
  8. Click to select.
  9. Select the policy, and click Select.
  10. Click Bind.
  11. If you bind multiple session policies, the policies are merged based on priority number. This is where you specify a priority for each bound policy. See CTX214588 Understanding Session Policy Priority on Different Bind Points.
  12. You can also edit the policy or profile from this screen by clicking the ellipsis icon next to each bound policy.
  13. While editing the Gateway vServer, consider changing the Portal Theme to RfWebUI. This changes the default portal page to look identical to StoreFront. RfWebUI requires StoreFront to be 3.6 or newer.
  14. To bind to a AAA Group, go to NetScaler Gateway > User Administration > AAA Groups.
  15. Add a group with the same name (case sensitive) as the Active Directory group name. This assumes your LDAP policies/server are configured for group extraction (Group Attribute, and Sub Attribute).
  16. Edit the AAA Group.
  17. On the right, in the Advanced Settings column, add the Policies section.
  18. Click the plus icon to bind one or more Session Policies.
  19. If you want these Session Policies to override the Session Policies bound to the NetScaler Gateway Virtual Server, then make sure the Session Policies bound to the AAA Group have lower priority numbers. See CTX214588 Understanding Session Policy Priority on Different Bind Points.


NetScaler Gateway Plug-in Installation

Here is what the user sees when launching the VPN session for the first time. This assumes the user is an administrator of the local machine.


And then the default portal page is displayed. If using the RfWebUI theme, it might prompt you to install Receiver.

Only administrators can install the NetScaler Gateway Plug-in. You can download the Gateway plug-in from the NetScaler appliance at /var/netscaler/gui/vpns/scripts/vista and push it to corporate-managed machines. Or you can download VPN clients from Citrix.com. The VPN client version must match the NetScaler firmware version.

While a VPN tunnel is established, you can open the Gateway Plug-in to see status. If the Gateway Plug-in is merged with Receiver, right-click Receiver, click Advanced Preferences, click NetScaler Gateway Settings and click Open.

Or, right-click the Gateway Plug-in icon, and click Open.

The hamburger menu on the left lets you see more info about the VPN tunnel.

If the Gateway VPN session isn’t established, you can open the Gateway plug-in, and login. No browser needed.

The Configuration page lets you enable Logging. Then the Logging page lets you collect the logs. See Citrix CTX138155 How to Collect Client VPN Logs for NetScaler Gateway.  💡

VPN Client (NetScaler Gateway Plug-in) Session Profile Settings

  1. By default, if Receiver and NetScaler Gateway Plug-in are installed on the same machine, then the icons are merged. To see the NetScaler Gateway Plug-in Settings, you right-click Receiver, open Advanced Preferences, and then click NetScaler Gateway Settings. This makes it difficult to log off.

  2. You can configure the Session Policy/Profile to prevent the NetScaler Gateway Plug-in from merging with Receiver. Edit your VPN Session Policy/Profile. On the Client Experience tab, scroll down, and check the box next to Advanced Settings.
  3. Check the box next to Show VPN Plugin-in icon with Receiver. This causes the two icons to be displayed separately thus making it easier to access the NetScaler Gateway Plug-in settings, including Logoff.


  4. When the user logs off of VPN, a Cleanup page is displayed. This can be enabled or disabled in a Session Profile on the Client Experience tab.

  5. The cleanup options can be forced in a Session Profile on the Client Experience tab, under Advanced Settings > Client Cleanup.
  6. Whenever NetScaler firmware is upgraded, all users will be prompted to upgrade their VPN clients. You can edit a Session Policy/Profile, and use the Upgrade drop-downs to disable the automatic upgrade.
  7. The Plugin Upgrade settings are also configurable in the Gateway vServer, in the Basic Settings section.

Authorization Policies

If your Session Profile has Security tab > Default Authorization set to Deny (recommended), then create Authorization Policies to allow access across the tunnel.

  1. On the left, under NetScaler Gateway, expand Policies, and click Authorization.
  2. On the right, click Add.
  3. Name the Authorization Policy.
  4. Select Allow or Deny.
  5. NetScaler Gateway requires you to Switch to Classic Syntax. The other syntax option is for AAA.
  6. Enter an expression. Use the Expression Editor link to build an expression. You can specify destination IP subnets, destination port numbers, etc.
  7. Click Create when done.
  8. Authorization Policies are usually bound to AAA groups. This allows different groups to have different access across the tunnel.
  9. On the right, in the Advanced Settings column, add the Authorization Policies section.
  10. Then click where it says No Authorization Policy to bind policies.

Intranet Applications

If you enabled Split Tunnel, then you’ll need to create Intranet Applications to specify which traffic goes through the tunnel.

  1. On the left, under NetScaler Gateway, expand Resources, and click Intranet Applications.
  2. On the right, click Add.
  3. Enter a name for the Internal subnet.
  4. Change the Interception Mode to TRANSPARENT.
  5. Enter an IP subnet. Only packets destined for this network go across the tunnel.
  6. Then click Create.
  7. Create additional Intranet applications for each internal subnet.
  8. Intranet Applications are usually bound to the Gateway Virtual Server, but you can also bind them to AAA Groups.
  9. On the right, in the Advanced Settings column, add the Intranet Applications section.
  10. On the left, click No Intranet Application to bind Intranet Applications.

DNS Suffix

Specify a DNS Suffix for Split DNS to function with single label DNS names.

  1. On the left, under NetScaler Gateway, expand Resources, and click DNS Suffix.
  2. On the right, click Add.
  3. Enter the DNS Suffix, and click Create. You can add multiple suffixes.

Bookmarks

Bookmarks are the links that are displayed in the default portal interface. They can point to websites, or RDP addresses.

  1. Under NetScaler Gateway, expand Resources, and click Bookmarks.
  2. On the right, click Add.
  3. Give the bookmark a name and display text.
  4. Enter a website or RDP address.
  5. The other fields are for Single Sign-on through Unified Gateway. Click Create.
  6. Bookmarks (aka Published Applications > Url) are usually bound to AAA groups so different groups can have different bookmarks. But it’s also possible to bind Bookmarks to NetScaler Gateway Virtual Servers.
  7. If NetScaler Gateway Virtual Server, add the Published Applications section to bind Bookmarks (Url).
  8. For AAA Group, it’s the Bookmarks section.
  9. On the left, find the Published Applications section and click No Url to bind Bookmarks.

VPN Client IP Pools (Intranet IPs)

By default, NetScaler Gateway VPN clients use NetScaler SNIP as their source IP when communicating with internal resources. To support IP Phones or endpoint management, you must instead assign IP addresses to VPN clients.

Any IP pool you add to NetScaler must be reachable from the internal network. Configure a static route on the upstream router. The reply traffic should be routed through a NetScaler SNIP. Or the NetScaler can participate in OSPF.

When a client is assigned a client IP, this IP address persists across multiple sessions until the appliance reboots, or until the appliance runs out of IPs in the pool.

  1. Edit a NetScaler Gateway Virtual Server or a AAA group.
  2. On the right, in the Advanced Settings section, click the plus icon next to Intranet IP Addresses.
  3. On the left, click where it says No Intranet IP.
  4. Enter a subnet and netmask. Click Bind.
  5. In a Session Policy/Profile, on the Network Configuration tab, check the box next to Advanced Settings.
  6. Use the Intranet IP drop-down to configure the behavior when there are more VPN clients than available IPs in the address pool.
  7. If you set it to NOSPILLOVER, then users can only have one VPN session, as described in CTX218066 How to Limit One Session Per User on NetScaler Gateway?.  💡


  8. To see the Client IP address, on the client side, after the tunnel is established, right-click the NetScaler Gateway Plug-in, and click Open.
  9. See the Internal network address.
  10. To see the client IP on the NetScaler, go to NetScaler Gateway, and on the right is Active user sessions.
  11. Select one of the views, and click Continue.
  12. The right column contains the Intranet IP.

StoreFront in Gateway X1 Portal

If you enabled the RfWebUI theme, then no StoreFront configuration is necessary.

But if you want to embed StoreFront in the other Gateway themes (X1, Default, Green Bubble), then follow these instructions.

  1. On StoreFront, edit the file C:\Inetpub\wwwroot\Citrix\StoreWeb\web.config.
  2. On the bottom, there are three sections containing X-Frame-Options. Change all three of them from deny to allow.
  3. Also change frame-ancestors from none to self.
  4. In NetScaler, go to NetScaler Gateway > Global Settings and click Configure Domains for Clientless Access.
  5. Change the selection to Allow Domains, enter your StoreFront FQDN and click the plus icon.
  6. Click OK.
  7. In a Session Policy/Profile, on the Client Experience tab, make sure Single Sign-on to Web Applications is enabled.
  8. On the Published Applications tab, configure the Web Interface Address to point to the StoreFront Receiver for Web page.
  9. Configure the Single Sign-on domain to match what’s configured in StoreFront.
  10. The Applications page of the 3-page portal (e.g. X1 theme) should automatically show the StoreFront published icons.

Quarantine Group

NetScaler Gateway can be configured so that if Endpoint Analysis scans fail, then the user is placed into a Quarantine Group. You can bind session policies, authorization policies, etc. to this quarantine group. Policies bound to other AAA groups are ignored.

  1. Go to NetScaler Gateway > User Administration > AAA Groups.
  2. Add a new local group for your Quarantined Users. This group is local, and does not need to exist in Active Directory.
  3. Create a new Session Profile.
  4. On the Security tab, check the box next to Advanced Settings.
  5. Check the box to the right of Client Security Check String.
  6. Use the Editor links to add an Endpoint Analysis expression.
  7. Just below the Client Security Check String, select the previously created Quarantine Group.
  8. Click Create when done.
  9. Create a Session Policy and select the Session Profile you just created.
  10. Enter ns_true as the expression. Then click Create.
  11. Edit your Gateway Virtual Server and bind the new session policy.
  12. Bind session policies, authorization policies, etc. to your quarantine AAA group. These policies typically limit access to the internal network so users can remediate. Or, it might simply display a webpage telling users how to become compliant.
  13. To troubleshoot Quarantine policies, use the command nsconmsg –d current –g pol_hits.
  14. Another option is to use the session policy bound to the Quarantine Group for SmartAccess configuration.
  15. Gateway Insight shows users that failed EPA scans and their quarantine status.

Related Pages

Citrix Federated Authentication Service (SAML) 2411

Last Modified: Dec 4, 2024 @ 2:28 am

1,097 Comments

Navigation

This article applies to Federated Authentication Service (FAS) versions 2411, 2402 LTSR CU1, 2203 LTSR CU5, 1912 LTSR CU9, and all other versions 7.9 and newer.

Change Log

Overview

Citrix Federated Authentication Service (FAS) enables users to log in to Citrix Gateway and Citrix StoreFront using SAML authentication.

With SAML, Citrix Gateway and StoreFront do not have access to the user’s password and thus cannot perform single sign-on to the VDA. FAS works around this limitation by using issuing certificates that can be used to logon to the VDA.

  • StoreFront asks Citrix Federated Authentication Service (FAS) to use a Microsoft Certificate Authority to issue Smart Card certificates on behalf of users.
  • The certificates are stored on the FAS server.
  • The VDA requests the user’s certificate from FAS so it can complete the VDA Windows logon process.

FAS can be used for any authentication scenario where the user’s password is not provided.

Requirements:

  • Microsoft Certification Authority (CA) in Enterprise mode.
    • When configuring FAS, you tell it what CA server to use.
    • You can build a new CA server just for FAS.
    • You can install CA on the FAS server.
  • Domain Controllers must have Domain Controller certificates. See CTX218941 FAS – Request not supported.
    • The certificates on the Domain Controllers must support smart card authentication. Certificates created using the Microsoft CA certificate template named Domain Controller Authentication supports smart cards. Manually created Domain Controller certificates might not work. See CTX270737 for the Domain Controller certificate requirements.

  • Citrix Virtual Apps and Desktops or XenApp/XenDesktop 7.9 or newer
  • StoreFront 3.6 or newer
  • Citrix Gateway.
    • StoreFront 3.9 and newer also support SAML authentication natively without Citrix ADC.
  • SAML in an nFactor (Authentication Virtual Server) configuration works in both browsers and Workspace app.
  • For multiple domains, see Deployment Guide: Multi-Domain FAS Architecture at Citrix Tech Zone.

Configuration overview:

  1. Build one or more FAS servers.
    • For security reasons, FAS should be its own server and not installed on a Delivery Controller.
  2. Upload Certificate Templates to Active Directory and configure a CA server to issue certificates using the new templates.
    • Enterprise Admin permissions are needed to upload the Certificate Templates.
    • One of the Certificate Templates is for Smart Card logon to Citrix VDA.
    • The other two Certificate Templates are to authorize FAS as a certificate registration authority.
    • The registration authority certificate does not renew automatically so be prepared to renew it manually every two years. See Renew registration authority certificates at Citrix Docs.
  3. Install the Citrix FAS group policy .admx template into PolicyDefinitions.
  4. Create a group policy object (GPO) and configure the GPO with the addresses of the FAS servers.
    • The GPO must apply to FAS servers, StoreFront servers, and every VDA. It does not need to apply to Delivery Controllers, but there’s no harm in applying it to the Delivery Controllers.
  5. Authorize FAS to request certificates from a Microsoft CA server.
  6. Configure FAS Rules to permit StoreFront servers to request FAS to generate certificates for users and permit VDA machines to retrieve the certificates from FAS.
  7. Configure StoreFront to use FAS for VDA single sign-on.

Links:

From Citrix CTX225721 Federated Authentication Service High Availability and Scalability: you can build multiple FAS servers. Enter all FAS server FQDNs in the Group Policy. StoreFront will then use a hashing algorithm on the username to select a FAS server.

  1. If you have less than 10K users, one FAS server with 4 vCPUs (2.5Ghz) should be sufficient.
  2. You will require a minimum of one FAS server (with 8 vCPUs) per 25,000 users if all users expect to be able to logon under cold start conditions (no keys or certificates cached) within 60-90 minutes.
  3. A single FAS server can handle greater than 50K users under warm start conditions (keys and certificates pre-cached)
  4. One reserve FAS server for every four FAS servers for “Day 1” cold start (Users get new keys/certificates) & disaster recovery scenarios
  5. Split the FAS Certificate Authority from Certificate Authority that performs other tasks for both security and scalability purposes.

Michael Shuster explains the Group Policy configuration for FAS in multiple datacenters at HowTo: Active-Active Multi-Datacenter Citrix FAS.

Also see the Citrix Federated Authentication Service Scalability whitepaper.

Federated Authentication Service Versions

The most recent Federated Authentication Service Current Release is version 2411.

For LTSR versions of Citrix Virtual Apps and Desktops (CVAD) and StoreFront, install the version of FAS that comes with the CVAD LTSR version.

Install/Upgrade Federated Authentication Service

The service should be installed on a secure, standalone server that does not have any other Citrix components installed. The FAS server stores user authentication keys, and thus security is paramount.

  1. On the Federated Authentication Service server, go to the Citrix Virtual Apps and Desktops, or XenDesktop 7.9, or newer ISO, and run AutoSelect.exe. Or you can download the standalone installer and run that.
  2. In the lower half of the window, click Federated Authentication Service.
  3. In the Licensing Agreement page, select I have read, understand, and accept the terms of the license agreement, and click Next.
  4. In the Core Components page, click Next.
  5. In the Firewall page, click Next.
  6. In the Summary page, click Install.
  7. The installer will probably ask for a restart.

    1. After the reboot, and after logging in again, you might see a Locate ‘Citrix Virtual Apps and Desktops 7’ installation media window. Don’t click anything yet.
    2. Go to the Citrix_Virtual_Apps_and_Desktops_7_2411.iso file and mount it.
    3. Go back to the Locate ‘Citrix Virtual Apps and Desktops 7’ installation media window.
    4. On the left, expand This PC, and click the DVD Drive.
    5. Click Select Folder.
  8. Click Finish.

FAS Group Policy

Configure a Group Policy that instructs StoreFront servers and VDAs on how to locate the FAS servers.

  1. On the Federated Authentication Service server, browse to C:\Program Files\Citrix\Federated Authentication Service\PolicyDefinitions. Copy the files and folder.
  2. Go to \\domain.com\SYSVOL\domain.com\Policies\PolicyDefinitions and paste the files and folder. If PolicyDefinitions doesn’t exist in SYSVOL, then copy them to C:\Windows\PolicyDefinitions instead.
  3. Edit a GPO that applies to all StoreFront servers, all Federated Authentication Service servers, and all VDAs.
  4. Navigate to Computer Configuration > Policies > Administrative Templates > Citrix Components > Authentication.
  5. Edit the setting Federated Authentication Service.
  6. Enable the setting and click Show.
  7. Enter the FQDN of the Federated Authentication Service server. You can add more than one Federated Authentication Service server.
  8. Click OK twice.
  9. On the Federated Authentication Service server, and VDAs, run gpupdate.
  10. On the FAS server, and on VDAs, look in the registry at HKLM\Software\Policies\Citrix\Authentication\UserCredentialService\Addresses. Make sure this key and value exists. The number one cause why FAS doesn’t work is because this key is missing from VDAs. The FAS Address GPO must apply to VDAs too.
  11. If the VDAs and Users are in different domains, see CTX220497 Users from one AD Domain not able to get FAS user certificates from another trusted domain: add the Citrix StoreFront Servers, FAS server and VDA servers to the Windows Authorization Access Group in the users’ domain. Also see Deployment Guide: Multi-Domain FAS Architecture at Citrix Tech Zone.
  13. By default, the VDAs will verify the certificates aren’t revoked by downloading the Certificate Revocation List. You can disable CRL checking by configuring HKEY_Local_Machine\System\CurrentControlSet\Control\LSA\Kerberos\Parameters\UseCachedCRLOnlyAndIgnoreRevocationUnknownErrors (DWORD) = 1 as detailed at CTX217150 Unable to login using the FAS Authentication – Getting Stuck on Please wait for local session manager.
  14. If your VDAs have third party credential providers (e.g., Duo), then it might interfere with FAS Single Sign-on.

FAS 1909+ Configuration

If you prefer to script the FAS configuration, then see Citrix Blog Post Automating the Citrix Federated Authentication Service with PowerShell.

FAS 1909 and newer have a different configuration GUI than FAS 1906 and older.

Here are 1909 and newer GUI configuration instructions:

  1. Log into the FAS server as an Enterprise Administrator that can upload certificate templates to Active Directory.
  2. On the FAS server, from the Start Menu, run Citrix Federated Authentication Service as administrator. Make sure you run it elevated.
  3. In the tab named Initial Setup, in the row named Deploy certificate templates, click Deploy.
  4. Click OK to deploy the templates to Active Directory.
  5. In the row named Set up a certificate authority, click Publish.
  6. Select an Enterprise Certificate Authority that will be issue the FAS certificates and click OK.
  7. In the row named Authorize this service, click Authorize.
  8. Select a CA that will issue this FAS server a Registration Authority certificate. Later, you will need to open the Certificate Authority console on the chosen server. Click OK.
  9. The row named Authorize this service has a new icon indicating it is waiting on the registration authority certificate to be approved.
  10. Open the Certification Authority console and point it to the CA server. In the Pending Requests node, find the certificate request for the FAS server and Issue it.
  11. Back in the FAS Administration Console, on the top right, click Refresh.
  12. The row named Authorize this service should now have a green check mark.
  13. In the row named Create a rule, click Create.
  14. In the Rule name page, leave it set to Create the default rule and click Next.
  15. In the Template page, click Next.
  16. In the Certificate authority page, select the CA that has the issuing templates configured and click Next. You can select more than one CA server.
  17. In the In-session use page, click Next.
  18. In the Access control page, click the link to Manage StoreFront access permissions.
  19. In the Permission for StoreFront Servers page, add your StoreFront servers and give them the permission Assert Identity. Click OK.
  20. Back in the Create Rule wizard, click Next.
  21. In the Restrictions page, you can optionally reduce the VDAs that are authorized to use FAS. Click Next.
  22. In the Summary page, click Create.
  23. The FAS Registration Authority certificate expires in two years. You’ll need to manually renew the FAS Registration Authority certificate before it expires. Put a notification on your calendar. For details, see Renew registration authority certificates at Citrix Docs.
    • In the row named Authorize this service, you can click the link for authorization certificate to see when it expires. Before expiration, use the Reauthorize button on the right of the same row.
  24. Jump ahead to Certificate Templates.

FAS 1906 and older Configuration

If you prefer to script the FAS configuration, then see Citrix Blog Post Automating the Citrix Federated Authentication Service with PowerShell.

Here are GUI configuration instructions for FAS 1906 and older:

  1. Log into the FAS server as a Domain Administrator or Enterprise Administrator that can upload certificate templates to Active Directory.
  2. On the FAS server, from the Start Menu, run Citrix Federated Authentication Service as administrator. Make sure you run it elevated.
  3. The Federated Authentication Service FQDN should already be in the list (from group policy). Click OK.
  4. In Step 1: Deploy certificate templates, click Start.
  5. Click OK to add certificate templates to Active Directory. Sufficient permission is required.
  6. In Step 2: Setup Certificate Authority, click Start.
  7. Select a Certificate Authority to issue the certificates, and click Ok.
  8. In Step 3: Authorize this Service, click Start.

    • Step 3 automatically submits an online request for the Registration Authority certificate to the CA and stores the non-exportable private key in the standard Microsoft Enhanced RSA and AES Cryptographic Provider.
    • Alternatively, you can submit the certificate request manually, and store the private key in TPM or HSM as detailed at Federated Authentication Service private key protection at Citrix Docs. When running New-FasAuthorizationCertificateRequest, the -UseTPM switch is optional.
  9. Select the issuing Certificate Authority, and click OK.

    • Authorize this Service only lets you select one Certificate Authority. If you want to load balance certificate requests against multiple Certificate Authorities, then see Set up multiple CA servers for use in FAS at Citrix Docs. 
      Set-FasCertificateDefinition -Name default_Definition -CertificateAuthorities @("ca1.corp.local\CA1.corp.local", "ca2.corp.local\ca2.corp.local")
  10. Step 3 is now yellow.
  11. On the Microsoft CA server, go to the Certification Authority Console > Pending Requests. Find the pending request, and Issue it.
  12. In a minute or two, Federated Authentication Service will recognize the issued certificate and Step 3 will turn green.
  13. After FAS authorization with the CA, in the FAS Configuration tool, switch to the User Rules tab.
  14. Use the Certificate Authority drop-down to select the issuing Certificate Authority.
  15. Use the Certificate Template drop-down to select the Citrix_SmartcardLogon template.
  16. Click Edit next to List of StoreFront servers that can use this rule.
  17. Remove Domain Computers from the top half, and instead add your StoreFront servers. You could add an Active Directory security group instead of individual StoreFront servers.
  18. On the bottom half, make sure Assert Identity is Allowed. Click OK.
  19. By default, all users and all VDAs are allowed. You can click the other two Edit boxes to change this.
  20. When done, click Apply.
  21. Click OK when you see Rule updated successfully.
  22. The FAS Registration Authority certificate expires in two years. You’ll need to manually renew the FAS Registration Authority certificate before it expires. Put a notification on your calendar. For details, see Renew registration authority certificates at Citrix Docs.
    • To see the expiration date of the authorization certificate, run the following PowerShell command after running add-pssnapin Citrix.Authentication.FederatedAuthenticationService.V1: 
      Get-FasAuthorizationCertificate -FullCertInfo -address myFASServer

Certificate Templates

The deployed FAS Certificate Templates from older versions of FAS have Autoenroll enabled. Newer versions of FAS (e.g., 2203) no longer have Autoenroll enabled.

  1. Open the Certificate Templates console. One option is to open the Certification Authority console, right-click Certificate Templates, and then click Manage.
  2. There should be three templates with names starting with Citrix_. Open the properties on each one.
  3. On the Security tab, highlight each group assigned to the template.
  4. On the bottom half, uncheck the box in the Autoenroll row but leave Enroll checked. Perform this step for every group assigned to this template. Then click OK.
  5. Repeat disabling autoenroll for the other two templates.

The Registration Authority certificate templates are permitted to all Domain Computers. You might want to change that.

  1. Open the Properties of one of the Citrix_RegistrationAuthority certificate templates.
  2. On the Security tab, remove Domain Computers.
  3. Add your FAS servers and enable the Enroll permission.
  4. Repeat for the other Registration Authority certificate.

To further restrict who can be issued certificates, go to your Certificate Authority’s Properties and use the Enrollment Agents tab to restrict enrollment agents.

StoreFront Configuration

Once FAS is enabled on a StoreFront store, it applies to all connections through that store, including password-based authentications. One option is to create a new store just for FAS users.

  1. Check the registry at at HKLM\Software\Policies\Citrix\Authentication\UserCredentialService\Addresses to confirm that the group policy with FAS addresses has been applied to the StoreFront servers.
  2. On the StoreFront 3.6 or newer server, run the following elevated PowerShell command: 
    & "$Env:PROGRAMFILES\Citrix\Receiver StoreFront\Scripts\ImportModules.ps1"
  3. Run the following commands. Adjust the store name as required. 
    $StoreVirtualPath = "/Citrix/Store"
$store = Get-STFStoreService -VirtualPath $StoreVirtualPath
$auth = Get-STFAuthenticationService -StoreService $store
Set-STFClaimsFactoryNames -AuthenticationService $auth -ClaimsFactoryName "FASClaimsFactory"
Set-STFStoreLaunchOptions -StoreService $store -VdaLogonDataProvider "FASLogonDataProvider"
  4. If you have multiple StoreFront servers, Propagate Changes.
  5. In Web Studio (CVAD 2212 and newer), go to Settings and Enable XML Trust.

    • Or on a Citrix Delivery Controller, run the following PowerShell command: 
      Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $true

If you ever need to disable FAS on StoreFront, run the following commands. Adjust the store name as required.

$StoreVirtualPath = "/Citrix/Store"
$store = Get-STFStoreService -VirtualPath $StoreVirtualPath
$auth = Get-STFAuthenticationService -StoreService $store
Set-STFClaimsFactoryNames -AuthenticationService $auth -ClaimsFactoryName "standardClaimsFactory"
Set-STFStoreLaunchOptions -StoreService $store -VdaLogonDataProvider ""

SAML Configuration

SAML Flow

SAML flows like this:

  1. (Optional) User goes to the web application aka Service Provider (e.g. Citrix Gateway).
    • The Service Provider (SP) redirects the user’s browser to the Identity Provider’s (IdP) SAML Single Sign-on (SSO) URL and includes an authentication request in the Redirect. The IdP SSO URL might be different for each Service Provider.
    • The Authentication Request from the Service Provider includes a Service Provider Entity ID. The IdP matches the SP Entity ID with an entry in its database so it knows which SP is making the authentication request. The Entity ID must match on both the SP and the IdP.
    • If the Authentication Request is signed by the Service Provider’s certificate private key, then the IdP will verify the signature using the Service Provider’s certificate public key. In this scenario, the Service Provider’s certificate (without private key) must be loaded into the IdP.
  2. The user authenticates to the IdP, typically using Multi-factor Authentication.
    • If the user was redirected from the SP, then the IdP already knows which SP to authenticate with.
    • If the user went directly to the IdP, then the user typically needs to click an icon representing the web application (Service Provider).
  3. IdP generates a SAML Assertion containing the user’s userPrincipalName or email address.
    • Configure the IdP to include the user’s UPN or email address in the NameID field of the assertion. SAMAccountName won’t work with Citrix FAS.
    • The SAML Assertion also includes the Service Provider’s Entity ID. The ID in the Assertion must match the ID configured on the SP.
    • IdP signs the SAML Assertion using an IdP certificate private key.
    • IdP has a configuration for the SP that includes a SAML Assertion Consumer Service (ACS) URL. IdP redirects the user’s browser to the SP’s ACS URL and POST’s the SAML Assertion.
      • The ACS URL on Citrix Gateway ends in /cgi/samlauth
  4. SP uses the IdP certificate’s public key to verify the signature on the SAML Assertion.
    • The IdP’s certificate (without private key) is installed on the Citrix ADC so it can verify the Assertion’s signature.
  5. SP extracts the user’s userPrincipalName from the Assertion and uses the UPN for Single Sign-on to StoreFront and the rest of the Citrix components.
    • Note that the SP does not have access to the user’s password and thus that’s why we need Citrix FAS to generate certificates for each user.

Configure the SAML IdP

You typically start the configuration on the Identity Provider (IdP). Every IdP has unique instructions. Search Google for your IdP and Citrix ADC and you might find a IdP-specific guide. After IdP configuration, you download the IdP’s certificate and copy the IdP’s SSO URL so you can configure them on Citrix ADC.

Azure AD as SAML IdP

  1. In Azure Portal, go to Azure Active Directory.
  2. On the left, click Enterprise applications.
  3. In the new blade that appears, on the All applications page, on the right, click New application.
  4. In the All Categories view of the gallery, on the top right, click Non-gallery application.
  5. Give the application a descriptive name. Azure AD shows this name in the myapps portal. Click Add.
  6. After the application is created, on the left, in the Manage section, click Single sign-on.
  7. On the right, click the big button for SAML.
  8. In section 1 labelled Basic SAML Configuration, click the pencil icon.
  9. In the Identifier (Entity ID) field, enter an identifier in URI format. Usually it matches the FQDN of the Citrix Gateway and can be entered in https://gateway.corp.com format. You’ll later need to specify the exact same Identifier on the Citrix ADC.
  10. In the Reply URL (Assertion Consumer Service URL) field, enter a URL similar to https://mygateway.company.com/cgi/samlauth. The path must be /cgi/samlauth. The scheme should be https. And the FQDN is your Citrix Gateway’s FQDN.
  11. Click Save. Then you might have to click the x on the top right to make it go away.
  12. In section 2 labelled User Attributes & Claims, notice that it defaults to sending the userprincipalname. You can click the pencil to change the attribute used for the Name identifier value. Whatever value you send will need to match the userPrincipalNames of local Active Directory accounts (aka shadow accounts).


  13. In section 3 labelled SAML Signing Certificate, click the Download link in the Certificate (Base64) line.
  14. Citrix ADC 12.1 and newer support SAML metadata so feel free to copy the App Federation Metadata Url field.
  15. If you are running NetScaler 12.0 or older, then you will need to copy the Login URL field from section 4 labelled Set up gateway5.corp.com
  16. On the left, under Manage, click Users and groups.
  17. Use the normal process to assign Azure AD users and groups to this application. Click Assign.
  18. Jump to the section named Citrix ADC SAML Configuration.

ADFS as SAML IdP

The screenshots in this section use ADFS as an example IdP. Your IdP will be different.

  1. In your SAML IdP, create a Relying Party Trust (aka service provider trust) or new Application.
  2. Since we’re configuring the IdP before we configure Citrix ADC and thus don’t have access to the SP metadata, select the option to Enter data about the relying party manually.
  3. For the Assertion Consumer Service URL (aka relying party service URL), enter the URL to your Citrix Gateway with /cgi/samlauth appended to the end (e.g. https://gateway.corp.com/cgi/samlauth)
  4. Enter a Relying party trust identifier in URI format. You must specify the same identifier (Issuer Name) on the Citrix ADC as detailed in the next section.
  5. Configure the SAML IdP to send email address or User-Principal-name as Name ID. Citrix ADC receives the Name ID and sends it to StoreFront. StoreFront will look in Active Directory for an account with userPrincipalName that matches the Name ID.
  6. Citrix ADC will sign the authentication requests it sends to the IdP. On the Citrix ADC, you will soon configure the Citrix ADC SAML SP signing certificate with private key that signs the authentication requests that are sent to the IdP. In your SAML IdP, import the same Citrix ADC SAML SP signing certificate but without the private key.
  7. Copy the SAML authentication URL (aka Token Issuance URL) from your SAML IdP. You’ll need to enter this same URL on your Citrix ADC later.
  8. Export the IdP Token-signing certificate from your SAML IdP. The IdP could be ADFS, Okta, Ping, etc.

Citrix ADC SAML Configuration

SAML Server/Action

  1. Instructions for Citrix ADC 13.0, Citrix ADC 12.1, NetScaler 12.0, and NetScaler 11.1 are essentially the same.
    • Citrix ADC 12.1 and newer support SAML Metadata while older versions of NetScaler do not support SAML Metadata.
    • NetScaler 11 is very similar, except Certificates are in a different place in the NetScaler menu tree.
  2. Workspace app support – If you bind a SAML Authentication Policy directly to the Gateway Virtual Server (no nFactor/AAA), then Workspace app and Gateway VPN plug-in won’t work. To support SAML with Workspace app and Gateway VPN plug-in, configure nFactor (Authentication Virtual Server with Authentication Profile) instead of directly on the Gateway Virtual Server.
  3. IdP Signing Certificate – On Citrix ADC, if you are not importing IdP metadata, then manually import the IdP SAML token-signing certificate (without private key) under Traffic Management > SSL > Certificates > CA Certificates. Citrix ADC uses this certificate to verify the signature of the SAML assertion from the IdP.
    Note: when you later create the SAML Action on Citrix ADC, there’s a place to add a SAML certificate. Unfortunately, the SAML Action is trying to import the wrong type of certificate since it wants the private key, which you don’t have access to. If you import the certificate here under CA Certificates, then there’s no prompt for private key.


    • SAML IdP certificates are shown in the Unknown Certificates node.
  4. If you want ADC to sign the authentication requests it sends to the IdP, then do the following:
    1. Move up two nodes to Server Certificates and Import or create a SP SAML signing certificate with private key. This can be the same certificate used on Citrix Gateway. Or a more common practice is to create a self-signed certificate.

    2. You’ll also need to import this SAML SP signing certificate (without private key) to your SAML IdP so it can verify the SAML authentication request signature from the Citrix ADC.
  5. Go to Citrix Gateway > Policies > Authentication > SAML. The quickest way to get here is to enter SAML in the search box on top of the menu.
  6. On the right, switch to the tab labelled Servers, and click Add.
  7. In the Name field, give the SAML Action a name that indicates the IdP’s name.
  8. If your Citrix ADC is 12.1 or newer, then get the SAML Metadata URL (or file) from the IdP.

    1. In the SAML Server on Citrix ADC, in the SAML IDP Metadata URL field, paste in the URL. ADC should be able to extract the IdP’s certificate from the Metadata URL.
    2. In the Issuer Name field, enter the ID that the SAML IdP is expecting for the Relying Party.  This Issuer Name must match the name you configured on the IdP’s Relying Party (Service Provider) Trust. Azure AD calls this the Identifier or Entity ID.
    3. Near the bottom, configure a Relay State Rule to prevent session hijack. It should check the Relay State field to make sure it matches the URL that users using to reach the Gateway Virtual Server. Make sure you include the forward slash at the end of the URL. Sample expression below. Pattern set is also possible. See CTX316577 for details. To avoid relay state “does not match” error, make sure users enter the Gateway URL instead of using a bookmark. 💡 
      AAA.LOGIN.RELAYSTATE.EQ("https://gateway5.corp.com/")

    4. Scroll down and click More.
    5. You can optionally check Force Authentication to prevent users from doing SAML authentication using cached credentials. This prompts for MFA every time the user accesses Citrix Gateway.
    6. Scroll down and click Create.
    7. Edit the SAML Server again.
    8. If you uncheck the box next to Import Metadata, you can see the fields that it filled in for you. Unfortunately, other fields must be configured manually as detailed soon.
  9. Configure the SAML Server based on the data provided by your IdP. If you imported Metadata, then some of the fields might already be populated.
    1. For IDP Certificate Name, select the SAML IdP’s certificate that was exported from the SAML IdP and imported to Citrix ADC. Citrix ADC will use this IdP certificate to verify SAML assertions from the IdP.
      Note: the Add button here does not work correctly. Instead, if you need to import the SAML IDP certificate, then do it at the CA Certificates node as detailed earlier in this section.
    2. For Redirect URL, enter the URL to the SAML IdP’s authentication page. Citrix Gateway will redirect users to this URL. For ADFS, enter your ADFS URL appended with /adfs/ls (e.g. https://adfs.corp.com/adfs/ls). For other IdP’s, get the URL from your IdP.
    3. For User Field, enter the name of the SAML Claim from the IdP that contains the value that matches the userPrincipalName of your local Active Directory users (aka shadow accounts). This defaults to the NameID field, but you might have to use a different claim, like emailaddress.
    4. In the Issuer Name field, enter the ID that the SAML IdP is expecting for the Relying Party.  This Issuer Name must match the name you configured on the IdP’s Relying Party (Service Provider) Trust. Azure AD calls this the Identifier or Entity ID.
    5. Near the bottom, configure a Relay State Rule to prevent session hijack. It should check the Relay State field to make sure it matches the URL that users using to reach the Gateway Virtual Server. Make sure you include the forward slash at the end of the URL. Sample expression below. Pattern set is also possible. See CTX316577 for details. 💡
    6. Optionally, for Signing Certificate Name, select the SAML SP certificate (with private key) that Citrix ADC will use to sign authentication requests to the IdP. This same certificate (without private key) must be imported to the IdP, so the IdP can verify the authentication request signature. This field usually isn’t needed by most IdPs.
    7. Scroll down and click More.
    8. Citrix ADC defaults to SHA1. You might have to change the Signature Algorithm and Digest Method to SHA256.
    9. Review the other settings as needed by your IdP. Click Create when done.

SAML Policy – Advanced (nFactor) Method

Workspace app and Gateway Plugin (i.e. VPN plugin) require nFactor (Advanced Authentication Policies) to support SAML authentication.

Licensing – nFactor requires NetScaler ADC Advanced Edition or NetScaler ADC Premium Edition. The newest builds of NetScaler ADC 13 have added nFactor support for NetScaler ADC Standard Edition, but the configuration of an Authentication Virtual Server is not directly accessible from the main menu. If you only have Standard Edition, then do the following to get to the Authentication Virtual Server:

  1. Go to Citrix Gateway > Virtual Servers and edit one.
  2. On the right, add the Authentication Profile section.
  3. On the left, in the Authentication Profile section, click Add to create an Authentication Profile.
  4. In the Authentication Virtual Server row, click Add to create an Authentication Virtual Server.
  5. The rest of the nFactor configuration is similar to what’s detailed below.

If you prefer to configure the older Classic Method, which doesn’t work with Workspace app, then skip to the Classic Method.

Do the following to create an Advanced Authentication Policy, an Authentication Virtual Server, and bind it to the Gateway Virtual Server:

  1. In the left menu, expand Security, expand AAA – Application Traffic, expand Policies, expand Authentication, expand Advanced Policies, and then click Policy.
  2. On the right, click the button labelled Add.

    1. Change the drop-down for Action Type to SAML.
    2. Change the drop-down for Action to the SAML Action you created earlier.
    3. In the box labelled Expression, enter true.
    4. Give the policy a name and click Create.
  3. In the left menu, expand Security, expand AAA – Application Traffic and then click Virtual Servers.
  4. On the right, click the button labelled Add.

    1. Change the drop-down named IP Address Type to Non Addressable and then click OK.
  5. You can optionally bind a Server Certificate. If you don’t bind a certificate, then the AAA vServer will be down but it will still work. It doesn’t matter what certificate you choose. Click Continue when done.
  6. On the left, in the section named Advanced Authentication Policies, click the row that says No Authentication Policy.

    1. Click where it says Click to select.
    2. Click the small circle to the left of the SAML Policy that you created earlier. Then click the blue button labelled Select at the top of the screen.
    3. There’s no need to configure Select Next Factor unless you want to bind an LDAP Policy with Authentication Disabled so you can extract groups from Active Directory and use those groups for Gateway authorization. This configuration procedure is detailed in the next section.
    4. Click the blue button labelled Bind at the bottom of the window.
  7. Click Continue,
  8. At the bottom of the page, click Done to finish creating the AAA vServer.
  9. In the left menu, expand Citrix Gateway and click Virtual Servers.
  10. On the right, edit your existing Gateway Virtual Server.
  11. On the right side of the screen, in the Advanced Settings column, click Authentication Profile.
  12. On the left side of the screen, find the Authentication Profile section and then click the button labelled Add.
  13. Click where it says Click to Select and then select your AAA vServer.
  14. Give the Authentication Profile a name and then click the blue button named Create.
  15. Make sure you click the blue OK button before you click Done. If you don’t click OK then your changes won’t be saved.

Here are some sample CLI commands for this nFactor SAML configuration.

# SAML Actions
# ------------
add authentication samlAction "Azure AD" -samlIdPCertName AzureADSAML -samlSigningCertName WildcardCorpCom -samlRedirectUrl "https://login.microsoftonline.com/815e26a9-4a9b/saml2" -samlIssuerName gateway5.corp.com -Attribute1 emailaddress -logoutURL "https://login.microsoftonline.com/815e26a9/saml2" -logoutBinding REDIRECT -relaystateRule "aaa.LOGIN.RELAYSTATE.EQ(\"https://gateway5.corp.com/\")"

# SAML Authentication Policies
# ----------------------------
add authentication samlPolicy "Azure AD" ns_true "Azure AD"

# Advanced Authentication Policies
# --------------------------------
add authentication Policy "Azure AD Advanced" -rule true -action "Azure AD"

# Authentication Virtual Servers
# ------------------------------
add authentication vserver nFactor-AzureAD-SAML SSL 0.0.0.0
bind authentication vserver nFactor-AzureAD-SAML -policy "Azure AD Advanced" -priority 100 -gotoPriorityExpression NEXT

# Authentication Profiles
# -----------------------
add authentication authnProfile nFactor-AzureAD-SAML -authnVsName nFactor-AzureAD-SAML

# Citrix Gateway Virtual Servers
# ------------------------------
set vpn vserver gateway5.corp.com -authnProfile nFactor-AzureAD-SAML

SAML nFactor LDAP Group Extraction

If you use AAA Groups with Citrix Gateway, then be aware that SAML usually does not provide the user’s group membership. Instead, configure a LDAP Policy to get the user’s groups from Active Directory so the groups can be later used by Citrix Gateway.

If you don’t need LDAP Group Extraction, then skip ahead to the StoreFront section.

Do the following to configure LDAP Group Extraction.

  1. Create a new LDAP Action.
    1. Use the Search in Menu to find LDAP then pick any of the results.
    2. Check the box next to an existing LDAP policy and click Add to copy its configuration. Or create a new one.
    3. Change the name of the LDAP Action.
    4. On the top right, uncheck the box next to Authentication.
    5. Scroll down a bit and in the right side re-enter the Administrator Password. Copying an existing LDAP Action does not copy the Bind password.
    6. Scroll down to the Other Settings section.
    7. On the left, change Server Logon Name Attribute to –<< New >>–.
    8. Enter userPrincipalName. The UPN is extracted from the SAML Assertion.
    9. Scroll down and click Create.
  2. On the left, go to Security > AAA – Application Traffic > Policies > Authentication > Advanced Policies > Policy and click Add to create a new Policy.

    1. Change Action Type to LDAP.
    2. Expression = true.
    3. Click Create.
  3. On the left, go to Security > AAA – Application Traffic > Policies > Authentication > Advanced Policies > Policy Label. On the right, click Add.

    1. Give the Policy Label a name and click Continue. The Login Schema should be LSCHEMA_INT.
    2. Select your LDAP Group Extract policy and then on the bottom click Bind.
    3. Click Done to close the Policy Label.
  4. On the left, go to Security > AAA – Application Traffic > Virtual Servers. On the right, edit your SAML AAA vServer.

    1. Click where it says 1 Authentication Policy.
    2. Right-click the Authentication Policy and then click Edit Binding.
    3. In the Select Next Factor field, click where it says Click to select.
    4. Select your LDAP Group Extract Policy Label and then click Bind.
  5. Skip ahead to the StoreFront section.

Here are some sample CLI commands for this nFactor SAML LDAP Group Extract configuration.

# LDAP Actions
# ------------
add authentication ldapAction LDAP-GroupExtract -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn ctxsvc@corp.local -ldapBindDnPassword ****** -ldapLoginName userPrincipalName -groupAttrName memberOf -subAttributeName cn -secType SSL -authentication DISABLED

# LDAP Policies
# -------------
add authentication ldapPolicy LDAP-Corp ns_true LDAP-Corp

# Authentication Policy Labels
# ----------------------------
add authentication policylabel LDAP-GroupExtract -loginSchema LSCHEMA_INT
bind authentication policylabel LDAP-GroupExtract -policyName LDAP-GroupExtract -priority 100 -gotoPriorityExpression NEXT

# Authentication Virtual Servers
# ------------------------------
bind authentication vserver nFactor-AzureAD-SAML -policy "Azure AD Advanced" -priority 100 -nextFactor LDAP-GroupExtract -gotoPriorityExpression NEXT

Configure StoreFront for SAML Citrix Gateway

  1. In StoreFront 3.6 or newer, in the StoreFront Console, go to Stores, right-click the store, and click Manage Authentication Methods.
  2. Make sure Pass-through from Citrix Gateway is selected.
  3. Click the bottom gear icon on the right, and click Configure Delegated Authentication.
  4. Check the box next to Fully delegate credential validation to Citrix Gateway and click OK twice.
  5. In StoreFront, add a Citrix Gateway object that matches the FQDN of the Citrix Gateway Virtual Server that has SAML enabled.
  6. On the Authentication Settings page, make sure you configure a Callback URL. It won’t work without it.
  7. Then assign (Configure Remote Access Settings) the Gateway to your Store.

  8. Next step: create Active Directory Shadow Accounts

Native SAML on StoreFront without Citrix ADC

StoreFront 3.9 and newer have native support for SAML Authentication without Citrix ADC. Notes:

  • SAML overrides Explicit and Pass-through authentication.
  • SAML in StoreFront without Citrix ADC seems to work in Workspace app and Receiver Self-Service for Windows.

For an example configuration using StoreFront PowerShell commands and SAML metadata, see CTX232042 Configure StoreFront with OKTA.

To configure native SAML in StoreFront 3.9 or newer:

  1. Export the signing certificate from your SAML IdP. The IdP could be ADFS, Okta, Ping Identity, etc.
  2. In StoreFront 3.9 or newer console, right-click a Store, and click Manage Authentication Methods.
  3. Check the box next to SAML Authentication. If you don’t see this option (because you upgraded from an older version), click the Advanced button on the bottom of the window, and install the authentication method.
  4. On the right, click the gear icon for SAML, and click Identity Provider.
  5. Change the SAML Binding to the method your IdP expects.
  6. Enter the IdP token issuance endpoint URL. For example, in ADFS, the path is /adfs/ls.
  7.  Click Import.
  8. Browse to the signing certificate exported from your IdP, and click Open.
  9. Then click OK to close the Identity Provider window.
  10. On the right, in the SAML Authentication row, click the gear icon, and then click Service Provider.
  11. Click the first Browse button.
  12. Give the Signing certificate a name, and save it somewhere.
  13. Click the second Browse button.
  14. Give the Encryption certificate a name, and save it somewhere.
  15. Copy the Service Provider Identifier. Or you can change it to your desired value. Then click OK.
  16. In your IdP (e.g. ADFS), create a Relying Party Trust.
  17. Import the Encryption certificate that you exported from StoreFront.
  18. Enable SAML 2.0.
  19. For the Assertion Consumer Service (ACS) path, enter something similar to https://storefront.corp.com/Citrix/StoreAuth/SamlForms/AssertionConsumerService. The hostname portion of the URL is equivalent to your StoreFront Base URL. /Citrix/StoreAuth matches your Store name with Auth on the end. The rest of the path must be /SamlForms/AssertionConsumerService. You can get this ACS value by looking in the SAML metadata at the bottom of https://<storefront host>/Citrix/StoreAuth/SamlForms/ServiceProvider/Metadata.

  20. For the Relying party trust identifier, enter the identifier you copied from the Service Provider window in StoreFront.
  21. Configure the Claim Rules to send the user’s email address or userPrincipalName as Name ID.
  22. Edit the Relying Party Trust. Import the Signing certificate that you exported from StoreFront.

  23. Create Active Directory Shadow Accounts. Federated users must be userPrincipalName mapped to local Active Directory accounts.
  24. If you point your browser to https://<storefront-host>/Citrix/<storename>Auth/SamlTest, it should perform a SAML Login, and then show you the assertion that was returned from the IdP. See Citrix CTX220639 How to configure SAML Authentication-Test Configuration.
  25. See Citrix CTX220682 Storefront SAML Troubleshooting Guide for event logs, SAML Metadata, Active Directory account mapping, Trust XML, etc.
  26. When you go to your Receiver for Web page, it should automatically redirect you to your IdP. After authentication, it should redirect you back to StoreFront and show you your icons.
  27. ADFS also works in Receiver 4.6 and newer, and Workspace app.
  28. When you logoff, it won’t let you log on again unless you close your browser and reopen it.

  29. To fix this problem, see CTP Sacha Thomet StoreFront – Allow relogin without browser close. Edit the file C:\inetpub\wwwroot\Citrix\StoreWeb\custom\script.js, and add the following line: 
    CTXS.allowReloginWithoutBrowserClose = true

  30. Now when you logoff, you’re given an option to log on again.

Active Directory Shadow Accounts

To login to Windows (Citrix VDA), every user must have an Active Directory account in a domain trusted by the VDA. For Federated Users, you typically need to create shadow accounts for each Federated user in your local Active Directory. These Shadow accounts need a userPrincipalName that matches the SAML attribute (usually email address) provided by the SAML IdP.

If the email address provided by the SAML IdP does not match the UPN suffix for your domain, then do the following:

  1. Open Active Directory Domains and Trust.
  2. Right-click the top left node (not a domain node), and click Properties.
  3. In the UPN Suffixes tab, add a UPN suffix that matches the email suffix provided by the SAML IdP.
  4. When creating a shadow account in your Active Directory, the new UPN suffix is available in the drop-down list. Note that the pre-Windows 2000 logon name can’t conflict with any other user in the domain.
  5. The password for these Shadow accounts can be any random complex password since the Federated users never need the Shadow account’s password.
  6. If the shadow account is already created, edit the account, and on the Account tab, use the drop-down to select the new UPN suffix.
  7. Create a shadow account for every federated user. There are third party Identity Management tools that can automate this. Or get an export from the IdP and use PowerShell scripting to create the acccounts.

Verify FAS

When FAS is enabled on StoreFront, every user that logs into StoreFront (local or remote) causes a user certificate to be created on the FAS server. You can see these user certificates by running the following PowerShell commands:

Add-PSSnapin Citrix.Authentication.FederatedAuthenticationService.V1
Get-FasUserCertificate -address fas01.corp.local

Citrix uses these certificates to logon to the VDA as the user. No password needed.

Session Policies for StoreFront – NetScaler Gateway 11.1

Last Modified: Nov 7, 2020 @ 6:35 am

18 Comments

Navigation

This page details creation of session profiles and session policies for NetScaler Gateway 11.1 where ICA Only is checked.

Partly based on Citrix Knowledgebase Article CTX139963 – How to Configure NetScaler Gateway with StoreFront

Session Profiles/Policies CLI Commands

The CLI commands are shown below:

add vpn sessionAction "Receiver Self-Service" -transparentInterception OFF -defaultAuthorizationAction ALLOW -SSO ON -icaProxy ON -wihome "https://storefront.corp.com" -ntDomain Corp -clientlessVpnMode OFF -storefronturl "https://storefront.corp.com"

add vpn sessionAction "Receiver for Web" -transparentInterception OFF -defaultAuthorizationAction ALLOW -SSO ON -icaProxy ON -wihome "https://storefront.corp.com/Citrix/StoreWeb" -ntDomain Corp -clientlessVpnMode OFF

add vpn sessionPolicy "Receiver Self-Service" "REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver" "Receiver Self-Service"

add vpn sessionPolicy "Receiver for Web" "REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver" "Receiver for Web"

Session Profiles

Or use the GUI to create the policies/profiles:

  1. On the left, expand NetScaler Gateway, expand Policies and click Session.
  2. On the right, switch to the Session Profiles tab, and click Add.
  3. Name the first one ReceiverSelfService or similar. This is for Receiver Self-Service (not in a web browser).
  4. Switch to the Client Experience tab.
  5. On the Client Experience tab, check the Override Global box next to Clientless Access and set it to Allow. Scroll down.
  6. Check the Override Global box next to Plug-in Type and set it to Java.
  7. Check the Override Global box next to Single Sign-on to Web Applications and enable it. Scroll up.
  8. If you need two-factor authentication, the session policy 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.
  9. On the Security tab, check the Override Global box next to Default Authorization Action and set it to Allow.
  10. On the Published Applications tab, check the Override Global box next to ICA Proxy and set it to ON.
  11. Check the Override Global box next to Web Interface Address and enter the load balanced URL to the StoreFront servers. You can use an IP address. Don’t add any path to the end of the URL.
  12. If you only have one domain, then check the Override Global box next to Single Sign-on Domain and enter the name of your Active Directory domain. StoreFront needs to accept this domain name (Configure Trusted Domains).
  13. If you have multiple domains, then leave Single Sign-on Domain field blank, and ensure the LDAP authentication servers have userPrincipalName in the SSO Name Attribute field.
  14. For Account Services Address, enter the Base URL for StoreFront. NetScaler needs to be able to resolve this DNS name.
  15. Click Create.
  16. Click the ellipsis next to the existing session profile and click Add. This copies the settings from the existing profile into the new one.
  17. Change the name of the second Session Profile to ReceiverForWeb or similar.
  18. On the Client Experience tab, Clientless Access should be set to Allow. Scroll down.
  19. Plug-in Type should still be set to Java.
  20. Single Sign-on to Web Applications should be enabled.
  21. If you need two-factor authentication, the session policy for Receiver for Web needs Credential Index set to PRIMARY. Only the Receiver Self-Service policy needs SECONDARY as detailed earlier.
  22. On the Security tab, the Default Authorization Action should still be Allow.
  23. On the Published Applications page, for the Web Interface Address field, add the path to your Receiver for Web site (e.g. /Citrix/StoreWeb).
  24. Everything else should be the same. If you only have one domain, then check the Override Global box next to Single Sign-on Domain and enter the name of your Active Directory domain. If you have multiple domains, then leave this field blank and ensure the LDAP authentication servers have userPrincipalName in the SSO Name Attribute field.
  25. Account Services Address is not needed in this profile but there’s no harm in leaving it.
  26. Click Create.

Session Policies

  1. On the right, switch to the Session Policies tab, and click Add.
  2. Name the Policy ReceiverSelfService or similar.
  3. Change the Request Profile to ReceiverSelfService.
  4. In the Expression box, either type in the following, or use the Expression Editor link to build the following expression: 
    REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver

  5. Then click Create.
  6. Add another policy, and name it ReceiverForWeb or similar.
  7. Change the Action to ReceiverForWeb.
  8. In the Expression box, either type in the following, or use the Expression Editor. It’s the same as the previous expression, except it’s NOTCONTAINS instead of CONTAINS. 
    REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver
  9. Click Create.

Next Step