Configure single sign-on

Configuring Citrix ADC single sign-on (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>

<!--NeedCopy-->

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

<!--NeedCopy-->

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:

• Handling authentication, authorization and auditing with Kerberos/NTLM

• How Citrix ADC implements Kerberos for client authentication

• Configuring kerberos authentication on the Citrix ADC appliance

Installing the client CA certificate on the Citrix ADC appliance

If you are configuring the 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 )]

<!--NeedCopy-->

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. Passphrase 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, the 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]

<!--NeedCopy-->

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.

Note:

For cross-realm, the servicePrincipalName of the delegated user must be in the format host/<name>. If it is not in this format, change the servicePrincipalName of the delegated user <servicePrincipalName> to host/<service-account-samaccountname>. You can check the attribute of the delegated user account in the domain controller. One method to change is to change the delegated user’s logonName attribute.

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

At the command prompt, type the following commands:

add aaa kcdAccount <kcdAccount> {-realmStr <string>} {-delegatedUser <string>} {-kcdPassword } [-userRealm <string>]
[-enterpriseRealm <string>] [-serviceSPN <string>]
<!--NeedCopy-->

For the variables, substitute the following values:

• kcdAccount - A name for the KCD account. This is a mandatory argument. Maximum Length: 31
• realmStr - The realm of Kerberos. Maximum Length: 255
• delegatedUser - The user name that can perform kerberos constrained delegation. The delegated user name is derived from the servicePrincipalName of your domain controller. For cross-realm, the servicePrincipalName of the delegated user must be in the format host/<name>. Maximum Length: 255.
• kcdPassword - Password for Delegated User. Maximum Length: 31
• userRealm - Realm of the user. Maximum Length: 255
• enterpriseRealm - Enterprise Realm of the user. This is given only in certain KDC deployments where KDC expects Enterprise user name instead of Principal Name. Maximum Length: 255
• serviceSPN - Service SPN. When specified, this is used to fetch kerberos tickets. If not specified, Citrix ADC constructs SPN using the 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

<!--NeedCopy-->

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

<!--NeedCopy-->

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.

Note:

For cross-realm, if you want to get the Keytab file as part of the KCD account, use the following command for the updated delegated user name.

In the domain controller, create an updated Keytab file.

ktpass /princ <servicePrincipalName-with-prefix<host/>Of-delegateUser>@<DC REALM in uppercase> /ptype KRB5_NT_PRINCIPAL /mapuser <DC REALM in uppercase>\<sAMAccountName> /pass <delegatedUserPassword> -out filepathfor.keytab

The filepathfor.keytab file can be placed in the Citrix ADC appliance and can be used as part of the Keytab configuration in the ADC KCD account.

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>
<!--NeedCopy-->

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>
<!--NeedCopy-->

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
<!--NeedCopy-->

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>
<!--NeedCopy-->

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 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
<!--NeedCopy-->

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

Configuration changes to enable KCD to support child domains

If the KCD account is configured with samAccountName for -delegatedUser, KCD does not work for users accessing services from child domains. In this case, you can modify the configuration on the Citrix ADC appliance and the Active Directory.

• Change service account <service-account-samaccountname> (which is configured as delegateUser on the KCD Account) logon name on AD in host/<service-account-samaccountname>.<completeUSERDNSDOMAIN> format (for example, host/svc_act.child.parent.com).

  You can change the service account manually or by using the ktpass command. The ktpass automatically updates the service account.

  ktpass /princ host/svc_act.child.parent.com@CHILD.PARENT.COM /ptype KRB5_NT_PRINCIPAL /mapuser CHILD\sv_act /pass serviceaccountpassword -out filepathfor.keytab

• Modify delegatedUser in KCD account on the Citrix ADC appliance.
• Modify the -delegatedUser parameter in the KCD account as host/svc_act.child.parent.com

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

• Sample configuration when keytab is used: add kcdaccount lbvs_keytab_aes256 -keytab "/nsconfig/krb/kcd2_aes256.keytab"
• Sample command when keytab has multiple encryption types. The command also captures domain user parameters: add kcdaccount lbvs_keytab_aes256 -keytab "/nsconfig/krb/kcd2_aes256.keytab" –domainUser "HTTP/lbvs.aaa.local”
• Sample command when user credentials are used: add kcdaccount kslb2_user -realmStr AAA.LOCAL -delegatedUser lbvs -kcdPassword <password>

Domain user information

When advanced encryption types are used for Kerberos SSO, ensure that the correct domain user information is provided. You can get the information about the user login name from Active Directory.

When configuring Citrix ADC SSO using Kerberos delegation

When advanced encryption types are used for Kerberos SSO using delegation, the delagatedUser parameter of the add aaa kcdaccount command must be the service principal name (SPN) of the user. The service principal name is case sensitive.

To know the service principal name of a user, use the setspn -L <domain\user> command on the Active Directory domain controller. For example, setspn -L EXAMPLE\username

To set the service principal name, use the setspn command on the Active Directory domain controller. To create a keytab file, use the ktpass command on the Active Directory domain controller. The following is an example of how to do so:

• setspn: setspn -S host/username.example.com EXAMPLE\username
• keytab: ktpass /princ host/username.example.com@EXAMPLE.COM /ptype KRB5_NT_PRINCIPAL /mapuser EXAMPLE.COM\username /pass XXXX /crypto AES256-SHA1 -out <pathto.keytab.file>

Once the above actions are performed on Active Directory, update the KCD account with the configured SPN by using the add kcdaccount or the setkcdaccount commands on the Citrix ADC CLI.

To view the SPN of the specific user account, navigate to the User Properties section of Active Directory.

When configuring Citrix ADC SSO using Kerberos impersonation

When advanced encryption types are used for Kerberos SSO using impersonation, ensure that the SSO credentials are used with the correct service principal name of the end user. If the end user login credentials do not work with a Kerberos SSO, then configure the appropriate user expression to set the SSO user name.

When the user principal name is the correct service principal name of the end user on Active Directory, then:

• Use the ssoNameAttribute parameter in the LDAPAction command to set the SSO user name if LDAP authentication is used for end user login.

  Example: set authentication ldapAction ldap_act -ssoNameAttribute userPrincipalName

• Use the userExpression parameter in the trafficAction command if any other authentication method is used for user login. For example, if user attribute1 has the user principal name stored, then you can use AAA.USER.ATTRIBUTE(1) with the traffic action.

  Example: add tm traffic action traf_act -userExpression AAA.USER.ATTRIBUTE(1)