Citrix ADC

Active Directory Federation Service Proxy Integration Protocol compliance

You can use third party proxies instead of the web application proxy. In such cases, ensure that the third party proxy supports the MS-ADFSPIP protocol. This protocol specifies the ADFS and WAP integration rules. ADFSPIP integrates Active Directory Federation services with an authentication and application proxy. This integration enables clients located outside the corporate network to access the services.

ADFSPIP diagram

Prerequisites

To successfully establish Trust between the proxy server and the ADFS farm, review the following configuration in the Citrix ADC appliance:

  • Create an SSL profile for the back end and enable SNI in the SSL profile. Disable SSLv3/TLS1. At the command prompt, type the following command:

     add ssl profile <new SSL profile> -sniEnable ENABLED -ssl3 DISABLED -tls1 DISABLED -commonName <FQDN of ADFS>
     <!--NeedCopy-->
    
  • Disable SSLv3/TLS1 for the service. At the command prompt, type the following command:

     set ssl service <adfs service name> -sslProfile ns_default_ssl_profile_backend
     <!--NeedCopy-->
    
  • Enable SNI extension for back-end server handshakes. At the command prompt, type the following command:

     set vpn parameter –backendServerSni ENABLED
    
     set ssl parameter -denySSLReneg NONSECURE
     <!--NeedCopy-->
    

Important:

For Home Realm Discovery (HRD) scenarios where authentication must be offloaded to the ADFS server, Citrix recommends you disable both authentication and SSO on the Citrix ADC appliance.

Authentication mechanism

The following are the high-level flow of events for the authentication.

  1. Establish Trust with the ADFS server – The Citrix ADC server establishes trust with the ADFS server by registering a client certificate. Once the Trust is established, the Citrix ADC appliance re-establishes the trust after reboot without user intervention. Upon certificate expiry, you must reestablish the trust by removing and adding an ADFS proxy profile again.

  2. Published endpoints - The Citrix ADC appliance automatically fetches the list of published endpoints on the ADFS server post trust establishment. These published endpoints filter the requests forwarded to the ADFS server.

  3. Insert headers to client requests – When the Citrix ADC appliance tunnels client requests, the HTTP headers related to ADFSPIP are added in the packet while sending them to the ADFS server. You can implement access control at the ADFS server based on these header values. The following headers are supported.

    • X-MS-Proxy
    • X-MS-Endpoint-Absolute-Path
    • X-MS-Forwarded-Client-IP
    • X-MS-Proxy
    • X-MS-Target-Role
    • X-MS-ADFS-Proxy-Client-IP
  4. Manage end-user traffic – End-user traffic is routed securely to the required resources.

    Note

    The Citrix ADC appliance uses form-based authentication.

Configure the Citrix ADC appliance to support the ADFS server

Prerequisites

  • Configure the Context Switching (CS) server as the front-end with authentication, authorization, and auditing server behind context switching. At the command prompt, type:

     add cs vserver <cs vserver name> SSL 10.220.xxx.xx 443
     -cltTimeout 180 -AuthenticationHost <adfs server hostname> -Authentication OFF -persistenceType NONE
     <!--NeedCopy-->
    
     add cs action <action name1> -targetLBVserver <lb vserver name>
     <!--NeedCopy-->
    
    
     add cs action <action name2> -targetLBVserver <lb vserver name>
     <!--NeedCopy-->
    
     add cs policy <policy name1> -rule " http.req.url.contains(\"/adfs/services/trust\") || http.req.url.contains(\"federationmetadata/2007-06/federationmetadata.xml\")" -action <action name1>
     <!--NeedCopy-->
    
     add cs policy <policy name2> -rule "HTTP.REQ.URL.CONTAINS(\"/adfs/ls\")" -action <action name2>
     <!--NeedCopy-->
    
     bind cs vserver <cs vserver name> -policyName <policy name1> -priority 100
     <!--NeedCopy-->
    
     bind cs vserver <cs vserver name> -policyName <policy name2> -priority 110
     <!--NeedCopy-->
    
     bind cs vserver <cs vserver name> -lbvserver <lb vserver name>
     <!--NeedCopy-->
    
  • Add ADFS service. At the command prompt, type:

     add service <adfs service name> <adfs server ip> SSL 443
     <!--NeedCopy-->
    
     set ssl service <adfs service name> -sslProfile ns_default_ssl_profile_backend
     <!--NeedCopy-->
    
  • Add a load balanced virtual server. At the command prompt, type:

     add lb vserver <lb vserver name> SSL 0.0.0.0 0
     <!--NeedCopy-->
    
     set ssl vserver <lb vserver name> -sslProfile ns_default_ssl_profile_frontend
     <!--NeedCopy-->
    
  • Bind the service to the load balanced server. At the command prompt, type:

     bind lb vserver <lb vserver name> <adfs service name>
     <!--NeedCopy-->
    

To configure the Citrix ADC appliance to work with the ADFS server you need to do the following:

  1. Create an SSL CertKey profile key to use with the ADFS proxy profile.
  2. Create an ADFS proxy profile.
  3. Associate the ADFS proxy profile to the LB virtual server.

Create an SSL certificate with private key to use with the ADFS proxy profile

At the command prompt, type:

    add ssl certkey <certkeyname> –cert <certificate path> -key <keypath>
<!--NeedCopy-->

Note: The Certificate file and the key file must be present in the Citrix ADC appliance. Create an ADFS proxy profile using CLI

At the command prompt, type:

add authentication adfsProxyProfile  <profile name> -serverUrl <https://<server FQDN or IP address>/> -username <adfs admin user name> -password <password for admin user> -certKeyName <name of the CertKey profile created above>
<!--NeedCopy-->

Where;

profile name – Name of the AFDS proxy profile to be created

serverUrl – Fully qualified domain name of the ADFS service including protocol and port. For example, https://adfs.citrix.com

Username – User name of an admin account that exists on ADFS server

password – Password of the admin account used as user name

certKeyName – Name of the previously created SSL CertKey profile

Associate the ADFS proxy profile to the load balancing virtual server using CLI

In the ADFS deployment, two load balancing virtual severs are required, one for the client traffic and the other one for metadata exchange. The ADFS proxy profile must be associated with the load balancing virtual server that is front-ending the ADFS server.

At the command prompt, type:

set lb vserver <adfs-proxy-lb> -adfsProxyProfile <name of the ADFS proxy profile>
<!--NeedCopy-->

Trust renewal support for ADFSPIP

You can renew the trust of the existing certificates that are about to expire or if the existing certificate is not valid. The trust renewal of certificates is done only when the trust is established between the Citrix ADC appliance and the ADFS server. To renew the trust of the certificate, you must provide the new certificate.

The following example lists the steps involved in the certificate trust renewal:

  1. The Citrix ADC appliance sends both the old (SerializedTrustCertificate) and the new (SerializedReplacementCertificate) certificates in POST request to the ADFS server for trust renewal.
  2. The ADFS server responds with 200 OK success if trust is renewed successfully.
  3. The Citrix ADC appliance updates the state as “ESTABLISHED_RENEW_SUCCESS” if the trust renewal is successful. If the trust renewal fails, the state is updated as “ESTABLISHED_RENEW_FAILED”. The Citrix ADC appliance then uses the old certificate.

Note

You cannot update the certificate key if the certificate key is bound to an ADFS proxy profile.

To configure the trust renewal of certificates by using the CLI

At the command prompt, type:

set authentication adfsProxyProfile <name> [-CertKeyName <string>]
<!--NeedCopy-->

Example:

set authentication adfsProxyProfile adfs_2 –CertKeyName ca_cert1
<!--NeedCopy-->

Trust renewal of new certificates

Manual intervention is required when trust renewal is needed. Trust renewal is needed when a certificate is about to expire or the admin wants to change certificates. These certificates can be self-signed certificates or certificates generated by the admin with the same details as the previous certificates. To create a certificate, complete the following steps.

  1. Create an SSL CertKey profile key to use with the ADFS proxy profile.
  2. Create an ADFS proxy profile.
  3. Associate the ADFS proxy profile to the load balancing virtual server.

    For details, see Create a certificate signing request and use SSL certificates on a Citrix ADC appliance.

After you create the certificate, you can set the certificate by using the following CLI command.

set authentication adfsProxyProfile <name> [-CertKeyName <string>]
<!--NeedCopy-->

Client certificate based authentication on the ADFS server

Starting with Windows server 2016, Microsoft introduced a new way of authenticating users when ADFS is accessed through proxy servers. End-users can log in with their certificates and not password.

End-users often access ADFS through a proxy, especially when they are outside the corporate network. The ADFS proxy servers are required to support client certificate authentication through the ADFSPIP protocol.

When ADFS is load balanced using a Citrix ADC appliance, users must log in to the Citrix ADC appliance using the certificate as well. The user must log in to support certificate based authentication at the ADFS server. The Citrix ADC appliance then passes the user certificate to ADFS to provide single sign-on to the ADFS server.

The following diagram displays the client certificate authentication flow.

Client certificate authentication flow

Configure SSO for ADFS server using client certificate

To configure SSO for the ADFS server using the client certificate, you must first configure the client certificate authentication on the Citrix ADC appliance. Then bind the certificate authentication policy to the authentication, authorization, and auditing virtual server.

At the command prompt, type;

add authentication certAction <action name>

add authentication Policy <policy name> -rule <expression> -action <action name>

add authentication policylable <label Name>

bind authentication policylabel <label Name> -policyName <name of the policy> -priority<integer>

<!--NeedCopy-->

Example:

add authentication certAction adfsproxy-cert

add authentication Policy cert1 -rule TRUE -action adfsproxy-cert

add authentication policylable certfactor

bind authentication policylabel certfactor –policyName cert1 –priority 100

<!--NeedCopy-->

For information on configuring the client certificate, see Configure client certificate authentication using advanced policies.

Active Directory Federation Service Proxy Integration Protocol compliance