Product Documentation

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

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 <accountname> -delegatedUser root -kcdPassword <password> -realmStr <realm>

For the variables, substitute the following values:

  • accountname. A name for the KCD account.
  • password. A password for the KCD account.
  • realm. The realm of the KCD account, usually the domain for which SSO is active.</span>

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 onto 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 username.
  • 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 username.
    • 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 need to 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 will manage.

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

  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.