SAML is an authentication method which allows the Client to authenticate to a trusted third party before accessing protected resources.

For a SAML setup, the authenticating party is called the Identity Provider (IdP) and the resource that the user is trying to access is called the Service Provider.
The SAML process can work in 2 separate ways:
    1) IdP Initiated SSO: This is where the Client connects to the IdP first, authenticates, then access the resources from the SP
    2) SP Initiated SSO: This is where an unauthenticated client connects to a SP, which then redirects the client to the IdP for authentication. The authenticated Client is then redirected to the SP and allowed to access the resource.

This article will discuss using the NetScaler as both a SAML IdP and SP in an SP Initiated SSO setup.

---

Instructions

ADC as a Service Provider 
ADC as an Identity Provider
Troubleshooting SAML on the ADC
Common Issues with SAML


ADC as a Service Provider (SP):

To setup the ADC as a Service Provider, create a SAML Policy and Profile under:
Security -> AAA - Application Traffic -> Policies -> Authentication -> Basic Policies -> SAML-> Servers and click Add:

The IdP Certificate Name is the Certificate that is bound to the IdP's authentication page. Just the certificate is needed, not the key/
Redirect URL is the URL that users will authenticate against. Some IdP's have special URLs that are not reachable unless under SAML setup.
Single Logout URL is a URL that is specified so that the ADC can recognize when to send the client back to the IdP to complete the Sign out process. We will not use it in this simple deployment.
User Field is the section of the IdP's SAML authentication Form that contains the Username, so the SP can extract it is required.
Signing Certificate Name is a Certificate-Key pair that can be used to sign the SP assertion that the ADC will generate. Some SAML setups require signed assertions to improve security . WE will see what a signed and unsigned SP assertion will look like.
Issue Name is a Unique ID that will be specified on both the SP and IdP to help identify the Service Provider to each other. This can be anything and does not need to be the URL as specified below.
Reject Unsigned Assertion is an option that you can specify if you require the Assertions from the IdP to be signed. You can ensure that only the Assertion needs to be signed (ON) or both the Assertion and Response from the IdP need to be signed (STRICT)
SAML Binding is the method that will be used to move the client from the SP to the IdP. This will need to be the same on the IdP so it understands how the client will connect to it.
When the ADC is an SP, it supported POST, REDIRECT and ARTIFACT bindings.
POST will respond to the unauthenticated client with a 200 OK and form data so the Client will connect to the IdP with a POST request.
REDIRECT will respond to the unauthenticated client with a 302 Redirect which will have the Redirect URL and the SP assertion in the URL. The client will then connect to the IdP with a GET request, which will contain the Assertion in the URL.

Under More
----------------------
Audience is an identifier, typically a URL, to identify the SP in the scenario
Skew Time, is the amount of time that the Assertion from the IdP is valid for.
This stops re-use and storage of SAML assertions
Name ID Format, is the format that the Username is tranmistted and expected between the IdP and SP. This option must match between IdP and SP




Then create a SAML policy and bind it to a Gateway or AAA vServer:
Example Config:
add authentication samlPolicy saml_sp_pol ns_true saml_sp_prof
bind authentication vserver sp.franklab.com -policy saml_sp_pol -priority 100 -gotoPriorityExpression END
add cs vserver http_cs_vserver HTTP 10.90.47.223 80 -cltTimeout 180 -AuthenticationHost sp.franklab.com -Authentication ON -authnVsName sp.franklab.com

If you are protecting a Content Switch or Load Balancer with SAML, bind the AAA/NSG vServer as a Forms based authentication to the protected VIP.

Note: If the ADC is acting as a Service Provider, the Consumer Assertion URL will be http(s)://fqdn.of.vserver/cgi/samlauth
The fqdn.of.vserver is the FQDN of the LB or CS that is being protected, not the AAA or NSG vServer.


ADC as an Identity Provider (IdP):

To setup the ADC as an Identity Provider, create a SAML IdP Policy and Profile under:
Security -> AAA - Application Traffic -> Policies -> Authentication -> Advanced Policies -> SAML IdP-> Servers and click Add:

The Assertion Consumer Service URL is the URL that the authenticated user will be redirected to.
IdP Certificate Name is the Certificate-Key pair used for the authentication page.
SP Certificate Name is the Certificate of the Service Provider in this scenario, the key is not required for this.
Sign Assertion is the option to Sign the Assertion and Response when redirecting the Client back to the Service Provider.
Issue Name is an ID that some Service Providers require. This does not need to be the FQDN or URL of the IdP, but it has to be the same on both the IdP and SP profiles if used.
Service Provider ID is a Unique ID that will be specified on both the SP and IdP to help identify the Service Provider to each other. This can be anything and does not need to be the URL as specified below, but needs to be the same on both the SP and IdP profiles.
Reject Unsigned Requests is an option you can specify to ensure only Assertions signed with the SP Certificate are accepted.
Signature Algorithm is the Algorithm used to sign and verify the Assertions between the IdP and SP, this needs to be the same on both the IdP and SP profiles.
Digest Method is the Algorithm used to verify the integrity of the Assertions between the IdP and SP, this needs to be the same on both the IdP and SP profiles.
SAML Binding is the same as described in the SP profile, it needs to be the same on both the SP and IdP.
ADC as a SAML IdP only supported POST and REDIRECT bindings, not ARTIFACT as of NS11.1 52.13


Note: When the ADC acts as an IdP, it uses an AuthnContextClassRef of urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
Some Service Provider Profiles require this information.

After creating this Profile, create a policy which will only be hit for SAML requests and bind it to a AAA or NSG vServer which has authentication policies bound to it, such as LDAP or RADIUS.
SAML IdP policies are considered Advanced Authentication policies which are processed first, so the priority does not need to be higher that Based Authentication Policies.
From there, the user will authenticate against the LDAP or RADIUS etc, and then be directed to the Assertion Consumer Service URL with the IdP assertion.

Note: In IDP initiated, User will get authenticated 1st and SAML Response is posted to the SP/ACS.

Example Config with LB Vserver:

add tm samlSSOProfile SAML_IDP_Initiated -samlSigningCertName Wildcard_new_repro.cer -assertionConsumerServiceURL "https://test.repro.lab/cgi/samlauth" -relaystateRule "\"https://test.repro.lab/customer1\"" -sendPassword ON -samlIssuerName saml-sp.repro.lab -audience "https://test.repro.lab/cgi/samlauth" -samlSPCertName Wildcard_new_repro.cer -skewTime 50

add tm trafficAction SAML_IDP_Initiated_Proile -SSO ON -persistentCookie OFF -InitiateLogout OFF -kcdAccount NONE -samlSSOProfile SAML_IDP_Initiated

add tm trafficPolicy SAML_IDP_Initiated "HTTP.REQ.URL.EQ(\"/customer1\")" SAML_IDP_Initiated_Proile

bind lb vserver SAML -policyName SAML_IDP_Initiated -priority 110 -gotoPriorityExpression END -type REQUEST

Example Config with VPN Vserver:

add vpn samlSSOProfile SAML_IDP_Initiated_VPN -samlSigningCertName Wildcard_new_repro.cer -assertionConsumerServiceURL "https://saml-sp.repro.lab/cgi/samlauth" -relaystateRule "\"https://saml-sp.repro.lab/index.html\"" -sendPassword ON -samlIssuerName test.repro.lab -audience "https://saml-sp.repro.lab/cgi/samlauth" -samlSPCertName Wildcard_new_repro.cer -skewTime 50

add vpn trafficAction SAML_IDP_VPN_Traffic_Profile http -SSO ON -samlSSOProfile SAML_IDP_Initiated_VPN

add vpn trafficPolicy SAML_IDP_VPN_TPol ns_true SAML_IDP_VPN_Traffic_Profile

bind vpn vserver Gateway_SAML -policy SAML_IDP_VPN_TPol -priority 100

Troubleshooting SAML on the ADC:

When troubleshooting SAML, the best way is to use Browser Debug tools such as the below and actively capture the Assertions from the IdP and SP:
https://chrome.google.com/webstore/detail/saml-message-decoder/mpabchoaimgbdbbjjieoaeiibojelbhm?hl=en
Or
https://addons.mozilla.org/en-GB/firefox/addon/saml-tracer/

A set of Signed and Unsigned SP and IdP assertions are attached to this article

Common Issues with SAML:

When accessing the SP, you are presented with the above page.
This tells you that the Signature Algorithm for the SP and IdP do not match or the signing certificate from the Service Provider does not match the Certificate specified on the IdP profile.
 

If you are presented with this error, this means that the NetScaler is not able to identify the SAML request that it is sent.
This usually occurs when the SAML binding on the SP and IdP profiles do not match.
 

After authentication to the IdP, the NetScaler (SP) presents the above.
This occurs when the assertion from the IdP is missing certain parameters that the NetScaler is looking for, such as a Signature.


If you see the above message from the NetScaler, upgrade to the latest firmware of your current version and contact Citrix Technical Support, as the NetScaler is having issues interpreting the Assertion from a Third Party IdP or SP

This article will go through a simple SP-Initiated SAML set up using the NetScaler as either an IdP or SP and troubleshoot some common error messages seen

https://docs.citrix.com/en-us/netscaler/11-1/aaa-tm/saml-authentication/netscaler-saml-idp.html
https://docs.citrix.com/en-us/netscaler/11-1/aaa-tm/saml-authentication/netscaler-saml-sp.html