Configure single sign-on

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 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 <accountname> -delegatedUser root -kcdPassword <password> -realmStr <realm>
<!--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 KCD account 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, choose 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