nFactor Authentication for NetScaler Gateway 11

Last Modified: May 4, 2017 @ 2:18 pm

Navigation

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.

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
    • 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.

In NetScaler 11.0 build 62 and newer, you can configure nFactor on AAA authentication servers.

In NetScaler 11.0 build 66 and newer, you can configure nFactor in the AAA feature and bind it to NetScaler Gateway Virtual Servers. Thus 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):

  • The first factor (Advanced Authentication Policy and Login Schema) is bound directly to a AAA Virtual Server.
  • Next factors are Authentication Policy Labels that are chained to Advanced Authentication Policies in prior factors.
  • Authentication Profile links AAA nFactor with NetScaler Gateway.

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. Enter an Authentication Domain and 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 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. 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.

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. You can easily duplicate and modify these files. You can also download login schemas from support.citrix.com.

After duplicating one of the existing .xml files, you can edit it as desired. You can change the labels. Or you can configure fields 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.

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 editing the file under /nsconfig/loginschema/LoginSchema/.
  7. On the top right, click Select.
  8. Give the Login Schema a name.
  9. 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.
  10. 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.
  11. Later you reference these index values in a Traffic Policy/Profile by using the expression HTTP.REQ.USER.ATTRIBUTE(#).
  12. Click Create.
  13. 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. Make sure Authentication is unchecked.
  2. Make sure the 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. Right-click 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 Done.

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 Security > AAA > Authentication Profile.
  2. On the right, click Add.
  3. Give the Authentication Profile a name.
  4. In the Authentication Host field, it wants a URL to redirect users to your AAA Virtual Server. If you do this configuration from the CLI then this field is optional. But in the GUI it is required. NetScaler Gateway does not need to redirect so it doesn’t matter what you enter here.
  5. In the Authentication Virtual Server field, Click to select.
  6. 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.
  7. Then click Create.
  8. Go to NetScaler Gateway > Virtual Servers.
  9. On the right, edit an existing Gateway Virtual Server.
  10. In the Basic Settings section, click the pencil icon.
  11. Click More.
  12. Use the Authentication Profile drop-down to select the Authentication Profile you just created.
  13. 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.
  14. When you browse to your Gateway, you’ll see the nFactor authentication screens.

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 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. Scroll down.
  6. In the SSO Expression fields, enter an HTTP.REQ.USER.ATTRIBUTE(#) expression that matches the indexes specified in the Login Schema.
  7. Click Create.
  8. On the right, switch to the Traffic Policies tab and click Add.
  9. Give the policy a name.
  10. Select the previously created Traffic Profile.
  11. Enter a classic expression (e.g. ns_true) and click Create.
  12. Edit an existing NetScaler Gateway Virtual Server.

  13. Scroll down to the Policies section and click the plus icon.
  14. Select Traffic > Request and click Continue.
  15. Select the previously created Traffic Policy.

  16. Bind the Traffic Policy.

Sample Configurations

From Citrix Docs: Sample deployments using nFactor authentication:

  • Getting two passwords up-front, pass-through in next factor. Read
  • 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
  • Prefilling user name from certificate. Read
  • Certificate authentication followed by group extraction for 401 enabled traffic management virtual servers. Read
  • Username and 2 passwords with group extraction in third factor.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
  • Domain drop down in first factor, then different policy evaluations based on group.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 -AuthenticationDomain corp.com
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
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
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 than LDAP-SAM policy
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
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
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
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 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

Citrix Federated Authentication Service (SAML) 7.15

Last Modified: Sep 18, 2017 @ 6:55 am

Navigation

This article applies to Federated Authentication Services versions 7.15, 7.14, 7.13, 7.12, 7.11, and 7.9.

Overview

Citrix Federated Authentication Service enables users to login to NetScaler Gateway and StoreFront using SAML authentication.

Citrix Federated Authentication Service uses Microsoft Certificate Authority to issue certificates on behalf of users. These certificates are used for the StoreFront and Virtual Delivery Agent logon process.

Requirements:

  • Microsoft Certificate Authority in Enterprise mode
  • XenApp/XenDesktop 7.9 or newer
  • StoreFront 3.6 or newer
  • NetScaler Gateway. Note: StoreFront 3.9 and newer also supports SAML authentication natively without NetScaler.
  • Receiver for Web only.
  • Receiver Self-Service for Windows 4.6 and newer supports SAML auth when connecting to StoreFront native SAML without NetScaler.

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.

Also see the Citrix Federated Authentication Service Scalability whitepaper.  💡

Install 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 XenDesktop 7.9 or newer ISO, and run AutoSelect.exe.
  2. In XenDesktop 7.13 and newer, in the lower half of the window, click Federated Authentication Service.
  3. Or in XenDesktop 7.9 through 7.12, on the bottom right, click Federated Authentication Service.
  4. In the Licensing Agreement page, select I have read, understand, and accept the terms of the license agreement, and click Next.
  5. In the Core Components page, click Next.
  6. In the Firewall page, click Next.
  7. In the Summary page, click Install.
  8. In the Finish Installation page, click Finish.

FAS Group Policy

  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 from domain B to the Windows Authorization Access Group on Domain B.
  12. By default, the VDAs will verify the certificates aren’t revoked by downloading the Certificate Revocation List. You can disable this 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.

FAS Configuration

  1. From the Start Menu, run Citrix Federated Authentication Service as administrator. Make sure you run it elevated.
  2. The Federated Authentication Service FQDN should already be in the list (from group policy). Click OK.
  3. In Step 1: Deploy certificate templates, click Start.
  4. Click OK to add certificate templates to Active Directory. Sufficient permission is required.
  5. In Step 2: Setup Certificate Authority, click Start.
  6. Select a Certificate Authority to issue the certificates, and click Ok.
  7. In Step 3: Authorize this Service, click Start.
  8. 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.
  10. Step 3 is now yellow.
  11. Go to the Certificate 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. If it doesn’t turn green, then there might be a private hotfix. See David Lloyd at Citrix Discussions.
  13. Another user at XenDesktop 7.9 FAS at Citrix Discussions had to bump up the Validity Period of the Citrix_RegistrationAuthority_ManualAuthorization template to 2 days before it would authorize.
  14. After authorization, switch to the User Rules tab.
  15. Use the Certificate Authority drop-down to select the issuing Certificate Authority.
  16. Use the Certificate Template drop-down to select the Citrix_SmartcardLogon template.
  17. Click Edit next to List of StoreFront servers that can use this rule.
  18. 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.
  19. On the bottom half, make sure Assert Identity is Allowed. Click OK.
  20. By default, all users and all VDAs are allowed. You can click the other two Edit boxes to change this.
  21. When done, click Apply.
  22. Click OK when Rule updated successfully.
  23. 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

  1. On the StoreFront 3.6 or newer server, run the following elevated PowerShell command:
    & "$Env:PROGRAMFILES\Citrix\Receiver StoreFront\Scripts\ImportModules.ps1"
  2. 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"
  3. If you have multiple StoreFront servers, Propagate Changes.
  4. On a XenDesktop Delivery Controller, run the following commands:
    asnp citrix.*
    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 ""

NetScaler Gateway Config

SAML on NetScaler Gateway 11.1

If NetScaler 11.0, see SAML on NetScaler Gateway 11.0.

ADFS-specific Links:

Configure the SAML iDP:

  1. In your SAML iDP, create a Relying Party Trust (aka service provider trust).
  2. NetScaler doesn’t have a SAML metadata service, but you can create a metadata file manually by following the instructions at Citrix CTX133919 How to Configure NetScaler SAML to Work with Microsoft AD FS 2.0 IDP.
  3. Otherwise, select the option to enter relying party data manually.
  4. For the Assertion Consumer Service URL (aka relying party service URL), enter the URL to your NetScaler Gateway with /cgi/samlauth appended to the end (e.g. https://gateway.corp.com/cgi/samlauth)
  5. Enter a Relying party trust identifier. You must specify the same identifier (Issuer Name) on the NetScaler as detailed soon.
  6. Configure the SAML iDP to send email address or User-Principal-name as Name ID. NetScaler 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.
  7. NetScaler will sign the authentication requests it sends to the iDP. On the NetScaler, you will soon configure the NetScaler signing certificate with private key that signs the requests. In your SAML iDP, import the same NetScaler signing certificate but without private key.
  8. Copy the SAML authentication URL (aka Token Issuance URL) from your SAML iDP. You’ll need to enter this same URL on your NetScaler later.
  9. Export the iDP Token-signing certificate from your SAML iDP. The iDP could be ADFS, Okta, Ping, etc.

Configure the NetScaler:

  1. On NetScaler, import the iDP SAML token-signing certificate (without private key) under Traffic Management > SSL > Certificates > CA Certificates. NetScaler uses this certificate to verify the signature of the SAML assertion from the iDP.

  2. Import or create a NetScaler SAML signing certificate with private key for signing of SAML authentication requests to the iDP. This can be the same certificate used on NetScaler Gateway. Or a more common practice is to create a self-signed certificate.
  3. You’ll also need to import this NetScaler SAML signing certificate (without private key) to your SAML iDP so it can verify the SAML authentication request signature from the NetScaler.
  4. Go to NetScaler Gateway > Policies > Authentication > SAML.
  5. On the right, switch to the Servers tab, and click Add.
  6. Enter the information for authenticating with your SAML iDP. This configuration will vary depending on your SAML iDP.
  7. For iDP Certificate Name, select the SAML iDP’s certificate that was exported from the SAML iDP and imported to NetScaler. NetScaler will use this iDP certificate to verify SAML assertions from the iDP.
  8. For Redirect URL, enter the URL to the SAML iDP’s authentication page. NetScaler 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 iDPs, get the URL from your iDP.
  9. For Signing Certificate Name, select the NetScaler certificate (with private key) that NetScaler 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.
  10. Enter an Issuer Name 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.
  11. Click More.
  12. NetScaler defaults to SHA1. You might have to change the Signature Algorithm and Digest Method to SHA256.
  13. Review the other settings as needed by your iDP. Click Create when done.
  14. On the right, switch to the Policies tab, and click Add.
  15. Give the policy a name, select the SAML Server, and enter ns_true for the expression. Click Create.
  16. If you haven’t created your Session Polices yet, then see http://www.carlstalhood.com/session-policies-for-storefront-netscaler-11-1/.
  17. Edit your Session Policy/Profile. On the Published Applications tab, make sure Single Sign-on Domain is not configured.
  18. If you haven’t created your Gateway Virtual Server yet, then see http://www.carlstalhood.com/netscaler-gateway-11-1-virtual-server/.
  19. Edit your Gateway Virtual Server. Go to the Basic Authentication section, and add a policy.
  20. Bind the SAML policy. This is the only authentication policy you need. You can remove all other authentication policies.

  21. Next step: configure StoreFront for SAML NetScaler Gateway.

SAML on NetScaler Gateway 11.0

If NetScaler 11.1, see SAML on NetScaler Gateway 11.1.

ADFS-specific Links:

Configure the SAML iDP:

  1. In your SAML iDP, create a Relying Party Trust (aka service provider trust).
  2. NetScaler doesn’t have a SAML metadata service, but you can create a metadata file manually by following the instructions at Citrix CTX133919 How to Configure NetScaler SAML to Work with Microsoft AD FS 2.0 IDP.
  3. Otherwise, select the option to enter relying party data manually.
  4. For the Assertion Consumer Service URL (aka relying party service URL), enter the URL to your NetScaler Gateway with /cgi/samlauth appended to the end (e.g. https://gateway.corp.com/cgi/samlauth)
  5. Enter a Relying party trust identifier. You must specify the same identifier (Issuer Name) on the NetScaler as detailed soon.
  6. Configure the SAML iDP to send email address or User-Principal-name as Name ID. NetScaler 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.
  7. NetScaler will sign the authentication requests it sends to the iDP. On the NetScaler, you will soon configure the NetScaler signing certificate with private key that signs the requests. In your SAML iDP, import the same NetScaler signing certificate but without private key.
  8. Copy the SAML authentication URL (aka Token Issuance URL) from your SAML iDP. You’ll need to enter this same URL on your NetScaler later.
  9. Export the signing certificate from your SAML iDP. The iDP could be ADFS, Okta, Ping, etc.

Configure the NetScaler:

  1. On NetScaler, import the iDP SAML signing certificate (without private key). NetScaler uses this certificate to verify SAML assertions from the iDP.

  2. Import or create a NetScaler SAML signing certificate with private key for signing of SAML authentication requests to the iDP. This can be the same certificate used on NetScaler Gateway. Or a more common practice is to create a self-signed certificate.
  3. You’ll also need to import this NetScaler SAML signing certificate (without private key) to your SAML iDP so it can verify the SAML authentication request signature from the NetScaler.
  4. Go to NetScaler Gateway > Policies > Authentication > SAML > Servers, and click Add.
  5. Enter the information for authenticating with SAML. This configuration will vary depending on your SAML iDP.
  6. For iDP Certificate Name, select the SAML iDP’s certificate that was exported from the SAML iDP and imported to NetScaler. NetScaler will use this iDP certificate to verify SAML assertions from the iDP.
  7. For Redirect URL, enter the URL to the SAML iDP’s authentication page. NetScaler 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 iDPs, get the URL from your iDP.
  8. For Signing Certificate Name, select the NetScaler certificate (with private key) that NetScaler 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.
  9. Enter an Issuer Name 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.
  10. Click More.
  11. NetScaler defaults to SHA1. You might have to change the Signature Algorithm and Digest Method to SHA256.
  12. Review the other settings as needed by your iDP. Click Create when done.
  13. On the right, switch to the Policies tab and click Add.
  14. Give the policy a name, select the SAML Server, and enter ns_true for the expression. Click Create.
  15. If you haven’t created your Session Polices yet, then see http://www.carlstalhood.com/session-policies-for-storefront-netscaler-11/.
  16. Edit your Session Policy/Profile. On the Published Applications tab, make sure Single Sign-on Domain is not configured.
  17. If you haven’t created your Gateway Virtual Server yet, then see http://www.carlstalhood.com/netscaler-gateway-11-virtual-server/.
  18. Edit your Gateway Virtual Server. Go to the Authentication section and add a policy.
  19. Bind the SAML policy. This is the only authentication policy you need. You can remove all other authentication policies.
  20. Next step: configure StoreFront for SAML NetScaler Gateway.

StoreFront Config for SAML NetScaler Gateway

  1. In StoreFront 3.6 or newer, right-click the store, and click Manage Authentication Methods.
  2. Make sure Pass-through from NetScaler Gateway is selected.
  3. Click the gear icon on the right, and click Configure Delegated Authentication.
  4. Check the box next to Fully delegate credential validation to NetScaler Gateway, and click OK twice.
  5. In StoreFront, add a NetScaler Gateway object that matches the NetScaler 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

SAML on StoreFront without NetScaler

New in StoreFront 3.9 is native support for SAML Authentication without NetScaler.

Notes:

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

To configure 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), 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. Currently, the only supported configuration is ADFS with SAML to StoreFront without NetScaler.
  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.

NetScaler Gateway 11 – SSL VPN

Last Modified: May 4, 2017 @ 2:21 pm

Navigation

💡 = Recently Updated

Overview

NetScaler Gateway supports five different connection methods:

  • ICA Proxy to XenApp/XenDesktop – client is built into Citrix Receiver
  • SSL VPN – requires 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

If Endpoint Analysis is configured, then an Endpoint Analysis plug-in is downloaded to the Windows or Mac client.

Users use SSL to connect to NetScaler Gateway Virtual Servers.

  • NetScaler Gateway prompts the user for authentication.
  • Once the user is authenticated, NetScaler Gateway uses Session Policies to determine what happens next.

You can configure NetScaler Gateway Session Policies 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 X1 theme:

Enable SSL VPN in a Session Policy as detailed later. Then configure additional NetScaler Gateway objects including the following:

  • DNS Servers and Suffix – enable DNS resolution across the VPN tunnel
  • NetScaler Gateway Universal Licenses – all VPN users must be licensed.
  • Intranet IP addresses – give IP addresses to VPN clients. If no client IP, then VPN clients use NetScaler SNIP to communicate with internal resources. Requires routing changes on internal network.
  • Intranet Applications – if split tunnel is enabled, configure this object to dictate what traffic goes across the tunnel and which traffic stays local.
  • Authorization Policies – if default authorization is DENY, use Authorization Policies to dictate what resources can be accessed across the NetScaler Gateway connection. These Authorization Policies apply to all NetScaler Gateway connections, not just VPN.
  • Bookmarks – displayed on the built-in NetScaler Gateway portal page. Users click bookmarks to access resources across the VPN tunnel or clientless access (rewrite).
  • Endpoint Analysis Scans – block endpoints that fail security requirements. Configured in Session Policies or Preauthentication Policies.
  • Traffic Policies – Single Sign-on to internal web applications
  • AAA Groups – bind Session Policies, Authorization Policies, Intranet Applications, Intranet IPs, Bookmarks, and Traffic Policies to one or more Active Directory groups. Allows different Active Directory groups to have different NetScaler Gateway configurations.

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

You can create multiple Session Policy/Profiles, each with different settings. Then you can bind these Session Policies to different AAA groups or different NetScaler Gateway Virtual Servers. 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.

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.

Do the following to enable SSL VPN. First create the Session Profile. Then create a Session Policy.

  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 and check the box next to Advanced Settings.
  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. Configure the behavior when there are more VPN clients than available IPs in the address pool. This only applies if you are configuring Intranet IPs.
  8. There are also a couple timeouts lower on the page.
  9. Switch to the Client Experience tab. This tab contains most of the NetScaler Gateway VPN settings.
  10. Override Plug-in Type and set it to Windows/Mac OS X.
  11. Whenever NetScaler firmware is upgraded, all users will be prompted to upgrade their VPN clients. You can use the Upgrade drop-downs to disable the automatic upgrade.
  12. 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.

  13. You can configure the Session Policy/Profile to prevent NetScaler Gateway Plug-in from merging with Receiver. On the Client Experience tab, scroll down and check the box next to Advanced Settings.
  14. 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.

  15. 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).
  16. On the Client Experience tab, there are timers that can be configured. Global Settings contains default timers so you might want 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 disconnects the session if there is no network activity for this duration.
    3. In addition to these two timers on the Client Experience tab, on the Network Configuration tab, under Advanced Settings, there’s a Forced Timeout setting.
  17. By default, once the VPN tunnel is established, a 3-page interface appears containing bookmarks, file shares, and StoreFront. An example of the three-page interface in the X1 theme is shown below.
  18. On the Client Experience tab, the Home Page field lets you override the 3-page interface and instead display a different webpage (e.g. Intranet or StoreFront). This homepage is displayed after the VPN tunnel is established (or immediately if connecting using Clientless Access).
  19. On the Client Experience tab, there are more settings that control the behavior of the NetScaler Gateway plug-in. Hover your mouse over the question marks to see what they do.
  20. Additional VPN settings can be found by clicking Advanced Settings near the bottom of the Client Experience tab.
  21. 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.
  22. 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, the VPN will launch automatically
  23. 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.
  24. An example of Client Choices is shown below:
  25. The Client Experience > Advanced Settings section has additional tabs for controlling the NetScaler Gateway Plug-in. A commonly configured tab is Proxy so you can enable a proxy server for VPN users.
  26. Back in the main Session Profile, switch to the Security tab.
  27. 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.
  28. On the Published Applications tab, set ICA Proxy to Off. This ensures VPN is used instead of ICA Proxy.
  29. Configure the Web Interface Address to embed StoreFront into the 3-pane default portal page. Note: additional iFrame configuration is required on the StoreFront side as detailed below.
  30. From Michael Krasnove: if you configured the Session Policy to direct users to StoreFront, 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;
    };
  31. Click Create when you’re done creating the Session Profile.

Create Session Policy

  1. In the right pane, switch to the Session Policies tab and click Add.
  2. Give the policy a descriptive name.
  3. Change the Action to the VPN Profile you just created.
  4. Add a policy expression. You can enter ns_true, which applies to all connections.
  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 objects can be bound to NetScaler Gateway Virtual Server, AAA Group, or both. This section details Session Policies, but the other NetScaler Gateway objects (e.g. Authorization Policies) can be bound using similar instructions.

  1. Bind the new session policy to a NetScaler Gateway Virtual Server or a AAA group. If you bind it only to a AAA group, then only members of that Active Directory group will evaluate the expression.
  2. To bind to a NetScaler Gateway Virtual Server, edit a NetScaler Gateway Virtual Server (or create a new one), scroll down to the Policies section and click the Plus icon.
  3. In the Choose Type page, select Session, Request and click Continue.
  4. Select one or more session policies. This is where you specify a priority.
  5. To bind to a AAA Group, go to NetScaler Gateway > User Administration > AAA Groups.
  6. 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.
  7. Edit the AAA Group.
  8. On the right, in the Advanced Settings column, add the Policies section.
  9. Click the plus icon to bind one or more Session Policies.
  10. 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.

NetScaler Gateway Plug-in Installation

Here is what the user sees when launching the VPN session for the first time.


And then the 3-pane interface is displayed.

Only administrators can install the NetScaler Gateway Plug-in. You can download the Gateway plug-in from the NetScaler 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.

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 3-pane interface. They can point to file shares or websites.

  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 file share. For file shares you can use %username%.
  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.
  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. To see the Client IP address, on the client side, right-click the NetScaler Gateway Plug-in and click Configure NetScaler Gateway.
  6. Switch to the Profile tab to see the Client IP address.
  7. To see the client IP on the NetScaler, go to NetScaler Gateway and on the right is Active user sessions.
  8. Select one of the views and click Continue.
  9. The right column contains the Intranet IP.

StoreFront in Gateway Portal

  1. If you want to enable StoreFront to integrate with NetScaler Gateway’s default portal, edit the file C:\Inetpub\wwwroot\Citrix\StoreWeb\web.config.
  2. On the bottom, there are three sections containing 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 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 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 (Insight Center 11.0 build 65 and newer) shows users that failed EPA scans and their quarantine status.

Related Pages

SmartAccess / SmartControl – NetScaler 11

Last Modified: Nov 15, 2016 @ 5:44 pm

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

Other than the NetScaler appliance license, 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. Gateway Universal licenses – Both SmartAccess and SmartControl require NetScaler Gateway Universal licenses. NetScaler 11.1 build 49 and newer come with a minimum of 500 Universal licenses so this might no longer be an issue. In 11.1 build 49 and newer, NetScaler Standard Edition comes with 500 licenses, NetScaler Enterprise Edition comes with 1,000 licenses, and NetScaler Platinum Edition comes with unlimited licenses.
  3. On the NetScaler, go to System > Licenses and make sure you have NetScaler Gateway Universal Licenses allocated to the appliance. 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.
  4. After installing licenses, go to NetScaler Gateway > Global Settings.
  5. On the top right, click Change authentication AAA settings.
  6. At the top of the page, change the Maximum Number of Users to match your installed license count. Then click OK. This setting is commonly missed and if not configured it defaults to only 5 concurrent connections.
  7. On a XenApp/XenDesktop Controller, run PowerShell as Administrator.
  8. Run asnp citrix.* to load the snapins.
  9. Run Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $true to enable Trust XML.
  10. In StoreFront Console, go to the NetScaler Gateway node and edit (Change General Settings) the existing Gateway object.
  11. Make sure a Callback URL is configured to 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.
  12. On the NetScaler, go to NetScaler Gateway > Virtual Servers and edit your Gateway Virtual Server.

  13. In the Basic Settings section, click the pencil icon.
  14. Click More.
  15. 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 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 11 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.

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.
  4. You can also use EPA expressions when configuring a Quarantine Group.

Once the 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

NetScaler 11.0 has a new SmartControl feature, where you can configure some of the SmartAccess functionality directly on the appliance. See Configuring SmartControl at docs.citrix.com for detailed instructions.

  1. If you are using a Preauthentication Policy to run an Endpoint Analysis scan, edit the Preauth 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, 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 OK.
  7. Switch to the ICA Action tab and click Add.
  8. Give the Action a name and select the 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 REQ.USER.IS_MEMBER_OF(“MyGroup”) 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.

  • 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.

Related Pages

NetScaler Gateway 11 – RDP Proxy

Last Modified: May 4, 2017 @ 2:33 pm

RDP Proxy

NetScaler 10.5.e and NetScaler 11 support RDP Proxy through NetScaler Gateway. No VPN required. There are two ways of launching RDP sessions through NetScaler Gateway RDP Proxy:

  • Bookmarks on the Clientless Access portal page.
  • After logging in, change the URL in the browser to /rdpproxy/MyRDPServer. MyRDPServer can be IP or DNS.

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.
  • TCP 443 and TCP 3389 opened to the NetScaler Gateway Virtual Server.
  • TCP 3389 opened from the NetScaler SNIP to the RDP Servers.

Do the following to configure RDP Proxy:

  1. Expand NetScaler Gateway, expand Policies, right-click RDP and click Enable Feature.
  2. Click RDP on the left. On the right, switch to the Client Profiles tab and click Add.
  3. Give the Client Profile a name and configure it as desired. Scroll down.
  4. In the RDP Host field, enter the FQDN that resolves to the RDP Proxy listener, which is typically the same FQDN as NetScaler Gateway.
  5. Near the bottom is a Pre Shared Key. Enter a password and click OK. You’ll need this later.
  6. On the right, switch to the Server Profiles tab and click Add.
  7. Give the Server Profile a name.
  8. Enter the IP of the Gateway Virtual Server you’re going to bind this to.
  9. Enter the same Pre Shared Key you configured for the RDP Client Profile. Click Create.
  10. If you want to  put RDP bookmarks on the Clientless Access portal page, on the left, expand NetScaler Gateway, expand Resources, and click Bookmarks.
  11. Alternatively, Simon Gottschlag Publish RDP Proxy Link via StoreFront shows how NetScaler Rewrite can insert an RDP Proxy link into a StoreFront web page.  💡
  12. On the right, click Add.
  13. Give the Bookmark a name.
  14. For the URL, enter rdp://MyRDPServer using IP or DNS.
  15. Check the box next to Use NetScaler Gateway As a Reverse Proxy and click Create.
  16. Create more bookmarks as desired.
  17. Create or edit a session profile/policy.
  18. On the Security tab, set Default Authorization Action to ALLOW. Or you can use Authorization policies to control access.
  19. On the Remote Desktop tab, select the RDP Client Profile you created earlier.
  20. If you want to use Bookmarks, on the Client Experience tab, set Clientless Access to On.
  21. On the Published Applications tab, make sure ICA Proxy is OFF.
  22. Edit or Create your Gateway Virtual Server.
  23. In the Basic Settings section, click More.
  24. Use the RDP Server Profile drop-down to select the RDP Server Profile you created earlier.
  25. Scroll down. Make sure ICA Only is not checked.
  26. Bind a certificate.
  27. Bind authentication policies.
  28. Bind the session policy/profile that has the RDP Client Profile configured.
  29. 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.
  30. On the left, in the Published Applications section, click where it says No Url.
  31. Bind your Bookmarks.
  32. 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.
  33. On the right, click Change authentication AAA settings.
  34. Change the Maximum Number of Users to your licensed limit.
  35. If you want to connect to RDP servers using DNS, make sure DNS servers are configured on the appliance (Traffic Management > DNS > Name Servers).
  36. If you want to use the short names instead of FQDNs, add a DNS Suffix (Traffic Management > DNS > DNS Suffix).
  37. Connect to your Gateway and login.
  38. If you configured Bookmarks, simply click the Bookmark.
  39. Or you can change the address bar to /rdpproxy/MyRDPServer. You can enter IP address (e.g. rdpproxy/192.168.1.50) or DNS names (/rdpproxy/myserver).
  40. Then open the downloaded .rdp file.
  41. You can view the currently connected users by going to NetScaler Gateway > Policies > RDP and on the right is the Connections tab.

NetScaler Gateway 11 RADIUS Authentication

Last Modified: May 4, 2017 @ 2:22 pm

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. See CTX205907 Dual-Password Field Shows in First Authentication When Connecting to NetScaler Gateway from Windows Receiver for instructions. 💡

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

    add authentication radiusAction RSA -serverIP 10.2.2.210 -serverPort 1812 -radKey Passw0rd
  8. Since you can’t create authentication policies from the authentication dashboard, go to NetScaler Gateway > Policies > Authentication > RADIUS.
  9. On the right, in the Policies tab, click Add.
  10. Name it RSA-SelfService or similar.
  11. Select the RADIUS server created earlier.
  12. Enter an expression. You will need two policies with different expressions. The expression for Receiver Self-Service is HTTP.HEADER User-Agent CONTAINS CitrixReceiver.
  13. Click Create.

    add authentication radiusPolicy RSA-Web "REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver" RSA
    
    add authentication radiusPolicy RSA-SelfService "REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver" RSA
    
    add authentication ldapPolicy Corp-Gateway-Web "REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver" Corp-Gateway
    
    add authentication ldapPolicy Corp-Gateway-SelfService "REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver" Corp-Gateway
  14. 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-SelfService REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver RSA
    RSA-Web REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver RSA

  15. Go to the NetScaler Gateway\Policies\Authentication\LDAP node.
     
  16. 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-SelfService REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver LDAP-Corp
    LDAP-Corp-Web REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver LDAP-Corp

Bind Two-factor Policies to Gateway

  1. When you create the 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-Web LDAP Primary
    RSA-SelfService RADIUS Primary
    LDAP-Corp-SelfService LDAP Secondary
    RSA-Web RADIUS Secondary

    bind vpn vserver gateway.corp.com -policy Corp-Gateway-Web -priority 100
    
    bind vpn vserver gateway.corp.com -policy RSA-SelfService -priority 110
    
    bind vpn vserver gateway.corp.com -policy RSA-Web -priority 100 -secondary
    
    bind vpn vserver gateway.corp.com -policy Corp-Gateway-SelfService -priority 110 -secondary
    
  2. The session policy/profile for Receiver Self-Service needs to be adjusted to indicate which authentication field contains the Active Directory password. In the Session Profile, 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 Virtual Server

Last Modified: May 4, 2017 @ 2:22 pm

Navigation

💡 = Recently Updated

NetScaler Gateway Universal Licenses

For basic ICA Proxy connectivity to XenApp/XenDesktop, you don’t need to install any NetScaler Gateway 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 Edition of XenMobile, and the Platinum version of NetScaler.

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 SmartAccess, SmartControl, and VPN features.

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.

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 the version info on the top right.

To change the hostname, click the gear icon on the top right.

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. This field has a default value of 5, and administrators frequently forget to change it thus only allowing 5 users to connect.
  6. If desired, check the box for Enable Enhanced Authentication Feedback. Click OK.

    set aaa parameter -enableEnhancedAuthFeedback YES -maxAAAUsers 200
  7. Then edit the NetScaler Gateway Virtual Server.
  8. In the Basic Settings section, click the pencil icon near the top right.
  9. Click More.
  10. In the Max Users field, either enter 0 (for unlimited/maximum) or enter a number that is equal to or less than the number of licensed users. Click OK.

    set vpn vserver gateway.corp.com -maxAAAUsers 0

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. 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.

  2. On the left, right-click NetScaler Gateway and click Enable Feature.
  3. On the left, expand NetScaler Gateway and click Virtual Servers.
  4. On the right, click Add.
  5. Name it gateway.corp.com or similar.
  6. Enter a new VIP that will be exposed to the Internet. Note: new to NetScaler 11.0 is the ability to set it to Non Addressable, which means you can place it behind a Content Switching Virtual Server.
  7. Click More.
  8. In the Max Users field enter 0.
  9. In the Max Login Attempts field, enter your desired number. Then enter a timeout in the Failed Login Timeout field.
  10. Check the box next to ICA Only. This option disables SmartAccess and VPN features but does not require any additional licenses.
  11. Check the box next to DTLS and click OK. DTLS enables UDP Audio and Framehawk. Note: DTLS is not yet supported for double-hop ICA.
  12. In the Certificates section, click where it says No Server Certificate.
  13. Click the arrow next to Click to select.
  14. Select a previously created certificate that matches the NetScaler Gateway DNS name, and click Select.
  15. Click Bind.
  16. If you see a warning about No usable ciphers, click OK.
  17. Click Continue.
  18. In the Authentication section, click the plus icon in the top right.
  19. 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.
  20. Select LDAP, select Primary and click Continue.
  21. If you used the authentication dashboard to create the LDAP server then you probably haven’t create the corresponding policy yet. Click the plus icon to create a new policy.
  22. Use the Server drop-down to select the previously created LDAP server.
  23. Give the policy a name. It can match the LDAP Server name.
  24. In the Expression box, enter ns_true or select it from the Saved Policy Expressions drop-down. Click Create.
  25. Click Bind.
  26. 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)
  27. Click Continue.
  28. Scroll down to the Profiles section and click the pencil icon.
  29. In the TCP Profile drop-down select nstcp_default_XA_XD_profile and click OK.
  30. In the Policies section, click the plus icon near the top right.
  31. Select Session, select Request and click Continue.
  32. Click the arrow next to Click to select.
  33. Select one of the Receiver session policies and click Select. It doesn’t matter which order you bind them.
  34. There’s no need to change the priority number. Click Bind.
  35. Repeat these steps to bind the second policy. In the Policies section, click the plus icon near the top right.
  36. Select Session, select Request and click Continue.
  37. Click Add Binding.
  38. Click the arrow next to Click to select.
  39. Select the other Receiver session policy and click Select.
  40. There’s no need to change the priority number. Click Bind.
  41. The two policies are mutually exclusive so there’s no need to adjust priority. Click Close.
  42. On the right, in the Advanced Settings section, click Published Applications.
  43. Click where it says No STA Server.
  44. Add a Controller in the https://<Controller_FQDN> or http://<Controller_FQDN> format, depending on if SSL is enabled on the XenApp Controller or not. This must be a FQDN or IP address. Short names don’t work.
  45. For the Address Type, select IPV4. Click Bind.
  46. To bind another Secure Ticket Authority server, on the left, in the Published Applications section, click where it says 1 STA Server.
  47. Click Add Binding. Enter the URL for the second controller.
  48. The State is probably down. Click Close.
  49. In the Published Applications section, click STA Server.
  50. Now they should be up and there should be a unique Auth ID for each server. Click OK.

    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 X1
  51. 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.digicert.com/help/ to verify the certificate chain.
  3. 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, NetScaler 11.0 build 62 and newer have a built-in X1 theme:

  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, click where it says No Portal Theme.
  4. Click to select.
  5. Select the built-in X1 theme and click Select.
  6. Click Bind.
  7. Click Done.

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

You can also create 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 it a name and select X1 as the Template Theme.

  4. In the Look and Feel section there are two sub-sections: one for Home Page and one for Other Pages. In each of these sections is an Attribute Legend link that shows you what you can edit.
  5. The Home Page is for Unified Gateway (aka VPN Clientless Access).

  6. If you want to modify the logon page, use the Other Pages sub-section.

  7. Make changes as desired and click OK.
  8. In the Locale section, select a language and click OK.
  9. On the right, in the Advanced Settings section, click Login Page.
  10. Make changes as desired (e.g. Password Field Titles) and click OK.
  11. At the top of the screen, click the link to Click to bind and view configured theme.
  12. Select a Gateway Virtual Server and click Preview.
  13. The logon page is displayed.
  14. You could go to /var/netscaler/logon/themes/StoreFront3/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.
  15. Citrix CTX209526 NetScaler; How to Copy a Portal Theme from the Device running version 11.0 to another Device running 11.0.  💡

Jason Samuel – How to fix Green Bubble theme after upgrading to NetScaler 11 Unified Gateway details the following:

  • Change the NetScaler Unified Gateway logo to match the older Citrix Receiver logo.
  • Restore the older favicon.
  • And other observations regarding the Green Bubbles theme in NetScaler 11.0

SSL Redirect – Down vServer Method

This procedure details the Down vServer method of performing an SSL redirect. An alternative is to use the Responder method.

  1. On the left, expand Traffic Management, expand Load Balancing, and click Virtual Servers.

  2. On the right, click Add.
  3. Give it a name of Gateway-HTTP-SSLRedirect or similar.
  4. Set the IP Address so it matches the VIP of the NetScaler Gateway vServer. Click OK.
  5. Do not select any services. This redirect only works if the vServer is Down. Click Continue.
  6. On the right, in the Advanced Settings column, click Protection.
  7. Enter https://gateway.corp.com or similar into the Redirect URL Click Save.
  8. Then click Done.

    add lb vserver gateway.corp.com-HTTP-SSLRedirect HTTP 10.2.2.200 80 -redirectURL "https://gateway.corp.com"
  9. All SSL Redirect Virtual Servers are supposed to be Down. They don’t work if they are not down. By contrast, the Responder method uses redirect Virtual Servers that are Up.

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

Andrew Morgan Blocking the new Citrix VPN iOS connection to Netscaler gateway and 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, do not set the Plugin type to Windows/Mac OS X.

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.
  4. Click OK.
  5. In the Portal Theme section 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.  💡

Citrix CTX202444 How to Customize NetScaler Gateway 11 logon Page with Links shows how to add links to the NetScaler Gateway 11 logon page.

  1. In WinSCP, go to /netscaler/ns_gui/vpn/js and edit the file gateway_login_form_view.js.
  2. Scroll down to line 40 and insert the code copied from the article. Feel free to change the link.
  3. Scroll down to line 140 and insert the line form.append(link_container);
  4. Since this is an if block, insert the line in both the if section and the else section (line 148). Both should be after the append field_login line and before the append(form) line.
  5. Save the file and verify your results.
  6. If you reboot your appliance then your changes will be lost. To preserve your changes after a reboot, copy the modified file to /var.

  7. Then edit /nsconfig/rc.netscaler and add a cp line to copy the modified file from /var to /netscaler/ns_gui/vpn/js. This is the same procedure as older NetScaler firmware. Feel free to reboot your appliance to confirm that the changes are still applied.

Other Customizations

Citrix CTX215817 NetScaler : How to Customize Footer of NetScaler Gateway Login Page.  💡

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: If you have NetScaler 11 build 62 or newer then enabling DTLS on the Gateway also enables Framehawk. See VDA > Framehawk for Framehawk configuration.

Requirements for UDP Audio:

  • Citrix Receiver 4.2 or newer
  • NetScaler Gateway 10.5.e (enhancement build) or NetScaler 11
  • 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

Unified Gateway

Unified Gateway FAQ at docs.citrix.com

The Unified Gateway wizard in NetScaler 11 relies on Clientless Access and the built-in portal. See Jens Trendelkamp NetScaler Gateway Single Sign-On to Storefront in Clientless Access Mode and Citrix CTX202890 How to Integrate StoreFront into Clientless Access Page from NetScaler When Using CVPN to learn how to enable iFrame in StoreFront so it can be embedded in the Clientless Access portal.

Unified Gateway means Content Switching for NetScaler Gateway. There are two methods of Content Switching:

  • Create a Content Switching Virtual Server that has a Content Switching policy that directs requests to a NetScaler Gateway
  • Create a NetScaler Gateway Virtual Server that has Content Switching policies that direct requests to Load Balancing Virtual Servers.

In either case you can only have one Gateway Virtual Server in the Content Switching configuration.

Content Switching vServer with Gateway as Target

  1. When creating a Gateway Virtual Server, you can change the IP Address Type to Non Addressable. This means you can only access the Gateway through a Content Switching Virtual Server.
  2. On the left, go to Traffic management > Content Switching > Policies.
  3. On the right click Add.
  4. Give the policy a name.
  5. Click the plus icon next to the Action field.
  6. Give the Action a name.
  7. Change the selection to NetScaler Gateway Virtual Server.
  8. Click the arrow to select a Gateway Virtual Server and click Create.
  9. Back in the policy screen, enter an expression. There are several options for selecting traffic that should be directed to the Gateway:
    • Hostname
    • The built-in is_vpn_url expression
    • Any path that starts with /Citrix/.
    http.REQ.HOSTNAME.SET_TEXT_MODE(IGNORECASE).EQ("mygateway.corp.com") && (is_vpn_url || http.REQ.URL.PATH.SET_TEXT_MODE(IGNORECASE).STARTSWITH("/Citrix/"))
    
  10. Click Create when done.
  11. Add or Edit a Content Switching Virtual Server.
  12. Click where it says No Content Switching Policy Bound.
  13. Click the arrow to select a Content Switching policy and click Bind.

Gateway vServer with Load Balancing vServer as Target

Another option is to bind Content Switching policies to a Gateway Virtual Server:

  1. On the left, go to Traffic Management > NetScaler Gateway > Policies > Content Switching.
  2. On the right, click Add to create a Content Switching Policy with an Action that points to a Load Balancing Virtual Server.
  3. On the left, go to NetScaler Gateway > Virtual Servers.
  4. On the right, edit an existing NetScaler Gateway Virtual Server.
  5. On the right in the Advanced Settings section, click Content Switching Policies.
  6. Click where it says No Content Switching Policies.
  7. Select a Content Switching policy that sends traffic to a Load Balancing Virtual Server and click Bind.
  8. Repeat for additional Content Switching policies that redirect to Load Balancing Virtual Servers. You cannot bind Content Switching policies that redirect to NetScaler Gateway Virtual Servers.

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

Session Policies for StoreFront – NetScaler Gateway 11

Last Modified: May 4, 2017 @ 2:14 pm

Navigation

This page details creation of session profiles and policies for NetScaler Gateway 11 where ICA Only (formerly known as Basic Mode) 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. 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. 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).
  12. 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.
  13. For Account Services Address, enter the Base URL for StoreFront. NetScaler needs to be able to resolve this DNS name.
  14. Highlight the existing session profile and click Add. This copies the settings from the existing profile into the new one.
  15. Change the name of the second Session Profile to ReceiverForWeb or similar.
  16. On the Client Experience tab, Clientless Access should be set to Allow. Scroll down.
  17. Plug-in Type should still be set to Java.
  18. Single Sign-on to Web Applications should be enabled.
  19. 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.
  20. On the Security tab, the Default Authorization Action should still be Allow.
  21. On the Published Applications tab, for the Web Interface Address field, add the path to your Receiver for Web site (e.g. /Citrix/StoreWeb).
  22. Account Services Address only applies to Receiver Self-Service so you can leave it or clear it.
  23. 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 NetBIOS 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.
  24. Account Services Address is not needed in this profile but there’s no harm in leaving it.
  25. 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. Either type in 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

Create NetScaler Gateway Virtual Server

NetScaler Gateway 11 LDAP Authentication

Last Modified: May 4, 2017 @ 2:21 pm

Navigation

Verify LDAPS

Use the tool ldp.exe to verify that the Domain Controllers have valid certificates installed and the service account is able to bind to the LDAP tree.

  1. ldp.exe is included with the Remote Server Administration Tools (AD DS Snap-Ins and Command-Line Tools)
  2. Run ldp.exe

  3. Open the Connection menu and click Connect.
  4. Check the box next to SSL. Change the port to 636. Then enter the FQDN of a Domain Controller and click OK.
  5. If it connected successfully, you can then attempt a bind. If the connection was unsuccessful then there’s probably an issue with the certificate installed on the Domain Controller.
  6. Open the Connection menu and click Bind.
  7. Change the Bind type to Simple bind. Then enter the service account credentials. You can use DOMAIN\Username or you can use Username@Domain.com. Click OK.
  8. Look on the right pane to verify a successful bind. If not, fix the credentials and try again.
  9. Once you have successfully binded, you can view the directory tree by opening the View menu and click Tree.
  10. Click the drop-down to view the directory partitions.
  11. Repeat these steps to verify each Domain Controller and any load balanced LDAPS.

LDAP Load Balancing

Before you create an LDAP authentication policy, setup LDAPS load balancing:

You can create multiple load-balancing Virtual Servers to load balance multiple domains. These load-balancing Virtual Servers can share the same VIP if their port numbers are different. Or you can use a different VIP for each domain.

LDAP Server

To create the LDAP Authentication Server, do the following:

  1. On the left, expand Authentication and click Dashboard.
  2. On the right, click Add.
  3. In the Choose Server Type drop-down, select LDAP.
  4. Enter LDAP-Corp as the name. If you have multiple domains, you’ll need a separate LDAP Server per domain so make sure you include the domain name.
  5. Change the selection to Server IP. Enter the VIP of the load balancing vServer for LDAP.
  6. Change the Security Type to SSL.
  7. Enter 636 as the Port. Scroll down.
  8. In the Connection Settings section, in the Base DN field, enter your Active Directory DNS domain name in LDAP format.
  9. Enter the credentials of the LDAP bind account in userPrincipalName format. Domain\Username also works.
  10. Check the box next to BindDN Password and enter the password. Scroll down.
  11. In the Other Settings section, use the drop-down next to Server Logon Name Attribute, Group Attribute, and Sub Attribute Name to select the default fields for Active Directory.
  12. On the right, check the box next to Allow Password Change.
  13. Note: there is a checkbox for Validate LDAP Server Certificate. If you want to do this, see Citrix Discussions for instructions for loading the root certificate to /nsconfig/truststore.
  14. If you want to restrict access to only members of a specific group, in the Search Filter field, enter memberOf=<GroupDN>. See the example below:
    memberOf=CN=CitrixRemote,OU=Citrix,DC=corp,DC=local
    You can add :1.2.840.113556.1.4.1941: to the query so it searches through nested groups. Without this users will need to be direct members of the filtered group.
    memberOf:1.2.840.113556.1.4.1941:=CN=CitrixRemote,OU=Citrix,DC=corp,DC=local

    1. An easy way to get the full distinguished name of the group is through Active Directory Administrative Center. Double-click the group object and switch to the Extensions page. On the right, switch to the Attribute Editor tab.
    2. Or in Active Directory Users & Computers, enable Advanced view, browse to the object (don’t use Find), double-click the object, and switch to the Attribute Editor tab.
    3. Scroll down to distinguishedName, double-click it and then copy it to the clipboard.

    4. Back on the NetScaler, in the Search Filter field, type in memberOf= and then paste the Distinguished Name right after the equals sign. Don’t worry about spaces.
  15. Scroll down and click More.
  16. For Nested Group Extraction, if desired, change the selection to Enabled.
  17. Set the Group Name Identifier to samAccountName.
  18. Set the Group Search Attribute to memberOf. Select << New >> first.
  19. Set the Group Search Sub-Attribute to CN. Select << New >> first
  20. For the Group Search Filter field, see CTX123795 Example of LDAP Nested Group Search Filter Syntax.
  21. Scroll down and click Create.

    add authentication ldapAction Corp-Gateway -serverIP 10.2.2.210 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn "corp\\ctxsvc" -ldapBindDnPassword Passw0rd -ldapLoginName samaccountname -searchFilter "memberOf=CN=Citrix Remote,CN=Users,DC=corp,DC=local" -groupAttrName memberOf -subAttributeName CN -secType SSL -passwdChange ENABLED
  22. The status of the LDAP Server should be Up.
  23. The Authentication Dashboard doesn’t allow you to create the LDAP Policy at this time. Instead the LDAP Policy will be created later when you bind the LDAP Server to the NetScaler Gateway vServer.

Authentication Feedback and Licenses

  1. On the left, under NetScaler Gateway, click Global Settings.
  2. On the right, in the right column, click Change authentication AAA settings.
  3. If you are using Gateway features that require Gateway Universal licenses, then change the Maximum Number of Users to the number of Gateway Universal licenses you have installed on this appliance. This field has a default value of 5, and administrators frequently forget to change it, thus only allowing 5 users to connect.
  4. If desired, check the box for Enable Enhanced Authentication Feedback. This feature provides a message to users if authentication fails. The message users receive include password errors, account disabled or locked, or the user is not found, to name a few. Click OK.

    set aaa parameter -enableEnhancedAuthFeedback YES -maxAAAUsers 200

Next Step

Multiple Domains

To support multiple Active Directory domains on a NetScaler Gateway, you create multiple LDAP authentication policies, one for each Active Directory domain, and bind all of the LDAP policies to the NetScaler Gateway Virtual Server. When the user logs into NetScaler Gateway, only the username and password are entered. The NetScaler will then loop through each of the LDAP policies in priority order until it finds one that contains the entered username/password.

What if the same username is present in multiple domains? As NetScaler loops through the LDAP policies, as soon as it finds one with the specified username, it will try to authenticate with that particular LDAP policy. If the password doesn’t match the user account for the attempted domain then a failed logon attempt will be logged in that domain and NetScaler will try the next domain.

Unfortunately, the only way to enter a realm name during user authentication is to require users to login using userPrincipalNames. To use userPrincipalName, set the LDAP Policy/Server with the Server Logon Name Attribute set to userPrincipalName.

You can even do a combination of policies: some with samAccountName and some with userPrincipalName. The samAccountName policies would be searched in priority order and the userPrincipalName policies can be used to override the search order. Bind the userPrincipalName policies higher (lower priority number) than the samAccountName policies.

Note: NetScaler 11.0 build 64 supports adding a domain name drop-down list to the logon page. Then use Cookie expressions in the auth policies and session policies. However, this probably doesn’t work for Receivers. See CTX203873 How to Add Drop-Down Menu with Domain Names on Logon Page for NetScaler Gateway 11.0 64.x and later releases for details.  💡
User-added image

After authentication is complete, a Session Policy will be applied that has the StoreFront URL. The NetScaler Gateway will attempt to log into StoreFront using SSO so the user doesn’t have to login again. When logging into NetScaler Gateway, only two fields are required: username and password. However, when logging in to StoreFront, a third field is required: domain name. So how does NetScaler specify the domain name while logging in to StoreFront?

There are two methods of specifying the domain:

  • Configure multiple session policies with unique Single Sign-on Domains.  Inside the Session Policy is a field called Single Sign-on Domain for specifying the domain name. If there is only one Active Directory domain then you can use the same Session Policy for all users. However, if there are multiple domains then you would need multiple Session Policies, one for each Active Directory domain. But as the NetScaler loops through the LDAP policies during authentication, once a successful LDAP policy is found, you need a method of linking an LDAP policy with a Session Policy that has the corresponding SSO Domain. This is typically done using AAA groups. This method is not detailed here but the general steps are: In the LDAP policy, specify a Default Authentication Group. Create a AAA group that matches it. Then bind the corresponding Session Policy to that AAA group.
  • Alternatively, configure the LDAP policy/server to extract the user’s UPN and then authenticate to StoreFront using UPN. This is the easiest method but some domains don’t have userPrincipalNames configured correctly.

This userPrincipalName method is detailed below:

  1. In each of your NetScaler LDAP policies/servers, in the Other Settings section, in the SSO Name Attribute field, enter userPrincipalName (select –<< New >>– first). Make sure there are no spaces after this name. NetScaler will use this attribute to authenticate the user against StoreFront.
  2. In StoreFront Console, right-click  the Store, and click Manage Authentication Methods.
  3. On the right, click the gear icon, and then click Configure Trusted Domains.
  4. In the Trusted domains box, select Any domain.
  5. Or add your domains in DNS format. The advantage of entering domain names is that you can select a default domain if internal users forget to enter a domain name during login. The DNS format is required for UPN logins (e.g. SSO from NetScaler Gateway).
  6. On the NetScaler Gateway Virtual Server, bind LDAP authentication polices in priority order. It will search them in order until it finds a match.
  7. In your session policies, make sure Single Sign-on Domain is not configured. Since NetScaler is using the userPrincipalName, there’s no need to specify a domain. If Single Sign-on Domain is configured, then Single Sign-on authentication will fail.

NetScaler Insight Center

Last Modified: Jul 12, 2017 @ 6:18 am

This article is for Insight Center 11.0 and older. Consider Insight Center 11.1, which works with older NetScaler appliances.

Navigation

💡 = Recently Updated

Planning

Note: HDX Insight only works with Session Reliability on NetScaler 10.5 build 54 or newer. Older builds, including NetScaler 10.1, do not support Session Reliability with HDX Insight. Read the release notes for your NetScaler firmware build to see the latest known issues with AppFlow, Session Reliability, and High Availability.

Requirements for HDX Insight:

  • Your NetScaler appliance must be running Enterprise Edition or Platinum Edition.
  • NetScaler must be 10.1 or newer. Insight Center 11 does work with NetScaler 10.5.
  • HDX Insight works with the following Receivers:
    • Receiver for Windows must be 3.4 or newer.
    • Receiver for Mac must be 11.8 or newer.
    • Receiver for Linux must be 13 or newer.
    • Notice no mobile Receivers. See the Citrix Receiver Feature Matrix for the latest details.
  • ICA traffic must flow through a NetScaler appliance:

 

For ICA round trip time calculations, in a Citrix Policy, enable the following settings:

  • ICA > End User Monitoring > ICA Round Trip Calculation
  • ICA > End User Monitoring > ICA Round Trip Calculation Interval
  • ICA > End User Monitoring > ICA Round Trip Calculation for Idle Connections

Citrix CTX204274 How ICA RTT is calculated on NetScaler Insight: ICA RTT constitutes the actual application delay. ICA_RTT = 1 + 2 + 3 + 4 +5 +6:  💡

  1. Client OS introduced delay
  2. Client to NS introduced network delay (Wan Latency)
  3. NS introduced delay in processing client to NS traffic (Client Side Device Latency)
  4. NS introduced delay in processing NS to Server (XA/XD) traffic (Server Side Device Latency)
  5. NS to Server network delay (DC Latency)
  6. Server (XA/XD) OS introduced delay (Host Delay)

 

For Web Insight, HTML Injection for NetScaler 10.0 is only available in Platinum Edition. In NetScaler 10.1, HTML Injection is available in all editions.

The version/build of Insight Center must be the same or newer than the version/build of the NetScaler appliances.

Insight Center 11 lets you scale the deployment by building multiple nodes. After building the first Insight Center Server, you can go to Configuration > NetScaler Insight Center > Insight Deployment Method to enter some planning data (e.g. # of concurrent ICA connections) and it will tell you the number of Insight Center nodes you should build. The number of nodes is based on the VM specs shown at the top of the page.

In this example, it recommends two Database Nodes and two Connectors. Agents are only used for HTTP traffic. There’s more information at NetScaler Insight Center Deployment Management at docs.citrix.com.

Import Appliance

You can use either the vSphere Client or the vSphere Web Client to import the appliance. In vSphere Client, open the File menu and click Deploy OVF Template. vSphere Web Client instructions are shown below.

You might see this operating system error when not using the vSphere Web Client. Click Yes and proceed. It seems to work.

  1. Download Insight Center for ESX and then extract the .zip file.
  2. In vSphere Web Client, navigate to the vCenter object. Open the Actions menu and click Deploy OVF Template.
  3. In the Select source page, if you see a message regarding the Client Integration Plug-in, download the installer, run it, and then return to this wizard.
  4. In the Select source page, select Local file and browse to the NetScaler Insight .ovf file. Click Next.
  5. In the Review details page, click Next.
  6. In the Select name and folder page, enter a name for the virtual machine and select an inventory folder. Then click Next.
  7. In the Select a resource page, select a cluster or resource pool and click Next.
  8. In the Select storage page, change it to Thin Provision.
  9. Select a datastore and click Next.
  10. In the Setup networks page, choose a valid port group and click Finish.
  11. In the Ready to Complete page, click Finish.
  12. View the progress of the import in the Recent Tasks pane at the top-right of the window.
  13. After the appliance is imported, power it on.

IP Configuration and Multi-Node

  1. Open the console of the virtual machine and configure an IP address.
  2. Insight Center 11 lets you configure a DNS server.
  3. Enter 6 when done.
  4. When prompted for Insight Deployment Type, enter 1 for NetScaler Insight Server. The first appliance must always be NetScaler Insight Server.
  5. Enter Yes to reboot.
  6. Subsequent nodes can be Database Node, Connector node, etc. If you choose one of the other node types it asks you for the IP address of the NetScaler Insight Server node.
  7. Once you’ve built all of the nodes, in the NetScaler Insight Server webpage, go to NetScaler Insight Center > Insight Deployment Management.
  8. Scroll down and click Get.
  9. It should show you the nodes. Then click Deploy.

  10. After it reboots you’ll see the performance of each node.
  11. Since the database is on a separate node, you might want to enable database caching. Go to System > Change Database Cache Settings.
  12. Check the box next to Enable Database Cache.

Initial Web Configuration

  1. Point your browser to the Insight IP address and login as nsroot/nsroot.
  2. Click Get Started

  3. Enter the IP address and credentials of a NetScaler appliance and click Add.

    Note: if your NetScaler appliances require https for management communication then this won’t work. Click Cancel. On the Configuration tab, click System. On the right, in the left column, click Change System Settings.
    Change the drop-down to https and click OK.
    On the left, click Inventory. On the right, click Add.
    Enter the NSIP and nsroot credentials again. This time it should work.
  4. At the top of the page, if desired, check the box next to Enable Geo data collection for Web and HDX Insight.
  5. With Load Balancing selected in the View list, right-click your StoreFront load balancer and click Enable AppFlow.

  6. Type in true and click OK.
  7. Note: if your StoreFront Load Balancing vServer uses Service Groups, you might need to enable AppFlow logging on the Service Group. In the NetScaler GUI, edit the Service Group. In the Basic Settings section, check the box next to AppFlow Logging.
  8. Back in Insight Center, use the View drop-down to select VPN.
  9. Right-click a NetScaler Gateway Virtual Server and click Enable AppFlow.
  10. In the Select Expression drop-down, select true.
  11. For Export Option select ICA and HTTP and click OK. The HTTP option is for Gateway Insight.
  12. The TCP option is for the second appliance in double-hop ICA. If you need double-hop then you’ll also need to run set appflow param -connectionChaining ENABLED on both appliances. See Enabling Data Collection for NetScaler Gateway Appliances Deployed in Double-Hop Mode at docs.citrix.com for more information.
  13. New in NetScaler 11 is the ability to use SOCKS proxy (Cache Redirection) for ICA traffic without requiring users to use NetScaler Gateway and without making any routing changes. You configure this on the NetScaler appliance. See Enabling Data Collection for Monitoring NetScaler ADCs Deployed in LAN User Mode at docs.citrix.com for more information.
  14. If you want to add more appliances, click the Configuration tab. The Inventory node will be selected by default.
  15. On the right, click Add.

Citrix Blog PostNetScaler Insight Center – Tips, Troubleshooting and Upgrade

Nsroot Password

  1. On the Configuration tab, expand System, expand User Administration and click Users.
  2. On the right, highlight the nsroot account and click Edit.
  3. Enter a new password.
  4. You can also specify a session timeout. Click OK.

Management Certificate

The certificate to upload must already be in PEM format. If you have a .pfx, you must convert it to PEM (separate certificate and key files). You can use NetScaler to convert the .pfx and then download the converted certificate from the appliance.

  1. On the left, switch to the System node.
  2. In the right pane, in the left column, click Install SSL Certificate.
  3. Browse to the PEM format certificate and key files. If the keyfile is encyrpted, enter the password. Click OK.
  4. Click Yes to reboot the system.

System Configuration

  1. Click the Configuration tab on the top of the page.
  2. On the left, click the System node.
  3. On the right, modify settings (e.g.Time Zone) as desired.

  4. To set the hostname, click Change Host name.

  5. To change the Session Timeout, click Change System Settings.

  6. The ICA Session Timeout can be configured by clicking the link. Two minutes of non-existent traffic must occur before the session is considered idle. Then this idle timer starts. See Managing ICA Sessions at docs.citrix.com for more information

  7. On the left, expand System and click NTP Servers.
  8. On the right, click Add.

  9. After adding NTP servers, click NTP Synchronization.
  10. Check the box next to Enable NTP Sync and click OK.
  11. On the left, expand Auditing and click Syslog Servers.

  12. On the right, click Add.
  13. Enter the syslog server IP address and select Log Levels. Click Create.
  14. In the Action menu you can click Syslog Parameters to change the timezone and date format.

Email Notifications

  1. On the left, expand System, expand Notifications and click Email.
  2. On the right, on the Email Servers tab, click Add.
  3. Enter the SMTP server address and click Create.
  4. On the right, switch to the Email Distribution List tab and click Add.
  5. Enter an address for a destination distribution list and click Create.

Authentication

  1. On the left, expand System¸ expand Authentication and click LDAP.
  2. On the right, click Add.
  3. This is configured identically to NetScaler. Enter a Load Balancing VIP for LDAP. Change the Security Type to SSL and Port to 636. Scroll down.
  4. Enter the bind account.
  5. Check the box for Enable Change Password.
  6. Click Retrieve Attributes and scroll down.
  7. For Server Logon Attribute select sAMAccountName.
  8. For Group Attribute select memberOf.
  9. For Sub Attribute Name select cn.
  10. To prevent unauthorized users from logging in, configure a Search Filter. Scroll down.
  11. If desired configure Nested Group Extraction.
  12. Click Create.
  13. On the left, expand User Administration and click Groups.
  14. On the right, click Add.
  15. Enter the case sensitive name of your NetScaler Admins group.
  16. Select the admin Permission.
  17. If desired, configure a Session Timeout. Click Create.

  18. On the left, under System, click User Administration.
  19. On the right click User Lockout Configuration.
  20. If desired, check the box next to Enable User Lockout and configure the maximum logon attempts. Click OK.
  21. On the left, under System, click Authentication.
  22. On the right, click Authentication Configuration.
  23. Change the Server Type to LDAP.
  24. Select the LDAP server you created and click OK.

Thresholds

  1. Go to NetScaler Insight Center > Thresholds.
  2. On the right, click Add.
  3. Enter a name.
  4. In the Entity field select a category of alerts. What you choose here determines what’s available in the Rule section.
  5. Check the box to Notify through Email.
  6. In the Rule section, select a rule and enter threshold values. Click Create.

Geo Map

  1. Download the Maxmind database from http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz.
  2. Extract the .gz file.
  3. On the Configuration tab, expand NetScaler Insight Center and click Geo Database Files.
  4. On the right, click the Action drop-down and click Upload.
  5. Browse to the extracted GeoLiteCity.dat file and click Upload.
  6. Click the Inventory node.
  7. Click the IP address for a device in the inventory.
  8. Check the box to Enable Geo data collection for Web and HDX Insight.
  9. You can define Geo locations for internal subnets. Go to NetScaler Insight Center > Private IP Block.
  10. On the right, click Add.
  11. Enter a name.
  12. Enter the starting and ending IP address.
  13. Select a Geo Location. Note that these are not necessarily alphabetical.
  14. Click Create.

Director Integration

Integrating Insight Center with Director requires XenApp/XenDesktop to be licensed for Platinum Edition. The integration adds Network tabs to the Trends and Machine Details views.

If using HTTPS to connect to Insight Center then the Insight Center certificate must be valid and trusted by both the Director Server and the Director user’s browser.

To link Citrix Director with NetScaler HDX Insight, on the Director server run C:\inetpub\wwwroot\Director\tools\DirectorConfig.exe /confignetscaler. Do this on both Director servers.

Use Insight Center

HDX Insight

HDX Insight Dashboard displays ICA session details including the following:

  • WAN Latency
  • DC Latency
  • RTT (round trip time)
  • Retransmits
  • Application Launch Duration
  • Client Type/Version
  • Bandwidth
  • Licenses in use

HDX Insight can also display Geo Maps. Configure Insight Center with Private IP Blocks.

More info at HDX Insight Reports and Use Cases: HDX Insight at docs.citrix.com

Gateway Insight

Insight Center 11.0 build 65 adds a new Gateway Insight dashboard.

This feature displays the following details:

  • Gateway connection failures due to failed EPA scans, failed authentication, failed SSON, or failed application launches.
  • Bandwidth and Bytes Consumed for ICA and other applications accessed through Gateway.
  • # of users
  • Session Modes (clientless, VPN, ICA)
  • Client Operating Systems
  • Client Browsers

More details at Gateway Insight at docs.citrix.com.

Security Insight

The new Security Insight dashboard in 11.0 build 65 and newer uses data from Application Firewall to display Threat Index (criticality of attack), Safety Index (how securely NetScaler is configured), and Actionable Information. More info at Security Insight at docs.citrix.com.
localized image

Troubleshooting

Citrix CTX215130 HDX Insight Diagnostics and Troubleshooting Guide: Syslog messages; Error counters; Troubleshooting checklist, Logs

Citrix Blog PostNetScaler Insight Center – Tips, Troubleshooting and Upgrade

See docs.citrix.com Troubleshooting Tips. Here are sample issues covered in docs.citrix.com:

  • Can’t see records on Insight Center dashboard
  • ICA RTT metrics are incorrect
  • Can’t add NetScaler appliance to inventory
  • Geo maps not displaying

Upgrade Insight Center

  1. Download the latest Upgrade Pack for Insight Center.
  2. Login to Insight Center.
  3. If you are running Insight Center 10.5 or older, on the Configuration tab, go to NetScaler Insight Center > Software Images and upload the file. If running Insight Center 11.0 or newer, you can skip this step.
  4. On the Configuration tab, on the left, click the System node.
  5. On the right, in the right pane, click Upgrade NetScaler Insight Center.
  6. Browse to the build-analytics-11.0.tgz Software Image Upgrade Pack and click OK.
  7. Click Yes to reboot the appliance.

  8. After it reboots, login. The new firmware version will be displayed in the top right corner.