How to Configure Single Sign-On on NetScaler Gateway with Smart Card PIN-Prompt

Description

This article describes how to configure Single Sign-On (SSO) on NetScaler Gateway with Smart Card Pin-Prompt.

When a Web Interface site is configured for NetScaler Gateway authentication, the user has the option of choosing either explicit authentication or a smart card.

When choosing to use a smart card, there are two possible choices:

Prompt users for a PIN

Enable smart card pass-through

The configuration for enabling smart card pass-through is described in CTX124603 – How to Configure Smart Card Single Sign-On with Access Gateway Enterprise Edition.

The requirements for the configuration that prompts users for a PIN is as follows:

Smart Card middleware must be installed on XenApp servers (or the Virtual Desktop Agent).
Smart Card device drivers must be installed on the XenApp server (or the Virtual Desktop Agent).
NetScaler Gateway must NOT use the User Principal Name (UPN) for SSO. This is a limitation of Web Interface which does not support UPN for Pin-Prompt authentication. This means that the user certificate in the smart card must have the pre-Windows 2000 username identified properly or the UPN must be a valid Active Directory user logon name.

Notes:

In the case of DoD CaC cards, there is nothing in the certificate matching the user’s pre-Windows 2000 logon name in Active Directory. The only value matching Active Directory is the UPN which matches the user logon name. Because of that follow the CaC procedure in the following section.
Citrix Receiver supports MacOS 12.1, iOS and Android with Smart Cards.

Instructions

To configure SSO, complete one of the the following procedures:

Non-CaC Procedure
CaC Procedure

Non-CaC Procedure

On NetScaler Gateway, create an NetScaler Gateway virtual server with a proper server certificate and add all relevant root certificates. The root certificates must be the ones that issued the client certificates in the smart card and must be added as a CA certificate:
Create a type certificate authentication policy. You must create a type certificate server profile and select the correct username field. This MUST NOT BE SubjectAltName:PrincipalName.
The value of this field changes based on how the user certificate is configured. The following example demonstrates how the user "certuser" is identified in the subject field on the user certificate in the smart card:

With the preceding example, the server profile would be configured as the following screen shot demonstrates:

Important: If there are multiple CN fields in the certificate's subject, the first one from top down is used and that might not be the correct one.
Create a session policy and session profile set to ICAPROXY ON and enter the Web Interface site URL and the SSO domain. The SSO domain is crucial and it must be the one associated with the user account.

In this particular example, the information passed to Web Interface for the user account is SAMPA\nesteves, which matches the Active Directory configuration.
You MUST allow Security Identifier enumeration by the Citrix's XML service. Follow the configuration setup as shown in the following article for XenApp and XenDesktop 4:
CTX117489 – How to Configure User SID Enumeration in the XML Service
For XenDesktop 5, follow the procedure in CTX129968 – How to Configure User Secure Identifier (SID) Enumeration in XenDesktop 5 ***

As a result of this configuration, users are prompted for the PIN once by the browser, once by the XenApp/Desktop client and once again by the VDA/XenApp server. If launching applications published on different XenApp servers, then each server prompts for the PIN separately.

CaC Procedure

On NetScaler Gateway, create a NetScaler Gateway virtual server with a proper server certificate and add all relevant root certificates. The root certificates must be the ones that issued the client certificates in the smart card and must be added as a CA certificate:
Create a certificate authentication policy and bind as your primary Authentication. You must create a type certificate server profile and select the username field to be SubjectAltName:PrincipalName.
Create another authentication policy with a LDAP profile for your proper domain controller. Make sure Authentication is unchecked and SSO attribute is samaccountname. Bind the policy as the secondary authentication policy.
Create a session policy and session profile set to ICAPROXY ON and enter the Web Interface site URL and the SSO domain. The SSO domain is crucial and it must be the one associated with the user account.
Go to the Client Experience tabs and set the Credential Index to be SECONDARY.

In this particular example, the information passed to Web Interface for the user account is SAMPA\nesteves, which matches the Active Directory configuration.
You MUST allow Security Identifier enumeration by the Citrix's XML service. Follow the configuration setup in:
Citrix Documentation - Web Interface 5.4
For XenDesktop 5, follow the procedure in CTX129968 – How to Configure User Secure Identifier (SID) Enumeration in XenDesktop 5 ***.

As a result of this configuration, users are prompted for the PIN once by the browser, once by the XenApp/Desktop client and once again by the VDA/XenApp server. If launching applications published on different XenApp servers, then each server prompts for the PIN separately.

Environment

Caution! Using Registry Editor incorrectly can cause serious problems that might require you to reinstall your operating system. Citrix cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk. Be sure to back up the registry before you edit it.

Issue/Introduction

This article describes how to configure Single Sign-On (SSO) on NetScaler Gateway with Smart Card Pin-Prompt.

Welcome to "KB Articles"