How-To's

Integrating the NetScaler Gateway with Microsoft Active Directory Federated Services

After combing through documentation from a few sources, I wanted to write down exactly how to properly integrate a Citrix NetScaler Gateway virtual server with any of the Microsoft identity and federation services (specifically AD FS and Azure AD).  Reason being, there is no definitive article on how to do it, and none .  After some blood, sweat, tears, and a few “Malformed SAML Assertion” errors,  I was able to have a working configuration for both AD FS.

For reference, this has been tested on NetScaler 11.x and 12.x, using AD FS 3.0 for Windows Server 2012 R2. This does not go in depth on how to configure a virtual server on a NetScaler device, nor any advanced options in AD FS.

Prerequisites

  • Obtain an export of the AD FS signing certificate from the AD FS server. The certificate should be in clear text .cer format.
  • Obtain an export of the server certificate for the NetScaler Gateway Virtual Server in pkcs format.

Configuring the NetScaler

  1. Upload the AD FS signing certificate that was exported previously to the NetScaler appliance.
    • Expand Menu>Traffic Management>SSL>Certificates>CA Certificates
    • Install
    • Provide a name the certificate. This name will be used when linking this certificate to the SAML authentication server.
    • Choose File>Local and point to the location of the exported ADFS signing certificate.
  2. Create a new SAML Authentication Server that will send all requests to AD FS.
    • Expand Menu>NetScaler Gateway>Policies>Authentication>SAML
      Servers, and Add
    • Name – Create a unique name for the server.
    • IDP Certificate Name – Select the name of the signing certificate from ADFS that was uploaded in the previous step.
    • Redirect URL- https://FQDN_FOR_ADFS/adfs/ls
    • Signout URL- https://FQDN_FOR_ADFS/adfs/ls?wa=wsignout1.0
    • User Field – Name ID
    • Signing Certificate Name – Name of the server certificate for the NetScaler Gateway Virtual Server.
    • Issuer Name – FQDN of the NetScaler Gateway Virtual Server
    • Reject Unsigned Assertion – ON
    • SAML Binding – POST
    • Two Factor – On or Off depending on whether additional authentication methods will be used on the NetScaler Gateway authentication policies.
    • Assertion Consumer Service Index – 255
    • Attribute Consuming Service Index – 1
    • Signature Algorithm – SHA256
    • Digest Method – SHA256
  3. Create a new SAML Authentication Policy for the Authentication Server just configured
    • Expand Menu>NetScaler Gateway>Policies>Authentication>SAML
    • Policies, and Add
    • Name – Create a unique name for the policy.
    • Server – Select the SAML authentication server created in the previous step.
    • Expression – Provide an expression for this policy. Default expression: ns_true
  4. Link this policy to the NetScaler Gateway Virtual Server.
    • Expand Menu>NetScaler Gateway>Virtual Servers
    • the appropriate Virtual Server and Edit.
    • In Basic Authentication, +
    • Choose Policy – SAML
    • Choose Type – Primary.  SAML authentication can only be a primary authentication type.
    • Select Policy – Select the SAML Authentication Policy created in the previous step.
    • Priority – Assign a priority to the policy. If it is the only primary policy, leave it default.
    • Bind.

Configuring AD FS

  1. Create a new Relying Party Trust
    • Open the ADFS management console.
    • Expand Trust Relationships>Relying Party Trusts
    • Add Relying Party Trust
    • Enter the configuration wizard
    • Start
    • Select Data Source: Enter data about the relying party trust manually and Next.
    • Specify Display Name: Enter a unique display name for the trust i.e. NetScaler Gateway and Next.
    • Choose Profile: AD FS Profile and Next.
    • Configure Certificate: Skip token encryption certificate. Next.
    • Configure URL: Skip and Next.
    • Configure Identifiers: https://FDQN of NetScaler Gateway Virtual Server
    • Next.
    • Configure Multi-Factor Authentication Now?: Optional. Configure or skip and Next.
    • Choose Issuance Authorization Rules: Choose the best option that reflects how you want to configure the claims rules of the trust, or leave Permit All as default.
    • Next until trust is added.
  2. Complete and Validate the Relying Trust Configuration Properties
    • Open the ADFS management console.
    • Expand Trust Relationships>Relying Party Trusts
    • Right the trust created in the previous step and Properties.
    • Monitoring: Leave empty.
    • Identifiers: Validate that the FQDN for the NetScaler Gateway Virtual Server is listed as a Relying Party Identifier.
    • Encryption: Should not contain any values.
    • Signature: Add and Select the server certificate for the NetScaler Gateway Virtual Server exported in the prerequisites.
    • Accepted Claims: Leave empty.
    • Organization: Leave empty.
    • Endpoints: Add SAML Endpoint
      • Type: SAML Assertion Consumer
      • Binding: POST
      • Index: 1
      • Trusted URL: https://FDQN of NetScaler Gateway Virtual Server/cgi/samlauth
    • Proxy Endpoints: Leave empty.
    • Notes: Enter any notes regarding this trust.
    • Advanced: Secure Hash Algorithm: SHA-256
    • Apply and OK
  3. Complete and Validate the Relying Trust Configuration Claims Rules
    • Open the ADFS management console.
    • Expand Trust Relationships>Relying Party Trusts
    • Right the trust created in the previous step and Edit Claims Rules.
    • Issuance Transform Rules: Add Rule
      • Choose Rule Type: Claim Rule Template – Send LDAP Attributes as Claims.
      • Attribute Store: Active Directory
      • LDAP Attribute: User-Principal-Name
      • Outgoing Claim Type: Name ID
      • OK

Pointers:

You can assign as many different endpoints to the Relying Trust as you want. What this means is that if you create additional NetScaler Gateway Virtual Servers, or if you create a non-routable authentication server that utilizes this SAML authentication policy and assign it to content switch virtual servers, you can add the content switch virtual server FQDN as an endpoint to this relying trust: https://FDQN of NetScaler Content Switch Virtual Server/cgi/samlauth , then increment the Index by 1.

 

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s