In Authentication, authorization, and auditing application traffic
In Citrix ADC 13.0
In Citrix ADC
In All products
Product documentation
In Authentication, authorization, and auditing application traffic
In Citrix ADC 13.0
In Citrix ADC
In All products
Citrix ADC
Current Release 12.1 11.1
View PDF

Configuring SSO

January 19, 2021
Contributed by: 
C

Configuring Citrix ADC SSO to authenticate by impersonation is simpler than configuring than SSO to authenticate by delegation, and is therefore preferable when your configuration allows it. You create a KCD account. You can use the user’s password.

If you do not have the user’s password, you can configure Citrix ADC SSO to authenticate by delegation. Although more complex than configuring SSO to authenticate by impersonation, the delegation method provides flexibility in that a user’s credentials might not be available to the Citrix ADC appliance in all circumstances.

For either impersonation or delegation, you must also enable integrated authentication on the web application server.

Enable integrated authentication on the web application server

To set up Citrix ADC Kerberos SSO on each web application server that Kerberos SSO manages, use the configuration interface on that server to configure the server to require authentication. Select Kerberos (negotiate) authentication by preference, with fallback to NTLM for clients that do not support Kerberos.

Following are instructions for configuring the Microsoft Internet Information Server (IIS) to require authentication. If your web application server uses software other than IIS, consult the documentation for that web server software for instructions.

To configure Microsoft IIS to use integrated authentication

  1. Log on to the IIS server and open Internet Information Services Manager.
  2. Select the website for which you want to enable integrated authentication. To enable integrated authentication for all IIS web servers managed by IISM, configure authentication settings for the Default website. To enable integrated authentication for individual services (such as Exchange, Exadmin, ExchWeb, and Public), configure these authentication settings for each service individually.
  3. Open the Properties dialog box for the default website or for the individual service, and click the Directory Security tab.
  4. Beside Authentication and Access Control, select Edit.
  5. Disable anonymous access.
  6. Enable Integrated Windows authentication (only). Enabling integrated Windows authentication must automatically set protocol negotiation for the web server to Negotiate, NTLM, which specifies Kerberos authentication with fallback to NTLM for non-Kerberos capable devices. If this option is not automatically selected, manually set protocol negotiation to Negotiate, NTLM.

Set up SSO by impersonation

You can configure the KCD account for Citrix ADC SSO by impersonation. In this configuration, the Citrix ADC appliance obtains the user’s user name and password when the user authenticates to the authentication server and uses those credentials to impersonate the user to obtain a ticket-granting ticket (TGT). If the user’s name is in UPN format, the appliance obtains the user’s realm from UPN. Otherwise, it obtains the user’s name and realm by extracting it from the SSO domain used during initial authentication, or from the session profile.

Note

You cannot add a user name with domain if the user name is already added without domain. If the user name with domain is added first followed by the same user name without domain, then the Citrix ADC appliance adds the user name to the user list.

When configuring the KCD account, you must set the realm parameter to the realm of the service that the user is accessing. The same realm is also used as the user’s realm if the user’s realm cannot be obtained from authentication with the Citrix ADC appliance or from the session profile.

To create the KCD account for SSO by impersonation with a password

At the command prompt, type the following command:


add aaa kcdaccount <accountname> -realmStr <realm>

For the variables, substitute the following values:

  • accountname. The KCD account name.
  • realm. The domain assigned to the Citrix ADC SSO.

Example

To add a KCD account named kcdccount1, and use the keytab named kcdvserver.keytab, you would type the following command:


add aaa kcdAccount kcdaccount1 -keytab kcdvserver.keytab

For information on configuring Kerberos impersonation through the Citrix ADC GUI, see Citrix Support.

Configure SSO by delegation

To configure SSO by Delegation, you need to perform the following tasks:

  • If you are configuring delegation by delegated user certificate, install the matching CA certificates on the Citrix ADC appliance and add them to the Citrix ADC configuration.
  • Create the KCD account on the appliance. The appliance uses this account to obtain service tickets for your protected applications.
  • Configure the Active Directory server.

Note

For more information on creating a KCD account and configuring on the NetScaler appliance, refer to the following topics:

Installing the client CA certificate on the Citrix ADC appliance

If you are configuring Citrix ADC SSO with a client certificate, you must copy the matching CA certificate for the client certificate domain (the client CA certificate) to the Citrix ADC appliance, and then install the CA certificate. To copy the client CA certificate, use the file transfer program of your choice to transfer the certificate and private-key file to the Citrix ADC appliance, and store the files in /nsconfig/ssl.

To install the client CA certificate on the Citrix ADC appliance

At the command prompt, type the following command:


add ssl certKey <certkeyName> -cert <cert> [(-key <key> [-password]) | -fipsKey <fipsKey>][-inform ( DER | PEM )][-expiryMonitor ( ENABLED | DISABLED | UNSET ) [-notificationPeriod <positive_integer>]] [-bundle ( YES | NO )]

For the variables, substitute the following values:

  • certkeyName. A name for the client CA certificate. Must begin with an ASCII alphanumeric or underscore (_) character, and must consist of from one to thirty-one characters. Allowed characters include the ASCII alphanumerics, underscore, hash (#), period(.), space, colon (:), at (@), equals (=), and hyphen (-) characters. Cannot be changed after the certificate-key pair is created. If the name includes one or more spaces, enclose the name in double or single quotation marks (for example, “my cert” or ‘my cert’).
  • cert. Full path name and file name of the X509 certificate file used to form the certificate-key pair. The certificate file must be stored on the Citrix ADC appliance, in the /nsconfig/ssl/ directory.
  • key. Full path name and file name of the file that contains the private key to the X509 certificate file. The key file must be stored on the Citrix ADC appliance in the /nsconfig/ssl/ directory.
  • password. If a private key is specified, the passphrase used to encrypt the private key. Use this option to load encrypted private keys in PEM format.
  • fipsKey. Name of the FIPS key that was created inside the Hardware Security Module (HSM) of a FIPS appliance, or a key that was imported into the HSM.

    Note

    You can specify either a key or a fipsKey, but not both.

  • inform. Format of the certificate and private-key files, either PEM or DER.
  • passplain. Pass phrase used to encrypt the private key. Required when adding an encrypted private-key in PEM format.
  • expiryMonitor. Configure the Citrix ADC appliance to issue an alert when the certificate is about to expire. Possible values: ENABLED, DISABLED, UNSET.
  • notificationPeriod. If expiryMonitor is ENABLED, number of days before the certificate expires to issue an alert.
  • bundle. Parse the certificate chain as a single file after linking the server certificate to its issuer’s certificate within the file. Possible values: YES, NO.

Example

The following example adds the specified delegated user certificate customer-cert.pem to the Citrix ADC configuration along with the key customer-key.pem, and sets the password, certificate format, expiration monitor, and notification period.

To add the delegated user certificate, you would type the following commands:


add ssl certKey customer -cert "/nsconfig/ssl/customer-cert.pem"
-key "/nsconfig/ssl/customer-key.pem" -password "dontUseDefaultPWs!"
-inform PEM -expiryMonitor ENABLED [-notificationPeriod 14]

Creating the KCD account

If you are configuring Citrix ADC SSO by delegation, you can configure the KCD account to use the user’s log-on name and password, to use the user’s log-on name and keytab, or to use the user’s client certificate. If you configure SSO with user name and password, the Citrix ADC appliance uses the delegated user account to obtain a Ticket Granting Ticket (TGT), and then uses the TGT to obtain service tickets for the specific services that each user requests. If you configure SSO with keytab file, the Citrix ADC appliance uses the delegated user account and keytab information. If you configure SSO with a delegated user certificate, the Citrix ADC appliance uses the delegated user certificate.

To create the KCD account for SSO by delegation with a password

At the command prompt, type the following commands:

add aaa kcdAccount <kcdAccount> {-keytab <string>} {-realmStr <string>} {-delegatedUser <string>} {-kcdPassword } {-usercert <string>} {-cacert <string>} [-userRealm <string>]
[-enterpriseRealm <string>] [-serviceSPN <string>]

For the variables, substitute the following values:

  • kcdAccount - A name for the KCD account.This is a mandatory argument. Maximum Length: 31
  • keytab - The path to the keytab file. If specified other parameters in this command need not be given. Maximum Length: 127
  • realmStr - The realm of Kerberos. Maximum Length: 255
  • delegatedUser - Username that can perform kerberos constrained delegation. Maximum Length: 255
  • kcdPassword - Password for Delegated User. Maximum Length: 31

  • usercert - SSL Cert (including private key) for Delegated User. Maximum Length: 255

  • cacert - CA Cert for UserCert or when doing PKINIT backchannel. Maximum Length: 255

  • userRealm - Realm of the user. Maximum Length: 255

  • enterpriseRealm - Enterprise Realm of the user. This should be given only in certain KDC deployments where KDC expects Enterprise username instead of Principal Name. Maximum Length: 255

  • serviceSPN - Service SPN. When specified, this will be used to fetch kerberos tickets. If not specified, Citrix ADC will construct SPN using service fqdn. Maximum Length: 255

Example (UPN Format)

To add a KCD account named kcdaccount1 to the Citrix ADC appliance configuration with a password of password1 and a realm of EXAMPLE.COM, specifying the delegated user account in UPN format (as root), you would type the following commands:


add aaa kcdaccount kcdaccount1 –delegatedUser root
-kcdPassword password1 -realmStr EXAMPLE.COM

Example (SPN Format)

To add a KCD account named kcdaccount1 to the Citrix ADC appliance configuration with a password of password1 and a realm of EXAMPLE.COM, specifying the delegated user account in SPN format, you would type the following commands:


add aaa kcdAccount kcdaccount1 -realmStr EXAMPLE.COM
-delegatedUser "host/kcdvserver.example.com" -kcdPassword password1

Creating the KCD account for SSO by delegation with a keytab

If you plan to use a keytab file for authentication, first create the keytab. You can create the keytab file manually by logging on to the AD server and using the ktpass utility, or you can use the Citrix ADC configuration utility to create a batch script, and then run that script on the AD server to generate the keytab file. Next, use FTP or another file transfer program to transfer the keytab file to the Citrix ADC appliance and place it in the /nsconfig/krb directory. Finally, configure the KCD account for Citrix ADC SSO by delegation and provide the path and file name of the keytab file to the Citrix ADC appliance.

To create the keytab file manually

Log on to the AD server command line and, at the command prompt, type the following command:

ktpass princ <SPN> ptype KRB5_NT_PRINCIPAL mapuser <DOMAIN><username> pass <password> -out <File_Path>

For the variables, substitute the following values:

  • SPN. The service principal name for the KCD service account.
  • DOMAIN. The domain of the Active Directory server.
  • username. The KSA account user name.
  • password. The KSA account password.
  • path. The full path name of the directory in which to store the keytab file after it is generated.
To use the Citrix ADC configuration utility to create a script to generate the keytab file
  1. Navigate to Security > AAA - Application Traffic.
  2. In the data pane, under Kerberos Constrained Delegation, click Batch file to generate Keytab.
  3. In the Generate KCD (Kerberos Constrained Delegation) Keytab Script dialog box, set the following parameters:
    • Domain User Name. The KSA account user name.
    • Domain Password. The KSA account password.
    • Service Principal. The service principal name for the KSA.
    • Output File Name. The full path and file name to which to save the keytab file on the AD server.
  4. Clear the Create Domain User Account check box.
  5. Click Generate Script.
  6. Log on to the Active Directory server and open a command line window.
  7. Copy the script from the Generated Script window and paste it directly into the Active Directory server command-line window. The keytab is generated and stored in the directory under the file name that you specified as Output File Name.
  8. Use the file transfer utility of your choice to copy the keytab file from the Active Directory server to the Citrix ADC appliance and place it in the /nsconfig/krb directory.
To create the KCD account

At the command prompt, type the following command:


add aaa kcdaccount <accountname> –keytab <keytab>

Example

To add a KCD account named kcdccount1, and use the keytab named kcdvserver.keytab, you would type the following commands:


add aaa kcdaccount kcdaccount1 –keytab kcdvserver.keytab

To create the KCD account for SSO by delegation with a delegated user cert

At the command prompt, type the following command:


add aaa kcdaccount <accountname> -realmStr <realm> -delegatedUser <user_nameSPN> -usercert <cert> -cacert <cacert>

For the variables, substitute the following values:

  • accountname. A name for the KCD account.
  • realmStr. The realm for the KCD account, usually the domain for which SSO is configured.
  • delegatedUser. The delegated user name, in SPN format.
  • usercert. The full path and name of the delegated user certificate file on the Citrix ADC appliance. The delegated user certificate must contain both the client certificate and the private key, and must be in PEM format. If you use smart card authentication, you might must create a smart card certificate template to allow certificates to be imported with the private key.
  • cacert. The full path to and name of the CA certificate file on the Citrix ADC appliance.

Example

To add a KCD account named kcdccount1, and use the keytab named kcdvserver.keytab, you would type the following command:


add aaa kcdaccount kcdaccount1 -realmStr EXAMPLE.COM
     -delegatedUser "host/kcdvserver.example.com" -usercert /certs/usercert
     -cacert /cacerts/cacert

Setting up Active Directory for Citrix ADC SSO

When you configure SSO by delegation, in addition to creating the KCDAccount on the Citrix ADC appliance, you must also create a matching Kerberos Service Account (KSA) on your LDAP active directory server, and configure the server for SSO. To create the KSA, use the account creation process on the active directory server. To configure SSO on the active directory server, open the properties window for the KSA. In the Delegation tab, enable the following options: Trust this user for delegation to specified services only and Use any Authentication protocol. (The Kerberos only option does not work, because it does not enable protocol transition or constrained delegation.) Finally, add the services that Citrix ADC SSO manages.

Note

If the Delegation tab is not visible in the KSA account properties dialog box, before you can configure the KSA as described, you must use the Microsoft setspn command-line tool to configure the active directory server so that the tab is visible.

To configure delegation for the Kerberos service account

  1. In the LDAP account configuration dialog box for the Kerberos service account that you created, click the Delegation tab.
  2. Choose “Trust this user for delegation to the specified services only”.
  3. Under “Trust this user for delegation to the specified services only,” choose “Use any authentication protocol”.
  4. Under “Services to which this account can present delegated credentials,” click Add.
  5. In the Add Services dialog box, click Users or Computers, choose the server that hosts the resources to be assigned to the service account, and then click OK.

    Note

    • Constrained delegation does not support services hosted in domains other than the domain assigned to the account, even though Kerberos might have a trust relationship with other domains.
    • Use the following command to create the setspn if a new user is created in active directory: setspn -A host/kcdvserver.example.com example\kcdtest
  6. Back in the Add Services dialog box, in the Available Services list, chooses the services assigned to the service account. Citrix ADC SSO supports the HTTP and MSSQLSVC services.
  7. Click OK.

Points to note when advanced encryptions is used to configure KCD account

  • Sample configuration when keytab is used: add kcdaccount lbvs_keytab_aes256 -keytab “/nsconfig/krb/kcd2_aes256.keytab”
  • Use the following command when keytab has multiple encryption types. The command additionally captures domain user parameters: add kcdaccount lbvs_keytab_aes256 -keytab “/nsconfig/krb/kcd2_aes256.keytab” –domainUser “HTTP/lbvs.aaa.local”
  • Use the following commands when user credential are used: add kcdaccount kslb2_user -realmStr AAA.LOCAL -delegatedUser lbvs -kcdPassword <password>
  • Ensure that the correct domainUser information is provided. You can look for the user logon name in AD.
Configuring SSO
January 19, 2021
Contributed by: 
C
January 19, 2021
Contributed by: 
C

In this article

Site feedback | Privacy and legal terms | Cookie preferences | Consent settings
© 1999- Citrix Systems, Inc. All rights reserved.