Active Directory Federation Service Proxy Integration Protocol compliance
If third-party proxies are to be used in place of the Web Application Proxy, they must support the MS-ADFSPIP protocol which specifies the ADFS and WAP integration rules. ADFSPIP integrates Active Directory Federation Services with an authentication and application proxy to enable access to services located inside the boundaries of the corporate network for clients that are located outside of that boundary.
Prerequisites
To successfully establish Trust between the proxy server and the ADFS farm, review the following configuration in the NetScaler 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 profile <adfs service name> -sessReuse <ENABLED|DISABLED> -tls1 <ENABLED|DISABLED> -SNIEnable <ENABLED|DISABLED> -commonName <name> -denySSLReneg <YES|NO> <!--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 NetScaler appliance.
## Authentication mechanism
The following are the high-level flow of events for the authentication.
1. **Establish Trust with ADFS server** – The NetScaler server establishes Trust with the ADFS server by registering a client certificate. Once the Trust is established, the NetScaler appliance re-establishes the trust after reboot without user intervention.
Upon certificate expiry, you must reestablish the trust by removing and adding the ADFS proxy profile again.
1. **Published endpoints** - The NetScaler 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.
1. **Insert headers to client requests** – When the NetScaler 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
1. **Manage end-user traffic** – End-user traffic is routed securely to the desired resources.
> **Note:**
>
>- NetScaler uses form based authentication.
>
>- NetScaler does not support publishing of an application using the Active Directory Federation Service Proxy Integration Protocol compliance.
## Configure NetScaler to support ADFS server
### Prerequisites
- Configure Context Switching (CS) server as front-end with authentication, authorization, and auditing server behind CS. At the command prompt, type:
```
add cs vserver cs_adfs_proxy SSL a.b.c.d 443 -cltTimeout 180 -AuthenticationHost adfs.ns.com
<!--NeedCopy-->
```
add cs action adfs_proxy_cs_act -targetVserver avs_adfs_proxy
<!--NeedCopy--> ```
```
add cs policy adfs_proxy_policy -rule is_vpn_url -action adfs_proxy_cs_act
<!--NeedCopy--> ```
```
bind cs vserver cs_adfs_proxy -policyName adfs_proxy_policy -priority 100
<!--NeedCopy--> ```
```
bind cs vserver cs_adfs_proxy -lbvserver lb_adfs_proxy
<!--NeedCopy--> ```
-
Add an ADFS service. At the command prompt, type:
add service adfs_service adfs_server SSL 443 set ssl service adfs_service -sslProfile ns_default_ssl_profile_backend bind ssl service adfs_service -certkeyName adfs_trust_cert <!--NeedCopy-->set ssl profile ns_default_ssl_profile_backend -sessReuse ENABLED -tls1 DISABLED -SNIEnable ENABLED -commonName www.server.com -denySSLReneg NO <!--NeedCopy--> -
Add a load balancing virtual server. At the command prompt, type:
add lb vserver lb_adfs_proxy SSL 0.0.0.0 0 -AuthenticationHost adfs.ns.com -Authentication ON -adfsProxyProfile adfs_proxy_profile <!--NeedCopy--> -
Bind the ADFS traffic policy and the ADFS service to the load balancing virtual server. At the command prompt, type:
bind lb vserver lb_adfs_proxy adfs_service bind lb vserver lb_adfs_proxy -policyName adfs_traffic_pol -priority 1 -type REQUEST <!--NeedCopy--> -
Configure an SNIP address:
add ns ip p.q.r.s 255.255.255.0 -type SNIP <!--NeedCopy--> -
Configure traffic actions and policies:
add tm trafficAction adfs_traffic_action -SSO ON -formSSOAction adfs_form_action add tm formSSOAction adfs_form_action -actionURL "/adfs/ls" -userField UserName -passwdField Password -ssoSuccessRule "HTTP.RES.SET_COOKIE.EQ(\"MSISAuth\")" -nameValuePair AuthMethod=FormsAuthentication -submitMethod POST add tm trafficAction adfs_traffic_action -SSO ON -formSSOAction adfs_form_action add tm trafficPolicy adfs_traffic_pol "HTTP.REQ.URL.EQ(\"/adfs/ls/\")" adfs_traffic_action <!--NeedCopy-->
To configure NetScaler to work with ADFS server, you need to do the following:
- Create an SSL CertKey profile key to use with ADFS proxy profile
- Create an ADFS proxy profile
- Associate the ADFS proxy profile to the load balancing virtual server
Create an SSL certificate with private key to use with ADFS proxy profile by using the GUI
-
Navigate to Traffic Management > SSL > Certificates > CA Certificates.
-
In the details pane, click Install. In the Install Certificate dialog box, type the details, such as the certificate and key file name, and then select Certificate Bundle.
-
Click Install, and then click Close.
Create an SSL certificate with private key to use with ADFS proxy profile by using the CLI
At the command prompt, type:
add ssl certKey aaa_local -cert aaa_local.cer -key aaa_local.key
<!--NeedCopy-->
Note: The Certificate file and the key file must be present in the NetScaler appliance.
Create an ADFS proxy profile using the GUI
-
Navigate to Configuration > Security > AAA-Application Traffic > adfsProxy Profile.
-
Click Add on the adfsProxy Profile page.
-
On the Create adfsProxy Profile page, configure the following parameters:
- Name: Assign a name to the ADFS proxy profile.
- User name: This is the name of an account in the directory that would be used to authenticate the trust request from NetScaler acting as a proxy.
- Password: This is the password of the account.
- Server URL: FQDN of the ADFS server.
- Cert Key Name: SSL certificate of the proxy that is registered at the ADFS server.
-
Click Create.
Create an ADFS proxy profile using the 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>
add dns addRec adfs.server.com 10.106.30.151
<!--NeedCopy-->
Example,
add authentication adfsProxyProfile adfs_proxy_profile -userName test -password test -serverURL "https://adfs.server.com" -CertKeyName adfs_trust_cert
<!--NeedCopy-->
Note:
The ADFS proxy and the ADFS server can establish trust only if the certificate is signed by the Certificate Authority of the ADFS server.
Associate the ADFS proxy profile to the load balancing virtual server using the GUI
-
Navigate to Traffic Management > Load Balancing > Virtual Servers, and select an SSL virtual server.
-
Click Edit.
-
In Advanced Settings, click Profiles.
-
Select the ADFS profile created earlier.
-
Click OK and then click Done.
Associate the ADFS proxy profile to the load balancing virtual server using the CLI
In the ADFS deployment, two virtual severs are used, 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 ssl vserver lb_adfs_proxy -sslProfile ns_default_ssl_profile_frontend
<!--NeedCopy-->
Trust renewal support for ADFSPIP
You can renew the trust of the existing certificates that are nearing to expiry or if the existing certificate is not valid. The trust renewal of certificates is done only when the trust is established between NetScaler appliance and ADFS server. To renew the trust of the certificate, you must provide the new certificate.
Important:
Manual intervention is required for trust renewal of new certificates.
The following example lists the steps involved in the certificate trust renewal:
- The NetScaler appliance sends both old (SerializedTrustCertificate) and new (SerializedReplacementCertificate) certificates in POST request to the ADFS server for trust renewal.
- The ADFS server responds with 200 OK success if trust is renewed successfully.
- The NetScaler 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” and the NetScaler appliance keeps using the old certificate.
Note:
You cannot update the certificate key if it is already bound to an ADFS proxy profile.
To configure the trust renewal of certificates by using the CLI
At the command prompt, type:
add ssl certKey <name> -cert <certificate file> -key <key file>
<!--NeedCopy-->
add authentication vserver <name> SSL <ipaddress> <port>
<!--NeedCopy-->
bind ssl vserver <virtual server name> -certkeyName <string>
<!--NeedCopy-->
Example:
add ssl certKey adfs_trust_cert -cert "client/client_rsa_2048.pem" -key "client/client_rsa_2048.ky"
<!--NeedCopy-->
Note:
The certificate must be issued by the Certificate Authority of the ADFS server.
add authentication vserver avs_adfs_proxy SSL 0.0.0.0
<!--NeedCopy-->
bind ssl vserver avs_adfs_proxy -certkeyName aaa_local
<!--NeedCopy-->
Client certificate based authentication on ADFS server
Starting with Windows server 2016, Microsoft introduced a new way of authenticating users when ADFS is accessed through proxy servers. Now, end users can log in with their certificates thereby avoiding the use of a password.
End users often access ADFS through a proxy, especially when they are not in the premises. Therefore, ADFS proxy servers are required to support client certificate authentication through the ADFSPIP protocol.
When ADFS is load balanced using a NetScaler appliance, to support certificate-based authentication at the ADFS server, users need to log in to the NetScaler appliance using the certificate as well. This allows NetScaler to pass the user certificate to ADFS to provide SSO to the ADFS server.
The following diagram represents the 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 NetScaler appliance. You must then bind the certificate authentication policy to the authentication, authorization, and auditing virtual server.
In addition, you must perform the following steps.
-
An extra context switching virtual server with port 49443 must be configured and this context switching virtual server must point to the same load balancing virtual server which is open for all ports, which you have created earlier.
-
The port 49443 must be opened on the NetScaler appliance for authentication.
-
The context switching policy must be bound the same load balancing virtual server with port 443 open that you have created earlier.
-
You must bind the same SSL service that you have created earlier to the load balancing virtual server.
-
If you have already created an SSL profile for the back end, you must use that profile.
At the command prompt, type;
bind ssl vserver <name> -certkeyName <string>
bind ssl vserver <vServerName> -certkeyName <string>
add authentication Policy <policy name> -rule <expression> -action <action name>
bind authentication vserver <name> -policy <name of the policy> -priority <integer>
<!--NeedCopy-->
Example:
bind ssl vserver lb_adfs_proxy -certkeyName aaa_local
set ssl profile ns_default_ssl_profile_frontend -eRSA ENABLED -sessReuse ENABLED -denySSLReneg NONSECURE
bind ssl vserver cs_adfs_proxy -certkeyName aaa_local
add authentication Policy local_pol -rule true -action LOCAL
bind authentication vserver avs_adfs_proxy -policy local_pol -priority 1
<!--NeedCopy-->
For information on configuring client certificate on the NetScaler appliance, see Configure client certificate authentication using advanced policies.