How to Configure NetScaler SAML to Work with Microsoft Active Directory Federation Services 3.0 IDP

How to Configure NetScaler SAML to Work with Microsoft Active Directory Federation Services 3.0 IDP

book

Article ID: CTX133919

calendar_today

Updated On:

Description

This article describes how to set up Security Assertion Markup Language (SAML) Active Directory Federation Services (AD FS) that is configuring NetScaler SAML to work with Microsoft ADFS 3.0 IDP.

Note: This article is not for replacing AD FS Proxy with NetScaler. It is intended to be used when SAML is configured in front of the NetScaler appliance.

Instructions

To set up SAML AD FS, complete the following procedure:

  1. Open the following links and verify if the AD FS is working:
    https://<adfs_fqdn>/adfs/fs/federationserverservice.asmx
    https://<adfs_fqdn >/FederationMetadata/2007-06/FederationMetadata.xml

  2. Verify if the AD FS 3.0 MMC plugin looks like the following screen shot:

    User-added image
    If it appears different then you have to install AD FS 3.0.

  3. Open AD FS 3.0 > Service > Certificates and then configure Service Communication, Token-Decrypting, and Token_signing certificates.

  4. Select the appropriate certificates by clicking on "Certificates" option that can be used for SAML communication. This is the certificate that NetScaler appliance will use when verifying the signed SAML Response from IDP.

  5. Open AD FS 3.0 > Trust Relation Ships > Relaying party Trusts > Add Relaying Party Trust and then configure Relaying Party Trust.

  6. Select the Import Data about the relaying party published online or local network option.

  7. Specify the NetScaler Metadata file location as https://vserver_fqdn>/ns_metadata.xml.

    User-added image

    Note: Metadata file is not created by default. NetScaler administrator has to create the metadata file (ns_metadata.xml) and copy the same at /netscaler/ns_gui/vpn folder by specifying the location as https://<vpnvserver>/ns_metdata.xml.

    OR

    Instead of copying to NetScaler and specifying the URL location, the metadata can be copied to a shared location and accessed.
    The following screen shot shows a sample metadata file.

    User-added image

    Update the following text in the metadata file for the corresponding environment:
    Note: The following is the metadata file in text - https://citrix.sharefile.com/d/sa0c465afb9142ff9 and here is an example that has been filled out - https://citrix.sharefile.com/d/see1f982434a4a7cb. Some of the screen shots will reflect the configuration from the example.

    • IDPLoginPage is the Redirect url

    • KeyName is the signingCertname

    • <lbvs.fqdn.com>/cgi/samlauth is the Login URL or authentication end point

    • lbvserver.fqdn.com is the common name for the certificate of the load balancing virtual server on a NetScaler appliance

  8. Ignore the following error message.

    User-added image

  9. Select the Authorization rules, as shown in the following screen shot:

    User-added image

  10. Verify the Relaying Party data before you complete:

    Encryption and Signature: NetScaler virtual server Server Certificate

    End Points: https://<vserver_fqdn>/cgi/samlauth 

    User-added image

  11. Complete the Relaying Party Trust Wizard.

  12. Select the new Relaying Party Trust and edit the Properties.

  13. Select Advanced.

  14. Select the Secure hash algorithm as SHA-1, as shown in the following screen shot:

    User-added image

    Note: An Enhancement #440382 raised to support SHA256 hashing algorithm. This is available in version 10.5 build 55.x or above.

  15. Select the Encryption tab, remove all Certificates, if there are any listed.
    Note: Encrypted Assertions are currently not supported.

    User-added image

  16. Select Endpoints and make sure it looks similar to the following screen shot:

    User-added image

  17. Select Identifiers, and make sure it looks similar to the following screen shot:

    User-added image

  18. Select Signature and make sure it looks similar to the following screen shot:

    User-added image

  19. Right-click the Relaying Party trust and select Edit Claim Rules.

  20. Select Transform Rule > Add Claim Rule > Claim Rule Template> Send LDAP Attributes as Claims.

  21. Type a name for the rule.

  22. Select Active Directory for Attribute Store.

  23. Select the LDAP attribute: <AD parameters>.

  24. Select the Out Going Claim Rule as Name ID.
    Note: Currently only Out Going Claim Rule: Name ID is supported.

    User-added image

  25. For the second rule, select Send claims using a custom rule.

  26. Specify a URL to redirect the network traffic when the user logs out by creating a custom claim rule which sends an additional logoutURL attribute.
    The custom rule is as follows:

    => issue(Type = "logoutURL", Value = "https://<adfs_fqdn>/adfs/ls/", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/attributename"] = "urn:oasis:names:tc:SAML:3.0:attrname-format:unspecified");

    User-added image

Configuration on a NetScaler Appliance

To configure the NetScaler appliance, complete the following procedure:

  1. Download AD FS signing certificate.

  2. Run the following command to add a Certificate key:
    add ssl certKey adfs-signing -cert adfs-signing.cer

  3. Run the following command to add an SAML action:
    add authentication samlAction samladfs -samlIdPCertName <ipd certificate> -samlSigningCertName <sp certificate> -samlRedirectUrl "https://<adfs_fqdn >/adfs/ls/" -samlUserField "Name ID" -samlIssuerName <issuername/relaying party identifier> 

    add authentication samlPolicy saml_true ns_true samladfs

    ex: add authentication samlAction samladfs -samlIdPCertName adfs.coolidge.netweb -samlSigningCertName lbiis.coolidge.net -samlRedirectUrl "https://adfs.coolidge.net/adfs/ls/FormsSignIn.aspx" -samlUserField "Name ID" -samlIssuerName "https://lbiis.coolidge.net"

    • sp certificate is the name of the certificate key pair added as a SAML signing certificate.
    • First occurrence of <certname> refers to the certificate name of SAML IDP certificate and second occurrence refers to the SAML signing certificate.
    • samlIDPCertname specifies the certificate the NetScaler appliance uses when verifying the signed SAML Response from IDP. It will be a public Signing certificate of IDP.
    • samlSigningCert specifies the certificate the NetScaler appliance uses to sign the SAML Request going to IDP. Therefore, the administrator has to configure the same certificate in the NetScaler Metadata file. Most IDPs extract Service Provider information from the metadata file including the certificate. If IDP supports the manual configuration, metadata file is not required. The administrator has to configure this certificate as Service Provider certificate.

  4. Add a aaa-tm server:
    add authentication vserver aaa.coolidge.net SSL 192.168.1.32 443

  5. Bind the SAML policy:
    bind authentication vserver aaa.coolidge.net -policy saml_true -priority 100

  6. Add a load balancing virtual server:
    add lb vserver lbvserver_iis_ssl SSL 192.168.1.31 443 -persistenceType NONE -cltTimeout 180 -AuthenticationHost "https://aaa.coolidge.net" -Authentication ON -authnVsName aaa.coolidge.net

  7. Add DNS names:
    192.168.1.32 > aaa.coolidge.net
    192.168.1.31 > lbiis.coolidge.net

  8. The following NetScaler configuration should also be completed:
    Add SSL certificates
    Add services
    Bind services

 

Issue/Introduction

This article describes how to set up Security Assertion Markup Language (SAML) Active Directory Federation Services (AD FS).

Additional Information

To configure AAA virtual server, refer to Citrix Documentation - Configuring the Authentication Virtual Server.

AD FS 3.0 Installation Document: - AD FS 3.0 Installation Document

The following table describes the parameters used to create an SAML action.
add authentication SAMLAction <name> -samlIdPCertName <certname> -samlRedirectUrl <IDP URL> -samlUsernameField –samlSigningCert <certname> -samlIssuerName <issuer_name> -samlRejectUnsignedAssertion <TRUE/FALSE>

Parameter

Description

certname

It is the public key corresponding to the private key at the Identity Provider (IdP). It is required for decrypting or verifying the SAML assertion. This can come in the assertion as keyInfo, but is not currently used. Add this information to the NetScaler appliance using the add certkey command.

Redirect url

It is the url of the authentication end point (IdP). Unauthenticated users are redirected to this URL.

Username field

It can be used to extract the username if the IdP sends the username in other than <NameIdentifier> tag of <Subject> tag. In most scenarios, this need not be configured. Depending on the use cases, this can be removed.

signingCertname

It is the certificate key of AAA/Gateway virtual server that is used to sign the authentication request to the IdP. If signingCertName is not configured, then assertion is either sent unsigned or authentication is rejected as per the samlRejectUnsignedAssertion parameter.

samlIssuerName

It is the string to be used in sending the authentication request. Every IdP expects a unique name in the issuer field to signify the authority which sent this assertion. A few IdPs ignore this but a few rely on this field to search the metadata corresponding to this Service Provider.

samlRejectUnsignedAssertion

It is a knob to accept or reject unsigned assertions from the IdP. This parameter gives flexibility to the administrator or user to verify the connectivity or basic functioning of the Service Provider and IdP. This knob is also used when sending the authentication request out. If signingCert is not configured and if this knob is false, the unsigned authentication request is sent. Otherwise, the SAML authentications are rejected and fall back to forms-based authentication.

Errors and Debugging

Places to look for information:

NetScaler

Live tracing:
nsconmsg -d current -g saml
cat /tmp/aaad.debug
tail -f /var/log/ns.log

Historical:
nsconmsg -d stats -g saml
cat /var/log/ns.log

Windows

ADFS 3.0 error log:
w3.woodsnetworks.com/index.php/2013/02/adfs-2-0-error-after-successful-login/
Issuername / identifier mismatch:
ID4037: The key needed to verify the signature could not be resolved from the following security key identifier 'SecurityKeyIdentifier

Incorrect IDP certificate configured on NetScaler

Browser error:
SAML Assertion verification failed; Please contact your administrator
/var/log/ns.log error:
Feb 12 15:07:07 <local0.err> 192.168.1.65 02/12/2015:14:07:07 GMT ns 0-PPE-0 : AAATM Message 1438 0 :  "Error while trying to verify the signature"
Feb 12 15:07:07 <local0.err> 192.168.1.65 02/12/2015:14:07:07 GMT ns 0-PPE-0 : AAATM Message 1439 0 :  "Verification of SAML assertion resulted in failure 917511"

Powered by Wolken Software