Consider a scenario of Service Provider (SP) initiated SAML flow where siteminder is the SAML Service Provider and NetScaler is the SAML Identity Provider (IdP):

• A user visits SAML Service Provider siteminder that evaluates user requests.

• When the authentication requirements are not met, the user is redirected to the configured IdP based on SAML policies configured on that server.

• SP sends a status code "200 OK" with autopost that contains SAML AuthnRequest and RelayState (indicating the target URL requested).
  • SAML AuthnRequest is the XML blob conforming to SAML standards, optionally along with digest and signature.
  • RelayState consists of information private to SP. Authentication virtual server (IdP) does not depend or use this information for any processing. However, after authentication is completed, authentication virtual server (IdP) would send this information to SP along with assertion. SPs post AuthnRequest to a pre-configured URL on the IdP and sign the message with their private key. On the authentication virtual server (that acts as IDP), this end point is “/saml/login”.

• After Authentication virtual server (IdP) receives SAML Authentication request that is signed, it does an evaluation of SAML IdP policies that are configured on that virtual server. The benefit of this evaluation is two folds. A profile is chosen after policy evaluation this is used not only for validating this logon request but also to sign the assertion after successful authentication.

• After authentication virtual server validates incoming SAML authentication request, it redirects user to AAA login page (index.html).

• After user logs on with the corresponding credentials, authentication virtual server then communicates to various authentication servers. For example, if Active Directory is configured to be the authentication server, IdP communicates using LDAP protocol and provides the credentials that user has posted.

• After authentication succeeds, IdP sends assertion to the user, redirecting the user to the SP using the profile that was chosen earlier to sign the assertion and any customizations. Along with sending assertion, IdP also sends relayState that SP sents with its authentication request.

The following are the FQDNs used in this article:

• Sm-proxy.nsi-test.com is the FQDN of the siteminder Secure Proxy Server. It is a high performance proxy gateway for the siteminder Policy Server (which is the SAML Service Provider in this article).

• Auth.nsi-test.com is the FQDN of the authentication vserver configured in the NetScaler which acts as the SAML Identity Provider.

Configuration on NetScaler

1. Create an authentication virtual server on NetScaler which represents the IdP.

2. Create an SAML IdP Policy/Profile which bounds to the authentication vserver.

3. Configure an SAML IdP profile with following parameters:

• Assertion Consumer Service Url - URL to which the assertion is to be sent. In case of siteminder, the ACS URL is http://sm-proxy.nsi-test.com:8080/affwebservices/public/saml2assertionconsumer. This is the location where the siteminder SP listens for SAML response from the NetScaler IdP.
• SP Certificate Name - Name of the SSL certificate of an SAML Service Provider (siteminder) that is used to verify signature of the incoming AuthnRequest from SP.
• IDP Certificate Name - Name of the signing authority similar to one in the SAML servers SSL certificate. This certificate is used to sign the SAMLResponse that is sent to Relying Party or Service Provider after successful authentication.
• Issuer Name - The name to be used in requests sent from NetScaler to an IdP to uniquely identify NetScaler.
• Signature Algorithm and Digest Method can be set to their default values.
• Audience -  Audience for which assertion sent by an IdP is applicable. This is an entity name or a URL that represents SP. When siteminder receives the Assertion, it checks the Audience field with the siteminder Entity Configuration. It ensures that entity name and Audience name are matching.
  

Configuration on Siteminder

On the siteminder Policy Server Administrative UI, the following must be created:

1. SignedSiteminderSP - A local SAML 2.0 SP entity which represents siteminder as a Service Provider.
2. SignedNSIDP - A Remote SAML 2.0 IdP entity which represents NetScaler as Identity Provider.
3. A federation partnership between the two entities, SignedSiteminderSP and SignedNSIDP.

Remote SAML IDP Entity – SignedNSIDP

• Verification Certificate Alias - The name of the IdP certificate used to sign the SAMLResponse that is sent to Service Provider after successful authentication. This certificate (Nssp-nsi-test) is the same certificate that is configured on the NetScaler as an IdP certificate.
• Binding must be selected as HTTP-POST. Currently NetScaler as IdP only supports this type.
• URL https://auth.nsi-test.com/saml/login where the NetScaler IdP is listening for SAML Auth request (auth.nsi-test.com is the FQDN of the Authentication vserver on NetScaler which has the SAML IDP profile bound to it).
  

Local SAML SP Entity: SignedSiteminderSP

• Base URL - It is the URL of siteminder component (an agent with option pack installed or a siteminder Secure Proxy Server (SPS) where ‘Affwebservices’ (siteminder federation services) are located). In this example, the siteminder Secure Proxy Server is used.
• Signature and Encryption Options - To send signed SAML Authentication requests to NetScaler IdP,  select the check box as shown in the following screen shot and specify the alias for the Key that is used to Sign the Auth request.
  

Partnership between the two entities

• When a partnership is configured, type the SP and IdP entities that were configured earlier. After clicking Get Updates, some of the common settings are inherited from the same entities.
• The important and relevant configurations are shown in the following screen shot of the partnership summary.
  

SAML response from NetScaler IdP to siteminder SP

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" ID="_71175c04d9382ba69c920cf8281e6ba6" IssueInstant="2014-07-14T22:51:26Z" Version="2.0">
<saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity”>SignedNSIDP</saml2:Issuer>
<saml2p:Status><saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" /></saml2p:Status>
<saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="_71175c04d9382ba69c920cf8281e6ba" IssueInstant="2014-07-14T22:51:26Z" Version="2.0">
<saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">NSIDP</saml2:Issuer>
<saml2:Subject>
<saml2:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">user1</saml2:NameID>
<saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml2:SubjectConfirmationData NotOnOrAfter="2014-07-14T22:56:26Z" Recipient="http://sm-proxy.nsi-test.com:8080/affwebservices/public/saml2assertionconsumer" />
</saml2:SubjectConfirmation></saml2:Subject><saml2:Conditions NotBefore="2014-07-14T22:46:26Z" NotOnOrAfter="2014-07-14T22:56:26Z">
<saml2:AudienceRestriction><saml2:Audience>SignedsiteminderSP</saml2:Audience></saml2:AudienceRestriction>
</saml2:Conditions><saml2:AuthnStatement AuthnInstant="2014-07-14T22:51:26Z" SessionIndex="c1d4ff6f291712abef46c2f6fbf127fa”><saml2:AuthnContext>
<saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef></saml2:AuthnContext></saml2:AuthnStatement>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<SignedInfo>
<CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
<SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha1" />
<Reference URI="#_71175c04d9382ba69c920cf8281e6ba">
<Transforms><Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" /><Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" /></Transforms>
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" /><DigestValue>/y1eOsTWLT/oaTkClcz7MS926z4=</DigestValue></Reference></SignedInfo>
<SignatureValue>pEF+xVQ3DNY5U/ohrhU1HL5JMdUFmpIapEd78bF9BHRuhVsJf28LCONReaM9zmBF2wFx1FU7wScWO2ooUBl39gXVUiCTtbIOflwrHwybLqNA5kAmssvsucwdwZGNOAleN6/P1iqePGhDb/u9VGffCTKq4ZPON93j2y1iX3XUwVihAlyy48oFzart/xt4MZVEMjc6s4Z8qMJ2256gjjIDPLBC73duNLFnkIfHcEsxrAR/vFvTT1p7ePzx3sbGv1ZjrhAUVV1ZGxOjt/NZpUAeaIWTbex4UItXSYwuhesF83LmwFuy63Kiwt1cfDUfxWoPLMfGVDf5SRZ6N8ydpGQH2g==</SignatureValue>
<KeyInfo><X509Data><X509Certificate>MIIFiTC....1yeb1xs=</X509Certificate></X509Data></KeyInfo></Signature>
</saml2:Assertion>
</saml2p:Response>

SAML counters to debug any issue

Counter	Description
saml_assertion_verify_success	Number of successful assertion verifications; that many sessions must be established.
saml_assertion_parse_fail	Number of times assertion parsing is failed.
saml_assertion_stale	Number of stale assertions; these have passed verification but are found stale.
saml_signature_verify_fail	Number of times signature verification failed, after passing digest verification.
saml_canonicalize_fail	Number of times canonicalization (done at aaad) is failed.
saml_digest_verify_fail	Number of times digest verification, the first step of verification is failed.
saml_malformed_data	Number of malformed assertions or responses from Idp.
saml_no_policy	Total number of times policy was not found during verification.
saml_parse_logout_fail	Total number of times logout request (from idp) parsing is  failed.
saml_tot_sp_init_logout	Total number of SP initiated logout requests.
saml_tot_idp_init_logout	Total number of IdP initiated logout requests.
saml_large_session_index	Total number of times the session index is greater than 64 bytes.
saml_session_bcast_fail	Total number of times session broadcast is failed.
saml_reject_unsigned_assertion	Total number of times unsigned assertions is rejected.
saml_large_post	Post body size is more than the required size.
saml_base64_decode_fail	Issue while trying to base64 decode SAML data.
saml_tot_dht_put_success	Total number of successful DHT puts.
saml_tot_dht_put_fail	Total number of unsuccessful DHT puts.
saml_tot_dht_get_success	Total number of success DHT pulls.
saml_tot_dht_get_notfound	Total number of times entry was not found, including false positives.
saml_tot_dht_free	Total number of times DHT entries are freed.
saml_tot_dht_deserialize_fail	Total number of times DHT deserialization is failed
saml_tot_replay_detected	Total number of times replay is detected.

ns.log messages which help in debugging failures

AAA LOGIN_FAILED 378 0 :  User user2 - Client_ip 10.252.112.191 - Failure_reason "External authentication server denied access" - Browser Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36
AAATM Message 383 0 :  "SAMLIDP: Checking whether current flow is SAML IdP flow, input U0FNTElEUDEAMzM5N2Y4MmY3YTRhYWMyOTEyYWIzMmRmMTg3YjZiYWNkMDVOTctYjkwYzUyZTA0MTBjJkZvcmNlQXV0aG49ZmFsc2UA"
AAATM Message 384 0 :  "No certificate found for signing assertion, trying to send unsigned assertion"
AAATM Message 452 0 :  "SAML verify digest: digest algorithm 1, input for digest: <AuthnRequest xmlns="urn:oasis:names:tc:SAML:2.0:protocol" ID="_1c7b1d27b0e3bcbada9deb17d1cad88c8981" IssueInstant="2014-08-08T18:12:13Z" Version="2.0">     <ns1:Issuer xmlns:ns1="urn:oasis:names:tc:SAML:2.0:assertion">SignedsiteminderSP</ns1:Issuer> </AuthnRequest>"
AAATM Message 453 0 :  "SAML signature validation: algorithm is 4 input buffer is: <ds:SignedInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:CanonicalizationMethod> <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"></ds:SignatureMethod> <ds:Reference URI="#_1c7b1d27b0e3bcbada9deb17d1cad88c8981"> <ds:Transforms> <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"></ds:Transform> <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform> </ds:Transforms> <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod> <ds:DigestValue>F9iyXEpbzbAWUkeoKNHtjIKjEQo=</ds:DigestValue> </ds:Reference> </ds:SignedInfo>"
AAATM Message 454 0 :  "Error while trying to verify the signature"

The following message is seen when an SAML response assertion is successfully sent to the SP:
AAATM Message 516 0 :  "SAMLIDP: Successfully sent assertion to http://sm-proxy.nsi-test.com:8080/affwebservices/public/saml2assertionconsumer "

Siteminder Logs

For troubleshooting in SP side, use siteminder agent/SPS and siteminder server logs (FWtrace.log and samtracedefault.log). The logs are available in the following locations:

• siteminder Agent Logs: <agent installation direction>/log/FWTrace.log
• siteminder Server Logs: C:\CA\siteminder\log\smtracedefault.log

FWTrace.log shows the instance of arrival of IDP response and subsequent authorization decision by siteminder policy server as well as redirection of user to targe URL. It can be used to verfiy whether the SAML processing is working on siteminder side.
The smtracedefault.log has detailed information including the received request to generate SAML Authentication Request, the Authentication Request generated that is sent to the IDP, the SAML response which is received, and why a SAML response is rejected in case of a failure.

Some common issues identified in the SMTraceDefault.log are:

• Entity Mismatch - When SAML response contains incorrect entity names (IDP or SP).
• SAML Timing Mismatch -  When the time on IDP and SP does not match, SAML may arrive before or after the configured ‘SKEW’ time allowed between the two parties.
• Audience Mismatch - IDP and SP must agree on a common Audience tag, in absence of a configured Audience tag. siteminder expects the SP entity name to appear in the Audience tag.
• Signature/Algorithm mismatch - SAML response must be signed by the IDP private key corresponding to the public key stored in the siteminder certificate store.

This article provides information about the configuration and troubleshooting for NetScaler as SAML IDP and siteminder as SAML SP.