Category: NetScaler 12

nFactor Authentication – NetScaler Gateway 12 / Citrix Gateway 12.1

Last Modified: Apr 16, 2021 @ 2:32 pm

85 Comments

Navigation

💡 = Recently Updated

Change Log

nFactor 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:

  1. Collect credentials from the user. These credentials can be anything supported by Citrix ADC, including:
    • SAML assertion
    • Client Certificate
    • OAuth OpenID Connect
    • Kerberos ticket
    • StoreFrontAuth – authentication is delegated to Citrix StoreFront
    • 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.
    • Endpoint Analysis Scan – either pre-authentication, or post-authentication.
    • EULA
    • Google reCAPTCHA
    • Swivel
    • Use a drop-down to select an authentication method
  2. This factor’s credentials are evaluated. The results can be:
    • Authentication success
    • Authentication failure
    • Group extraction
    • Attribute extraction from SAML, Certificate, etc.
  3. Based on the evaluation results, do one of the following:
    • Allow access
    • Select next factor
    • Deny access
  4. If there’s a Next Factor, repeat these steps, until there are no more Next Factors to evaluate.
  5. The Next Factor can also do one of the following:
    • Prompt the user for more credentials
    • If the Login Schema asked for multiple passwords, evaluate the already entered next set of credentials.
    • Use a 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:

  • Choose 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 client certificate, or ask user for LDAP password. If LDAP, the username doesn’t need to be entered again.
  • Ask for Certificate first:
    • If client certificate is valid, perform LDAP only.
    • If no client certificate, perform LDAP + RADIUS
  • Two-factor with passwords checked in specific order: Display logon screen with two password fields. Check the first password. If the first password succeeds, then check the second password. This lets you check RADIUS before LDAP.
  • Run Endpoint Analysis first:
    • If passes, perform LDAP only.
    • If fails, perform LDAP + RADIUS
  • See Sample Configurations later for many more combinations.

All new authentication methods added to Citrix ADC require nFactor configuration and are not supported on native Citrix Gateway. These new authentication methods include:

nFactor is a AAA feature, which means you need Citrix ADC Advanced Edition (aka NetScaler Enterprise Edition) or Citrix ADC Premium Edition (aka NetScaler Platinum Edition). Citrix ADC Standard Edition and Citrix Gateway VPX are not entitled for nFactor.

Citrix ADC supports two types of authentication policies – Classic, and Advanced (aka Default). You can bind Classic Authentication Policies directly to Citrix Gateway Virtual Servers, but today you cannot bind Advanced Authentication Policies to Citrix Gateway. The only way to use Advanced Authentication Policies with Citrix Gateway is to configure nFactor on a AAA Virtual Server and then link the AAA Virtual Server to the Gateway Virtual Server.

  • Workspace app 1809 and newer with Citrix Gateway (NetScaler) 12.1 build 49 and newer support nFactor authentication. Older Receivers and older NetScalers don’t support nFactor, so you’ll instead have to use a web browser.

nFactor configuration summary (detailed instructions below):

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

Also see:

This article will detail how to configure nFactor from top to bottom.:

  1. Create AAA vServer
  2. Create Login Schema Profiles
  3. Create Login Schema Policy – select Login Schema Profile, bind Login Schema Policy to AAA vServer
  4. Create Authentication Actions – LDAP, RADIUS, etc.
  5. Create Advanced Authentication Policies – select Authentication Action, bind Advanced Authentication Policy to AAA vServer
  6. Create Authentication Policy Labels – bind Login Schema, bind Advanced Authentication Policies
  7. Edit Advanced Authentication Policy binding and select Next Factor Authentication Policy Label.
  8. Create Citrix Gateway Traffic Policy for Single Sign-on to StoreFront.
  9. Create Authentication Profile
  10. Edit Citrix Gateway – bind Authentication Profile, bind Traffic Policy

Once you are familiar with nFactor, due to the way the objects are linked together, it’s probably easier to configure it from bottom up:

  1. Create Authentication Actions – LDAP, RADIUS, etc.
  2. Create Advanced Authentication Policies – select Authentication Action
  3. Create Login Schema Profiles
  4. Create Authentication Policy Labels – bind Login Schema, bind Advanced Authentication Policies
  5. Create Login Schema Policy – select Login Schema Profile
  6. Create AAA vServer – bind Login Schema, bind Advanced Authentication Policies, select Next Factor Authentication Policy Label
  7. Create Citrix Gateway Traffic Policy for Single Sign-on to StoreFront.
  8. Create Authentication Profile
  9. Edit Citrix Gateway – bind Authentication Profile, bind Traffic Policy

It can be difficult to visualize a nFactor configuration so my ADC Virtual Server Configuration Extractor script now includes a nFactor visualizer. Here’s an example for a Native OTP configuration.

AAA Virtual Server

Create AAA Virtual Server

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

  1. If AAA feature is not already enabled, on the left menu, expand Security, right-click AAA – Application Traffic, and click 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 Citrix Gateway, then you can change the IP address Type to Non Addressable. It’s also possible to content switch to AAA (Citrix CTX201949 One Public IP for AAA-TM Deployments on NetScaler).
  6. Click OK.
  7. In the Certificates section, click where it says No Server Certificate.

    1. Click where it says Click to select.
    2. Click the radio button next to 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.
    3. Click Bind.
  8. Click Continue to close the Certificate section.
  9. You probably don’t have any Advanced Authentication Policies yet, so just click Continue.

Bind Portal Theme to AAA Virtual Server

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

  1. Go to Citrix Gateway > Portal Themes, and add a theme. You create the theme under Citrix Gateway, and then later bind it to the AAA Virtual Server.
  2. Create a theme based on the RfWebUI Template Theme.
  3. After adjusting the theme as desired, at the top of the portal theme editing page, Click to Bind and View Configured Theme.
  4. Change the selection to Authentication.
  5. Use the Authentication Virtual Server Name drop-down to select the AAA Virtual Server, and click Bind and Preview. You can close the preview window.

Client Certificate Authentication

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

  1. Go to Traffic Management > SSL > Certificates > CA Certificates, and install the root certificate for the issuer of the client certificates. Root certificates do not have a key file.

  2. Go to Traffic Management >SSL > Change advanced SSL settings.

    1. Scroll down. If you see Default Profile: ENABLED, then you must use an SSL Profile to enable Client Certificate Authentication. Otherwise, you can enable Client Certificate Authentication directly on the AAA Virtual Server in the SSL Parameters section.
  3. If Default SSL Profiles are enabled, then create a new SSL Profile with Client Authentication enabled:
    1. On the left menu, expand System, and click Profiles.
    2. On the top right, switch to the SSL Profile tab.
    3. Right-click the ns_default_ssl_profile_frontend profile, and click Add. This copies settings from the default profile.
    4. Give the Profile a name. The purpose of this profile is to enable Client Certificates.
    5. Scroll down and find the Client Authentication checkbox. Check the box.
    6. Change the Client Certificate drop-down to OPTIONAL.
    7. Copying the default SSL Profile does not copy the SSL Ciphers so you’ll have to redo them.
    8. Click Done when done creating the SSL Profile.
    9. Go to Security > AAA – Application Traffic > Virtual Servers, and edit a AAA vServer.
    10. Scroll down to the SSL Profile section and click the pencil.
    11. Change the SSL Profile drop-down to the profile that has Client Certificates enabled. Click OK.
    12. Scroll down this article until you reach the instructions to bind the CA certificate.
  4. If default SSL Profiles are not enabled:
    1. Go to Security > AAA > Virtual Servers, and edit an existing AAA Virtual Server.
    2. On the left, in the SSL Parameters section, click the pencil icon.
    3. Check the box next to Client Authentication.
    4. Make sure Client Certificate drop-down is set to Optional, and click OK.
  5. On the left, in the Certificates section, click where it says No CA Certificate.
  6. Click to select.
  7. Click the radio button next to the root certificate for the issuer of the client certificates, and click Select.
  8. 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 Login Schema gather information that can be passed on to multiple 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 Citrix ADC under /nsconfig/loginschema/LoginSchema.

You can edit the Login Schema labels from within the Citrix ADC management GUI. When the labels are changed, Citrix ADC copies the Login Schema to a new .xml file based on the Schema Name entered in this widow, or based on the original file name.

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

The structure of the Login Schema is documented at Citrix Common Authentication Forms Language Citrix Developer Documentation.

CTP Sam Jacobs at SYN229 – nFactor and Login Schemas explains how to customize the .xml file.

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 and Authentication Factor can be a EULA. See Citrix CTX226488 How to Configure EULA as an Authentication Factor in NetScaler nFactor.

Citrix CTX219545 Custom Login Labels in NetScaler nFactor Authentication: add a Requirement element with a Label sub-element to the Login Schema .xml file. Then use JavaScript to populate the label with any desired HTML. Another example is Morten Kallesoee nFactor – adding custom links.

Several more samples can be found later.

Login Schema Profile

To configure a Login Schema Profile:

  1. Create or Edit a Login Schema .XML file based on your nFactor design.
  2. Go to Security > AAA > Login Schema.
  3. On the right, switch to the Profiles tab, and click Add.
  4. In the Authentication Schema field, click the pencil icon.
  5. Click the LoginSchema folder to see the files in it.
  6. Select one of the files. You can see a preview on the right. The labels can be changed by clicking the Edit button on the top right.
  7. When you Save the changes, a new file is created under /nsconfig/LoginSchema.
  8. On the top right, click Select.
  9. Give the Login Schema a name, and click More.
  10. You typically need to use the entered credentials elsewhere. For example, you might need to use the username and one of the passwords to later Single Sign-on to StoreFront. Near the bottom of the Login Schema Profile, click More, and enter unique values for the indexes. These values can be between 1 and 16.

    1. Later you reference these index values in a Traffic Policy/Profile by using the expression HTTP.REQ.USER.ATTRIBUTE(#).
  11. Click Create to create the Login Schema profile.

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

To bind a Login Schema Profile to a AAA vServer, you must first create a Login Schema Policy. Login Schema Policies are not required when binding the Login Schema Profile to an Authentication Policy Label, as detailed later.

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 (e.g. true) 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 Schema.
  8. Click where it says Click to select.
  9. Click the radio button next to 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 authentication 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.

Note: Citrix Gateway 12.0 and newer have deprecated Basic Authentication Policies (Classic Syntax). The only way to bind an Advanced Authentication Policy (Default Syntax) to Gateway is through nFactor and AAA.

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 (Add) icon that lets you create Authentication Actions/Servers.
  • Or you can create Authentication Actions (Servers) prior to creating the Advanced Authentication Policy. The Authentication Servers are located under Authentication > Dashboard. On the right, click Add and select a Server Type. The instructions for creating these Authentication Servers is not detailed here. See the Authentication – NetScaler 12 / Citrix ADC 12.1 procedures.

To create an Advanced Authentication Policy:

  1. Go to Security > AAA > Policies > 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, Citrix ADC checks each authentication policy in priority order until one of them succeeds.
  3. Use the Action Type drop-down to select the Action Type (e.g. LDAP). Typically each Factor is a different type of Authentication Action.
  4. If you don’t currently have any Actions configured, or if you want to create a new one, click the plus icon (Add button) next to the Action drop-down. The Actions/Servers are created in the normal fashion (not detailed here).
  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 First Factor 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 Next 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 where it says Click to select.
  5. Click the radio button next to the Advanced Authentication Policy, and click Select.
  6. In the Binding Details section, 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 AAA Virtual Server is evaluated. If it is set to END, or if there are no more Advanced Authentication Policies bound to this AAA Virtual Server, then authentication is finished and marked as failed.
  7. 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.
  8. Click Bind.

LDAP Group Extraction

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

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

  1. When creating or editing an LDAP Server/Action, make sure Authentication is unchecked.
  2. In the Other Settings section, make sure Group Attribute and Sub Attribute Name are filled in.

Authentication Policy Label

When configuring the first Factor, you bind two objects directly 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 Citrix 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 succeeds, 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 succeed, 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 succeeds, 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 succeeds, 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 web 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 a Login Schema Profile that is set to noschema (LSCHEMA_INT) if you don’t actually want to display anything to the user. Then click Continue.
  5. In the Policy Binding section, click where it says Click to select.
  6. Click the radio button next to 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 want to chain another Factor, click where it says Click to select, and bind the next Authentication Policy Label (Next Factor). You can click the Add button to create another Policy Label.
  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). Note: each Label is a separate factor. If your intent is multi-factor, then create a separate Label for the next factor.
  12. When done, 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. You can select a Next Factor (Policy Label) in two places:

  • Edit an existing AAA Virtual Server that has an Advanced Authentication Policy already bound to it and edit the binding to include the Next Factor.
  • Edit a different Policy Label, and edit an Advanced Authentication Policy binding to include the Next Factor.

To add a Policy Label Next Factor to a AAA Virtual Server:

  1. Edit an existing AAA Virtual Server that has an Advanced Authentication Policy already bound to it.
  2. On the left, in the Advanced Authentication Policies section, click the existing Authentication Policy bindings.
  3. Right-click an existing binding, and click Edit Binding.
  4. In the Select Next Factor field, click where it says Click to select.
  5. Click the radio button next to the Policy Label for the Next Factor, and click Select.
  6. Click Bind.
  7. The far right shows the Next Factor.
  8. Click Close.

To add a Policy Label Next Factor to a different Policy Label:

  1. Go to Security > AAA – Application Traffic > Policies > Authentication > Advanced Policies > PolicyLabel.
  2. On the right, edit a different Policy Label.
  3. Highlight an existing Advanced Authentication Policy binding, open the Action menu, and click Edit Binding.
  4. In the Binding Details section, next to Select Next Factor, click Click to select.
  5. Click the radio button next to a Policy Label for the next factor, and then click the blue Select button on the top of the window.
  6. Click Bind.
  7. On the far right, you can see the configured Next Factor.
  8. Click Close to close the PolicyLabel.

nFactor for Citrix Gateway

AAA Authentication Profile

Authentication Profile links a AAA Virtual Server to Citrix Gateway and enables nFactor on Citrix Gateway.

  1. Go to Citrix Gateway > Virtual Servers.
  2. On the right, edit an existing Gateway Virtual Server.
  3. On the right, in the Advanced Settings column, click Authentication Profile.
  4. On the left, click the plus icon (Add button) next to the Authentication Profile drop-down.
  5. Give the Authentication Profile a name.
  6. In the Authentication Virtual Server field, click where it says Click to select.
  7. Click the radio button next to 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.
  8. Then click Create.
  9. And click OK to close the Authentication Profile section.
  10. 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.
  11. When you browse to your Gateway, you’ll see the nFactor authentication screens.
  12. Workspace app 1809 and newer with Gateway/ADC 12.1 build 49 and newer should support nFactor authentication. Older clients with older builds do not support nFactor, so those users will have to use a web browser.
    1. CTX223386 nFactor Authentication with Native Clients from NetScaler 11.1: Although Native Receiver Clients can now leverage advanced authentication policies, they still interact using legacy Gateway protocol. That is, Native Clients do not yet support nFactor wire protocol. Gateway acts intelligently based on the clients that are interfacing with it. That is, for Browser client, Gateway redirects to advanced login page with all customizations. For a Native Receiver client, Gateway responds according to the legacy protocol. Since Native clients do not process LoginSchema (even if it is sent), Gateway processes the configured LoginSchema, learns the configured factors, and sends hint to the clients in response to /vpn/index.html.

Gateway Client Certificate Authentication

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

  1. Go to Traffic Management > SSL > Certificates > CA Certificates, and install the root certificate for the issuer of the client certificates. Certificate Authority certificates do not need key files.
  2. If default SSL Profiles are enabled, then you should have already created an SSL Profile that has Client Authentication enabled.
  3. Go to Citrix Gateway > Virtual Servers, and edit an existing Citrix Gateway Virtual Server that is enabled for nFactor.
  4. If default SSL Profiles are enabled:
    1. Scroll down to the SSL Profile section, and click the pencil icon.
    2. In the SSL Profile drop-down, select the SSL Profile that has Client Authentication enabled and set to OPTIONAL.
  5. If default SSL Profiles are not enabled:
    1. On the left, in the SSL Parameters section, click the pencil icon.
    2. Check the box next to Client Authentication.
    3. 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 where it says Click to select.
  8. Click the radio button next to the root certificate for the issuer of the client certificates, and click Select.
  9. Click Bind.
  10. You might have to also bind any Intermediate CA Certificates that issued the client certificates.

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

Sample Configurations

From Citrix Docs: Sample deployments using nFactor authentication:

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

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

  • Prefill user name from certificate. Read
  • Certificate authentication followed by group extraction for 401 enabled traffic management virtual servers. Read
  • Certificate fallback to LDAP in same cascade; one virtual server for both certificate and LDAP authentication. Read
  • LDAP in first factor and WebAuth in second factor. Read
  • WebAuth in first factor, LDAP in second factor. Read
  • Domain drop down in first factor, then different policy evaluations based on selected domain. Read

    • Domain drop-down, then send Domain\Username to RADIUS.  Read
  • Google reCAPTCHA first factor, LDAP second. Read (George Spiers)
  • Supporting reCaptcha with NetScaler nFactor. Read
  • CTX225938 nFactor – Customizing UI to Display Images – e.g. Swivel
  • With 12.0 version of NetScaler, EPA is blended into the authentication framework thereby making EPA a conditional or on-demand feature. This reduces the need for multiple virtual servers by allowing for all the clients to gain access to a single virtual server. See CTX223597 Concepts and Entities Used for EPA in nFactor Authentication Through NetScaler.
  • Configure Post-Authentication EPA (Endpoint Analysis) Scan as a Factor. Read
  • Configure Pre-Authentication EPA (Endpoint Analysis) Scan as a Factor. Read
  • Configure EULA (End User License Agreement) as an Authentication Factor. Read
  • Show a drop-down box in the logon form and automatically hide or show certain fields based on drop-down selection. Read

  • Step-up authentication – i.e. one Unified Gateway website needs single factor, while other website needs multi-factor. Read
  • RADIUS authentication with reversed PIN – if user enters reversed PIN, then user is under duress. This sample configuration has some interesting components:  Read  💡
    • Policy Extension Function using the Lua language
      • Usage = HTTP.REQ.BODY(1000).TYPECAST_NVLIST_T(’=’,’&’).VALUE(”passwd1”).RPIN
    • NetScaler Variable of type Map with Expiration timer
      • Responder to set the variable
      • Variable identifies duress state for four hours
    • Custom syslog message (audit messageaction) triggered by a Responder
    • Default Authentication Group to put duressed user on site/farm with Session Recording enabled
    • nFactor sequence:

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

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

The authentication process flows like this:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Group Extraction, followed by LDAP (Active Directory), or Azure MFA (NPS)

Azure MFA is available as a plug-in for Microsoft Network Policy Server (NPS), which is a Microsoft RADIUS server and built-in Windows Server Role.

NPS performs both AD authentication, and Azure MFA authentication. NetScaler sends the user’s AD password to NPS. NPS verifies AD, and then the NPS Azure MFA plug-in calls the user (or push notification to the user). If both AD and MFA are successful, then NPS sends back RADIUS-Accept.

Summary:

  1. First factor Login Schema asks for Username only.
    1. LDAP Group Extraction (with Authentication disabled) reads the user’s groups from AD.
  2. Second factor checks for group membership and sends to one of two different third factors.
  3. If user is in LDAP Group, or Client IP is on internal network, then perform LDAP-only authentication.
    1. Login schema asks for AD password.
    2. LDAP Policy authenticates with LDAP Server (Active Directory).
  4. Otherwise, perform RADIUS (two-factor) authentication.
    1. Login schema asks for AD password.
      • Note: NPS with MFA plugin only needs the AD password. Alternatively, you could use a Login Schema that asks for both LDAP password and RADIUS password.
    2. RADIUS Policy uses the entered AD password to authenticate to Microsoft NPS and Azure MFA.

CLI Commands. Note, these objects are created in the required order, which is backwards from how you would want to configure them.

  1. Add cert for AAA vServer. Link the cert to Intermediate. 
    add ssl certKey WildcardCorpCom -cert WildcardCorpCom.pfx -key WildcardCorpCom.pfx -inform PFX -passcrypt "myPassword"

link ssl certKey WildcardCorpCom Intermediate
  2. Enable AAA feature if not already enabled. 
    enable ns feature AAA
  3. Create first factor LDAP Action (LDAP Server) and LDAP Policy (expression) for Group Extraction. Authentication is disabled. This is the first factor that is bound directly to the AAA vServer. 
    add authentication ldapAction LDAP-Corp-GroupExtract -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn ctxsvc@corp.local -ldapBindDnPassword MyPassword -ldapLoginName sAMAccountName -groupAttrName memberOf -subAttributeName cn -secType SSL -authentication DISABLED

add authentication Policy LDAP-Corp-GroupExtract -rule true -action LDAP-Corp-GroupExtract
  4. Create a third-factor LDAP Action (LDAP Server) and Authentication Policy (expression) for Active Directory Authentication. This is the authentication factor if user is in the LDAP Users group. 
    add authentication ldapAction LDAP-Corp -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn ctxsvc@corp.local -ldapBindDnPassword MyPassword -ldapLoginName sAMAccountName -groupAttrName memberOf -subAttributeName cn -secType SSL -passwdChange ENABLED

add authentication Policy LDAP-Corp -rule true -action LDAP-Corp
  5. Create a third-factor RADIUS Action (RADIUS Server) and Authentication Policy (expression) for NPS. 
    add authentication radiusAction NPS -serverIP 10.2.2.42 -serverPort 1812 -radKey MySecret

add authentication Policy NPS -rule true -action NPS
  6. Create the second factor NO_AUTHN authentication policies to determine the next factor based on the user’s group membership. NO_AUTHN means don’t authenticate. Instead, these policies will have a Next Factor that points to the Authentication Policies that we created earlier. If the policy expression is true, then go to Next Factor. Next Factor is configured later when binding these policies to the second factor PolicyLabel. Note: the group name is case sensitive and must match the Active Directory group name. 
    add authentication Policy LDAP-Only -rule "http.REQ.USER.IS_MEMBER_OF(\"LDAP\") || client.IP.SRC.IN_SUBNET(10.2.2.0/24)" -action NO_AUTHN

add authentication Policy TwoFactor -rule "client.IP.SRC.IN_SUBNET(10.2.2.0/24).NOT" -action NO_AUTHN
  7. Create first factor Login Schema Profile for username-only group extraction. You can copy the built-in OnlyUsername.xml and modify it with your desired labels. Since this Login Schema Profile is bound to the AAA vServer, it needs a Login Schema Policy (expression). The other two Login Schema Profiles are bound to PolicyLabels and thus don’t need Login Schema Policies. 
    add authentication loginSchema OnlyUsername -authenticationSchema "/nsconfig/loginschema/LoginSchema/OnlyUsername.xml"

add authentication loginSchemaPolicy OnlyUsername -rule true -action OnlyUsername
  8. Create third factor Login Schema Profile for AD Authentication. The .xml file is copied from the built-in PrefillUserFromExpr.xml but with modified labels for AD authentication. The username is pre-filled in from the first factor. 
    add authentication loginSchema LDAPPasswordOnly -authenticationSchema "/nsconfig/loginschema/LDAPPassword.xml"
  9. Create third factor Login Schema Profile for NPS Authentication. The .xml file is copied from the built-in PrefillUserFromExpr.xml but with modified labels for NPS authentication. The username is pre-filled in from the first factor. 
    add authentication loginSchema NPSPasswordOnly -authenticationSchema "/nsconfig/loginschema/NPSPassword.xml"
  10. Create third factor PolicyLabel for Active Directory authentication with Active Directory Login Schema and Active Directory Authentication Policy. 
    add authentication policylabel LDAPPasswordAuth -loginSchema LDAPPasswordOnly

bind authentication policylabel LDAPPasswordAuth -policyName LDAP-Corp -priority 100 -gotoPriorityExpression NEXT
  11. Create third factor PolicyLabel for NPS authentication with NPS Login Schema and NPS Authentication Policy. 
    add authentication policylabel NPSPasswordAuth -loginSchema NPSPasswordOnly

bind authentication policylabel NPSPasswordAuth -policyName NPS -priority 100 -gotoPriorityExpression NEXT
  12. Create second factor PolicyLabel with Policies that choose Next Factor. This PolicyLabel is processed before the two we just created. 
    add authentication policylabel CheckForAuthType -loginSchema LSCHEMA_INT

bind authentication policylabel CheckForAuthType -policyName TwoFactor -priority 90 -gotoPriorityExpression NEXT -nextFactor NPSPasswordAuth

bind authentication policylabel CheckForAuthType -policyName LDAP-Only -priority 100 -gotoPriorityExpression NEXT -nextFactor LDAPPasswordAuth
  13. Create AAA vServer. Bind Login Schema Policy (username only) and Group Extraction Policy. 
    add authentication vserver AAA SSL 10.x.x.218 443
bind authentication vserver AAA -policy OnlyUsername -priority 100 -gotoPriorityExpression END
bind authentication vserver AAA -policy LDAP-Corp-GroupExtract -priority 100 -nextFactor CheckForAuthType -gotoPriorityExpression NEXT
  14. Perform additional steps not detailed here:
    1. For Traffic Management:
      1. Create a Session Policy and bind it to the AAA vServer.
      2. Enable authentication on the Load Balancing or Content Switching vServer.
    2. For NetScaler Gateway, create an Authentication Profile, and bind it to the Gateway vServer.

NetScaler Management and Analytics System (MAS) 12

Last Modified: May 21, 2019 @ 9:25 am

106 Comments

Navigation

The newer 12.1 version of NetScaler MAS (aka Citrix ADM, aka Citrix Application Delivery Management) is detailed in a different article.

The older 11.1 version of NetScaler MAS is detailed in a different article.

💡 = Recently Updated

Change Log

Planning

NetScaler MAS is a replacement for NetScaler Insight Center, Command Center, and Control Center. It’s a combination of these three different tools.

For an overview of MAS, see Citrix’s YouTube video Citrix NetScaler MAS: Application visibility and control in the cloud.

Cloud vs on-prem – MAS is available both on-premises and as a Cloud Service. For the Cloud Service, you import a MAS Agent appliance to an on-prem hypervisor, or deploy a MAS Agent to AWS or Azure. The MAS Agent is the broker between the Cloud Service and the on-prem (or cloud hosted) NetScaler appliances. For more info on the MAS Cloud Service, see the following:

The rest of this article focuses on the on-premises version, but much of it also applies to the Cloud Service.

On-premises MAS Licensing:

  • Instance management is free (unlimited). This includes Configuration Jobs, Instance Backups, Network Functions/Reporting. Basically everything in the Networks node is free.
  • Analytics and Application monitoring are free for up to 30 Virtual Servers (Load Balancing, NetScaler Gateway, Content Switching, etc.).
    • Beyond 30 Virtual Servers, licenses can be purchased in 100 Virtual Server packs. See NetScaler MAS Licensing at Citrix Docs.
    • You can control assignment of licenses to Virtual Servers.

MAS version – The version/build of NetScaler MAS must be the same or newer than the version/build of the NetScaler appliances being monitored.

HDX Insight Requirements (AppFlow Analytics for ICA traffic):

  • Your NetScaler appliance must be running Enterprise Edition or Platinum Edition.
  • NetScaler must be 10.1 or newer.
  • 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.
  • For ICA Session Reliability with AppFlow: NetScaler 10.5 build 54 and newer.
    • For ICA Session Reliability, AppFlow, and NetScaler High Availability: NetScaler 11.1 build 49 and newer.
  • Internally, when a user clicks an icon from StoreFront, an ICA connection is established directly from Receiver to the VDA, thus bypassing the internal NetScaler. To produce AppFlow statistics, here are some methods of getting ICA traffic to flow through an internal NetScaler:
  • 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 CTX215130 HDX Insight Diagnostics and Troubleshooting Guide contains the following contents:
    • Introduction
    • Prerequisites for Configuring HDX Insight
    • Troubleshooting
      • Issues Related to ICA parsing
      • Error Counter details
    • Checklist before Contacting Citrix Technical Support
    • Information to collect before Contacting Citrix Technical support
    • Known Issues

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)

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

  1. Download NetScaler MAS for ESX, and then extract the .zip file.
  2. In vSphere Web Client, right-click a cluster, and click Deploy OVF Template.
  3. In the Select an OVF Template page, select Local file, and browse to the NetScaler MAS .ovf files. If vCenter 6.5+, select all three files. Click Next.
  4. In the Select name and folder page, enter a name for the virtual machine, and select an inventory folder. Then click Next.
  5. In the Select a resource page, select a cluster or resource pool, and click Next.
  6. In the Review details page, click Next.
  7. In the Select storage page, select a datastore. If a single appliance, or if a database appliance, due to high IOPS, SSD or Flash is recommended.
  8. Change the virtual disk format to Thin Provision. Click Next.
  9. In the Select networks page, choose a valid port group, and click Finish.
  10. In the Ready to Complete page, click Finish.
  11. In vSphere 6.5 and newer, you’ll need to upgrade the VM Compatibility.
    1. Right-click the NetScaler MAS appliance, expand Compatibility, and click Upgrade VM Compatibility.
    2. Click Yes.
    3. Select at least hardware version 7 (ESX/ESXi 4.0 and later).
  12. Before powering on the appliance, you can review its specs.
  13. If you see a message about Invalid guestid in Configinfo, then you’ll have to upgrade the VM hardware version first. VM hardware version 4 seems to be too old for vSphere 6.5.
  14. Now you can review the default specs and increase them. Citrix Docs VMware ESXi Hardware Requirements has recommended specs.
  15. Citrix Docs How to Attach an Additional Disk to NetScaler MAS: power off appliance, add a second disk that’s larger than the first, then power on the appliance. Note: you can only add one disk. Use the MAS storage calculator to determine the recommended size of the disk.

    • Enabling more features on MAS means more disk space. MAS features that consume large amounts of disk space include: Web/SSL Insight. SNMP/Syslog/Network Reports have a configurable purge interval.
  16. Power on the VM if it’s not running already.
  17. If you see a message about freeBSD not being supported, then you might have to upgrade the VM Hardware Compatibility Level. VM hardware version 4 seems to be too old for vSphere 6.5.

Appliance IP Configuration and Deployment Modes

  1. Open the console of the virtual machine.
  2. Configure an IP address.
  3. Enter 7 when done.
  4. When prompted for Deployment Type, enter 1 for NetScaler MAS Server. The first appliance must always be NetScaler MAS Server.
  5. Other deployment options:
    1. Notice the option for Remote Backup Node.

MAS High Availability

MAS 12.0 build 51 and newer support active/passive High Availability. Another option is the Remote Backup Node.

  1. If you want to deploy two NetScaler MAS appliances and HA pair them, enter no for Standalone, and yes for First Server Node.
    1. Note: HA is only for database redundancy. All other traffic (SNMP, AppFlow) only goes to one node.
  2. Enter Yes to reboot.
  3. Deploy another appliance.
  4. This time, when asked if First Server Node, enter no. You will then be asked for the IP address of the first node. Enter the nsroot password.

MAS Maintenance

Getting Started

  1. Once you’ve built all of the nodes, point your browser to the primary NetScaler MAS IP address, and login as nsroot/nsroot.
  2. If you see CUXIP, either Skip or Enable the Customer User Experience Improvement Program.
  3. Click Get Started
  4. If you did a standalone deployment, select Single Server Deployment, click Next, and skip to the next section to Add Instances.
  5. If you deployed high availability appliances, select Two servers deployed in High Availability Mode, and click Next.
  6. It should show both nodes. Click Deploy on the top right.
  7. Click Yes to reboot the appliances.

  8. If you login to one of the appliances, at System > Deployment, you’ll see the performance of each node. Notice the Break HA icon on the top right.

  9. You can manage the pair by logging in to either node.
  10. Or you can load balance the pair. Load Balancing is only useful for administration. All other communications (e.g.  SNMP, AppFlow) go directly to one of the nodes. See High Availability Deployment at Citrix Docs for load balancing instructions. NetScaler Load Balancing can detect which node is Active and connect you to the Active node.

Add Instances

NetScaler MAS must discover NetScaler instances before they can be managed. Citrix Docs How NetScaler MAS Discovers Instances.

  1. On the Add New Instances page, click + New near the top right.
  2. Enter the NSIP address of a NetScaler appliance.
  3. Click the pencil next to ns_nsroot_profile.
  4. Check the box next to Do you want to change the password and enter the password for the nsroot account. MAS will use this password to login to the NetScaler instance.
  5. The NetScaler Profile defaults to using https for instance communication. You can change it by unclicking Use global settings for NetScaler communication.
  6. Enter an SNMP v2 community string or SNMP v3 Security Name that NetScaler MAS will configure on the appliance.
  7. Click OK.
  8. Then click OK to add the instance.
  9. A progress window will appear.
  10. You can add more instances, or just click Finish.
  11. To add more instances later, click the top left hamburger icon, go to Networks > Instances, select the Instance type, and on the right, click Add.

NetScaler SDX

  1. At Networks > Instances > NetScaler SDX, you can click Add to discover a SDX appliance, and all VPXs on that appliance. You don’t have to discover the VPXs separately.
  2. In the Add NetScaler SDX page, click the pencil icon next to the Profile Name drop-down to edit nssdx_default_profile. Or you can click the plus icon to create a new SDX Profile. Note: SDX profiles are different than VPX profiles.
  3. Enter the credentials for the SDX SVM Management Service.
  4. For NetScaler Profile, select an admin profile that has nsroot credentials for the VPX instances. If you don’t have one in your drop-down list, click the plus icon. Note: You can only select one NetScaler Profile. If each VPX instance has different nsroot credentials, you can fix it after SDX discovery has been performed. The NetProfile Profile is different than the SDX Profile.

    1. In the Create NetScaler Profile page, enter the nsroot credentials for the VPX instances, and click Create.
  5. Back in the Configure NetScaler SDX Profile page, you can uncheck the box for Use global settings for SDX communication, and change the protocol. Click OK when done.
  6. Back in the Add NetScaler SDX page, click OK to start discovery.
  7. After discovery is complete, on the left, go to Networks > Instances > NetScaler VPX. You should automatically see the VPX instances.
  8. To specify the nsroot credentials for a VPX, right-click the VPX, and click Edit.

    1. In the Modify NetScaler VPX page, either select an existing Profile Name, or click the plus icon to create a new one. Click OK when done. It should start rediscovery automatically.
  9. After fixing the nsroot credentials, right-click the VPX instance, and click Configure SNMP. MAS will configure the VPX to send SNMP Traps to MAS.

Instance management

  • REST API proxy – NetScaler MAS can function as a REST API proxy server for its managed instances. Instead of sending API requests directly to the managed instances, REST API clients can send the API requests to NetScaler MAS. See Citrix CTX228449 NetScaler MAS as an API Proxy Server
  • NetScaler VPX Check-In/Check-Out Licensing – You can allocate VPX licenses to NetScaler VPX instances on demand from NetScaler MAS. The Licenses are stored and managed by NetScaler MAS, which has a licensing framework that provides scalable and automated license provisioning. A NetScaler VPX instance can check out the license from the NetScaler MAS when a NetScaler VPX instance is provisioned, or check back in its license to NetScaler MAS when an instance is removed or destroyed. See Citrix CTX228451 NetScaler VPX Check-In/Check-Out Licensing with NMAS

Licenses

Virtual Server License Packs

Without licenses, you can enable analytics features on only 30 Virtual Servers. You can install additional licenses in 100 Virtual Server packs. More info at NetScaler MAS Licensing at Citrix Docs.

  1. Go to Networks> Licenses > System Licenses to see the number of currently installed licenses, and the number of managed virtual servers.
  2. By default, Auto-select Virtual Servers is enabled. If you disable this setting, then the Select Virtual Servers button appears.
  3. On the left, go to Networks > Licenses.
  4. On the right, notice the Host ID.
  5. At mycitrix.com, allocate your NetScaler MAS licenses to this Host ID.
  6. Then use the Browse button to upload the allocated license file.
  7. Click Finish after uploading the license file to apply it.
  8. The License Expiry Information section shows you the number of installed licenses and when they expire.
  9. You can use the Notification Settings section to email you when licenses are almost fully consumed or about to expire.

Allocate licenses to Virtual Servers

You can manually unassign a MAS Virtual Server license and reassign it to a different Virtual Server.

  1. Go to Networks > Licenses > System Licenses to see the number of Allowed Virtual Servers.
  2. By default, Auto-select Virtual Servers is enabled. If you disable this setting, then the Click to select button appears. Click it.
  3. In the top row, select the type of Virtual Server you want to unlicense or license. Yes, the headings are clickable.
  4. Select one or more Virtual Servers, and click the Mark Unlicensed button. Only the licensed Virtual Servers are listed.
  5. Click Yes when asked to mark unlicensed.
  6. The unlicensed Virtual Servers won’t be removed from the list until you click the Save and Exit or Finish button.
  7. Back in Choose Virtual Servers, to allocate a license to a Virtual Server, click the Add Virtual Servers button.
  8. Select the Virtual Server(s) you want to allocate.
    • You can use the Search button.
    • 12.0 build 57 adds a Throughput column, so you can see how much traffic each vServer is currently handling.
  9. At the top of the screen, click the blue Select button.
  10. Click Save & Exit or Finish when done.

Enable AppFlow / Insight

  1. Go to Networks > Instances > Instance type (e.g. NetScaler VPX).
  2. Right-click an instance, and then click Enable/Disable Insight.
  3. At the top of the page are boxes you can check.
  4. With Load Balancing selected in the View list, right-click your StoreFront load balancer, and click Enable AppFlow. If you don’t see your Virtual Server in this list, then you need to assign a license.
  5. Type in true.
  6. Select Web Insight.
  7. If App Firewall is enabled on the vServer, then also select Security Insight.
  8. HTML Injection injects JavaScript in HTTP responses to measure page load times.
  9. Click OK.

  10. Use the View drop-down to select VPN.
  11. Right-click a NetScaler Gateway Virtual Server, and click Enable AppFlow.
  12. In the Select Expression drop-down, select true.
  13. For Export Option, select ICA and HTTP, and click OK. The HTTP option is for Gateway Insight.
  14. 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 Citrix Docs for more information.

  15. By default, with AppFlow enabled, if a NetScaler High Availability pair fails over, all Citrix connections will drop, and users must reconnect manually. NetScaler 11.1 build 49 adds a new feature to replicate Session Reliability state between both HA nodes.
    1. From Session Reliability on NetScaler High Availability Pair at Citrix Docs: Enabling this feature will result in increased bandwidth consumption, which is due to ICA compression being turned off by the feature, and the extra traffic between the primary and secondary nodes to keep them in sync.
    2. If you still want this feature, on a NetScaler 11.1 build 49 and newer appliance, go to System > Settings.
    3. On the right, in the Settings section, click Change ICA Parameters.
    4. Check the box next to Session Reliability on HA Failover, and click OK.
  16. In a NetScaler 12 instance, at System > AppFlow > Collectors, you can see if the Collector (MAS) is up or not. However, NetScaler uses SNIP to verify connectivity, but AppFlow is sent using NSIP, so being DOWN doesn’t necessarily mean that AppFlow isn’t working. Citrix CTX227438 After NetScaler Upgrade to Release 12.0 State of AppFlow Collector Shows as DOWN.

  17. AppFlow (e.g. HDX Insight) information can be viewed in NetScaler MAS under the Analytics node.

Citrix Blog Post – NetScaler Insight Center – Tips, Troubleshooting and Upgrade

Enable Syslog on Instance

MAS can configure Syslog on the NetScaler instances, including sending Syslog to MAS.

Configure Syslog Method:

  1. Go to Networks > Instances > Instance Type.
  2. On the right, right-click an instance and click Configure Syslog.
  3. Uncheck All and check the other boxes. You probably don’t want Debug. Click OK.

Configuration Job Method:

  1. Go to Networks > Configuration Jobs.
  2. On the right, click Create Job.
  3. Give the job a name.
  4. Change the Configuration Source drop-down to Inbuilt Template.
  5. On the left, drag the NSConfigureSyslogServer blue text to the right side of the screen. Notice that this job uses variables.
  6. On the bottom, click Next.
  7. On the Select Instances page, click Add Instances.
  8. Select one or more instances, and click OK.
  9. Click Next.
  10. In the Specify Variable Values page, switch to the Common Variable Values for all instances tab.
  11. Enter the Syslog server IP address (e.g. MAS IP address). Click Next.
  12. In the Job Preview page, review the commands it’s going to run, and click Next.
  13. In the Execute page, click Finish.
  14. The job will eventually say Completed.

MAS Nsroot Password

  1. In MAS, go to System > User Administration > Users.
  2. On the right, right-click the nsroot account, and click Edit.
  3. Check the box next to Change Password and enter a new password.
  4. You can also specify a session timeout by checking the box next to Configure Session Timeout. Click OK.

Management Certificate

The certificate to upload must already be in PEM format. If you have a .pfx, you must first 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. Go to System > System Administration.
  2. On the right, in the Set Up NetScaler MAS section, click Install SSL Certificate.
  3. Click Choose File to browse to the PEM format certificate and key files. If the keyfile is encrypted, enter the password. Click OK.
  4. Click Yes to reboot the system.

System Configuration

Note: the System Administration page has been rearranged slightly in MAS 12.0 build 53 and newer.

  1. Go to System > System Administration.
  2. On the right, modify settings (e.g. Change Time Zone) as desired.

  3. Click Change System Settings.

    1. Check the box next to Enable Session Timeout, and specify a value.
    2. By default, on the Instances page, if you click a blue IP address link, it opens the instance in a new webpage, and logs in using the nsroot credentials. If you want to force users to login using non-nsroot credentials, in Modify System Settings, check the bottom box for Prompt Credentials for Instance Login.

  4. Configure SSL Settings lets you disable TLS 1 and TLS 1.1.

    1. Click the Protocol Settings section in the Edit Settings section on the right side of the screen.

  5. On the left are Prune Settings.
  6. System Prune Settings defaults to deleting System Events, Audit Logs, and Task Logs after 15 days. System events are generated by the MAS appliance, which contrasts with Instance events (SNMP traps) that are generated by NetScaler appliances.

    1. 12.0 build 53 and newer can initiate a purge automatically as the database starts to get full.
    2. If you click the pencil next to the purge threshold value, you can configure an alarm for when the database gets full.

    3. To see the current database disk usage, go to System > Statistics.
  7. Instance Events prune Settings controls when instance SNMP traps are pruned, which defaults to 40 days.

  8. If you are sending Syslog from instances to MAS, Instance Syslog Purge Settings controls when the log entries are purged. You can even configure different purge intervals for different types of NetScaler Gateway log entries.

  9. In the right column, under Backup Settings, are additional settings.
  10. System Backup Settings lets you export MAS backups to an external file server (External Transfer).

  11. Instance Backup Settings lets you configure how often the instances are backed up. These can also be transferred to External systems.

  12. There are more settings under System > Analytics Settings.
  13. 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.

  14. MAS 12.0 build 56 lets you configure how the App Score (Application Dashboard) is calculated.

  15. System > Analytics Settings > Database Summarization lets you configure how long Analytics data is retained. Adjusting these values could dramatically increase disk space consumption. See CTX224238 How Do I Increase Granularity of Data Points Stored on NetScaler MAS Analytics?.

    • To see the current database disk usage, go to System > Statistics.
  16. On the left, click System > NTP Servers.
  17. On the right, click Add.
  18. Enter an NTP server, and click Create.

  19. After adding NTP servers, click the NTP Synchronization button.
  20. Check the box next to Enable NTP Synchronization, and click OK.
  21. Click Yes to restart.
  22. Go to System > Auditing > Syslog Servers.
  23. On the right, click Add.
  24. Enter the syslog server IP address, and select Log Levels. Click Create.
  25. You can click Syslog Parameters to change the timezone and date format.

System Email Notifications

  1. Go to System > Notifications > 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.
  6. On the left, click System > Notifications.
  7. On the right, click Change Notification Settings.
  8. Move notification categories (e.g. UserLogin) to the right.
  9. Check the box next to Send Email. Select a notification distribution list. Then click OK.

Authentication

  1. Go to System > Authentication > 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 Base DN in LDAP format.
  5. Enter the bind account credentials.
  6. Check the box for Enable Change Password.
  7. Click Retrieve Attributes, and scroll down.
  8. For Server Logon Attribute, select sAMAccountName.
  9. For Group Attribute, select memberOf.
  10. For Sub Attribute Name, select cn.
  11. To prevent unauthorized users from logging in, configure a Search Filter. Scroll down.
  12. If desired, configure Nested Group Extraction.
  13. Click Create.
  14. On the left, go to System > User Administration > Groups.
  15. On the right, click Add.

    1. Enter the case sensitive name of your NetScaler Admins AD group.
    2. Move the admin Permission to the right.
    3. The Configure User Session Timeout checkbox lets you configure a session timeout.
    4. Click Next.
    5. On the Applications and Templates page, click Create Group. If you are delegating limited permissions, you can uncheck these boxes and delegate specific entities.
    6. In the Assign Users page, click Finish. Group membership comes from LDAP, so there’s no need to add local users.
  16. On the left, go to System > User Administration.
  17. On the right, click User Lockout Configuration.
  18. If desired, check the box next to Enable User Lockout, and configure the maximum logon attempts. Click OK.
  19. On the left, go to System > Authentication.
  20. On the right, click Authentication Configuration.
  21. Change the Server Type to EXTERNAL, and click Insert.
  22. Select the LDAP server you created, and click OK.
  23. Make sure Enable fallback local authentication is checked, and click OK.

Analytics Thresholds

  1. Go to System > Analytics Settings > Thresholds.
  2. On the right, click Add.
  3. Enter a name.
  4. Use the Traffic Type drop-down to select HDX, Web, or Security.

    • In MAS 12.0 build 56 and newer, with HDX as the Traffic Type, the Rules section lets you add multiple rules. The other two Traffic Type options only let you specify one rule.
  5. Use the Entity drop-down to select a category of alerts. What you choose here determines what’s available as Metrics when you click Add Rule. With HDX as the Traffic Type, to add multiple rules for multiple Entity types, simply change the Entity drop-down before adding a new rule.
  6. Check the box to Enable Alert.
  7. Check the box to Notify through Email and select an existing Email Distribution List.
  8. In MAS 12.0 build 56 and newer, if HDX is the Traffic Type, click Add Rule to add a rule.
  9. Select a Metric, and enter threshold values (e.g. WAN Latency > 200 ms). The available metrics are based on the Entity chosen earlier. Click OK when done.
  10. In MAS 12.0 build 56 and newer, if HDX is the Traffic Type, you can add multiple rules for multiple Entity types.
  11. If the Traffic Type is HDX, and the Entity drop-down is set to Users, on the bottom in the Configure Geo Details section, you can restrict the rule so it only fires for users for a specific geographical location.

  12. On the bottom of the window, 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 left, go to System > Advanced Settings, and click Geo Database Files.
  4. On the right, click Upload.
  5. Browse to the extracted GeoLiteCity.dat file, and click Open.
  6. You can also define Geo locations for internal subnets. Go to Networks > Sites > Private IP Blocks.
  7. On the right, click Add.
  8. Enter a name for the subnet.
  9. Enter the starting and ending IP address.
  10. Select a Geo Location (Country, Region, City).
  11. Click Create.
  12. On the left, go to Networks > Sites.
  13. On the right, click Add.
  14. Give the site a name.
  15. Click Add IP Block.
  16. Select one or more IP Blocks, and click Select.
  17. Click Create.

Instance Email Alerts (SNMP Traps)

You can receive email alerts whenever a NetScaler appliance sends a critical SNMP trap.

  1. On the left, go to Networks > Events > Rules.
  2. On the right, click Add.
  3. Give the rule a name.
  4. Move Severity filters (e.g. Major, Critical) to the right by clicking the plus icon next to each Severity.
  5. While scrolling down, you can configure additional alert filters.
  6. On the bottom of the page, click Add Action.
  7. Select an Action Type (e.g. Send e-mail Action).
  8. Select the recipients (or click the plus icon to add recipients).
  9. Optionally, enter a Subject and/or Message.
  10. Emails can be repeated by selecting Repeat Email Notification until the event is cleared.
  11. Click OK.
  12. Then click Create.
  13. See the Event Management section at MAS How-to articles at Citrix Docs.

Events Digest  💡

MAS can email you a daily digest (PDF format) of system and instance events

To enable the daily digest:

  1. Go to System > Notifications.
  2. On the right, click Configure Event Digest Settings.
  3. Uncheck the box next to Disable Event Digest.
  4. Configure the other settings as desired, and click OK.

Director Integration

Integrating NetScaler MAS with Director adds Network tabs to Director’s Trends and Machine Details views. Citrix Blog Post Configure Director with Netscaler Management & Analytics System (MAS)

Requirements:

  • XenApp/XenDesktop must be licensed for Platinum Edition. This is only required for the Director integration. Without Platinum, you can still access the HDX Insight data by going visiting the NetScaler MAS website.
  • Director must be 7.11 or newer for NetScaler MAS support.
  • NetScaler MAS must be 11.1 build 49 or newer.

To link Citrix Director with NetScaler MAS:

  1. On the Director server, run C:\inetpub\wwwroot\Director\tools\DirectorConfig.exe /confignetscaler.
  2. Enter the NetScaler MAS nsroot credentials.
  3. If HTTPS Connection (recommended), the NetScaler MAS certificate must be valid and trusted by both the Director Server and the Director user’s browser.
  4. Enter 1 for NetScaler MAS.
  5. Do this on both Director servers.

Use NetScaler MAS

The AppFlow Analysis tools (e.g. HDX Insight) are located under the Analytics node. See Viewing HDX Insight Reports and Metrics at Citrix Docs.

NetScaler MAS also includes all previous Command Center functionality, which you can find on the Networks nodes. For example, at Networks > Instances, select an instance, and view its Dashboard.

Backups are available by right-clicking an instance, and clicking View Backup.

Networks > Network Reporting > NetScaler let you view Instance performance data.

Dave Bretty Automating Your Netscaler 11.1 Vserver Config Using Netscaler Management and Analytics System: use a Configuration Job to deploy StoreFront load balancing configuration to an instance.

Applications > Dashboard automatically includes all licensed vServers in the Others section. On the top right, click Define Custom App to group vServers together into an application. The grouped vServers are removed from the Others list.

The Applications Node has quite a bit of functionality. See Application Analytics and Management at Citrix Docs for details.

Link:

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 NetScaler MAS with Data Center definitions (private IP blocks). More info at Geo Maps for HDX Insight at Citrix Docs.

Citrix CTX215130 HDX Insight Diagnostics and Troubleshooting Guide contains the following contents:

  • Introduction
  • Prerequisites for Configuring HDX Insight
  • Troubleshooting
    • Issues Related to ICA parsing
    • Error Counter details
  • Checklist before Contacting Citrix Technical Support
  • Information to collect before Contacting Citrix Technical support
  • Known Issues

Gateway Insight

In the Analytics node is Gateway Insight.

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

Security Insight

The Security Insight dashboard 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 Citrix Docs.

Troubleshooting

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

Citrix CTX224502 NetScaler MAS Troubleshooting Guide

Citrix Blog Post NetScaler Insight Center – Tips, Troubleshooting and Upgrade

See Citrix Docs Troubleshooting Tips. Here are sample issues covered in Citrix Docs:

  • 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 NetScaler MAS

  1. Download the latest Upgrade Package for NetScaler Management and Analytics System. You want the Upgrade Package, not a MAS image.
  2. Login to NetScaler MAS.
  3. Go to System > System Administration.
  4. On the right, in the right pane, click Upgrade NetScaler MAS.
  5. Browse to the Upgrade Package .tgz file, and click OK.
  6. Click Yes to reboot the appliance.



  7. After it reboots, login. The new firmware version will be displayed by clicking your username in the top right corner.

Citrix Federated Authentication Service (SAML) 2402 LTSR

Last Modified: Apr 17, 2024 @ 6:28 am

1,041 Comments

Navigation

This article applies to Federated Authentication Service (FAS) versions 2402, 2203 LTSR CU4, 1912 LTSR CU8, 7.15.9000 (LTSR), and all other versions 7.9 and newer.

Change Log

Overview

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

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

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

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

Requirements:

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

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

Configuration overview:

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

Links:

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

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

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

Also see the Citrix Federated Authentication Service Scalability whitepaper.

Federated Authentication Service Versions

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

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

Install/Upgrade Federated Authentication Service

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

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

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

FAS Group Policy

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

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

FAS 1909+ Configuration

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

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

Here are 1909 and newer GUI configuration instructions:

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

FAS 1906 and older Configuration

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

Here are GUI configuration instructions for FAS 1906 and older:

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

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

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

Certificate Templates

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

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

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

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

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

StoreFront Configuration

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

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

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

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

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

SAML Configuration

SAML Flow

SAML flows like this:

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

Configure the SAML IdP

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

Azure AD as SAML IdP

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


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

ADFS as SAML IdP

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

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

Citrix ADC SAML Configuration

SAML Server/Action

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


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

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

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

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

SAML Policy – Advanced (nFactor) Method

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

SAML nFactor LDAP Group Extraction

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

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

Do the following to configure LDAP Group Extraction.

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

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

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

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

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

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

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

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

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

Configure StoreFront for SAML Citrix Gateway

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

  8. Next step: create Active Directory Shadow Accounts

Native SAML on StoreFront without Citrix ADC

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

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

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

To configure native SAML in StoreFront 3.9 or newer:

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

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

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

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

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

Active Directory Shadow Accounts

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

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

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

Verify FAS

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

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

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