This document covers the SAML in a network environment where Citrix ADC is a virtual standalone instance running as SAML Identity Provider (IdP) and Cisco Call Manager as SAML Service Provider (SP). There are some important facts about Cisco UCM that should be taken into consideration before proceeding with SAML configuration.

Cisco UCM Cluster:

Cisco UCM cluster handles call processing in Cisco's implementation of IP Telephony.  The cluster has two types of nodes.

a)       Publisher:

The publisher is the authoritative database for configuration.  When changes are made in configuration, they are made on the publisher and replicated to the subscribers. NODE-C1 is a publisher node in this configuration document.

b)      Subscriber:

If the publisher is unavailable, the phones can re-home themselves to a subscriber in order to continue to be functional. Subscribers are not entitled to make any SAML configuration related changes. NODE-C2 and NODE-C3 are subscriber nodes in this document.

Cisco UCM SSO allowed operations according to node type is in the table below. 

Instructions

Cisco Assertion Consumer Service (ACS) Index URL:
 

Unified Communications Manager no longer uses the Assertion Consumer Service URL in SAML authentication requests, instead uses the Assertion Consumer Service Index URL.

ACS URL is the SP endpoint to which SAML assertion is redirected at SP. In Cisco UCM, each node in the cluster is a unique SP endpoint. Therefore, Publisher node generates SP metadata configuration with a list of indexes in which each index represents a unique URL and assertion method for each node in the cluster.

Below is an example of ACS Indexing, obtained from SP metadata file.
 

 In the above example,

Index “0” points to subscriber node “NODE-C3” with assertion method “POST”.
Index “2” points to publisher node “NODE-C1” with assertion method “POST”.
Index “4” points to subscriber node “NODE-C2” with assertion method “POST”.

Citrix ADC ACS Index Feature:

Starting from R13.0, Citrix ADC as SAML Identity Provider (IdP) support ACS indexing. The SAML IdP imports ACS indexing configuration from SP metadata only. ACS indexing cannot be configured via GUI or CLI. R13.0 also provides additional SAML debugging messages, which can be useful in troubleshooting. If you running an older version, you must upgrade to R13.0 to use this feature. Please refer to the release notes for more information.
https://docs.citrix.com/en-us/citrix-adc/downloads/release-notes-13-0-41-28.html

SAML SSO Call Flow:

This section describes the call flow between Citrix ADC and Cisco UCM. This example is a SP initiated SSO where an unauthenticated client connects to SP, which then redirects the client to IdP for authentication. The successfully authenticated client is redirected back to SP and is allowed to access the resource. 

1. SSO is initiated from Cisco Call Manager by choosing the node. A node can be either Publisher or subscriber.  Test user is selected from the list.
2. After the test is run, Cisco UCM receives the request from browser and generates SAML authentication request.  This SAML authentication request contains information about the SP identity, IdP destination and most importantly ACS Index information.
3. The service provider redirects the request (302) to the browser.
4. The browser follows the redirect and issues an HTTPS GET request to IdP. The SAML authentication request is maintained as a query parameter in the GET request.
5. Citrix ADC checks for a valid session with browser.
6. If there is no session found, then Citrix ADC will generate a login request to the browser, asking for credentials.
7. User enters the required credentials in the login page and posts them back to Citrix ADC.
8. Citrix ADC forwards the username and password to LDAP server.
9. LDAP server verifies credentials and sends back the validation status.
10. If validation is successful, Citrix ADC will generate a SAML Response which includes a SAML assertion.
11. Citrix ADC then redirects the SAML response to the browser.
12. The browser follows the hidden form POST instruction and posts the assertion to the ACS URL on the service provider.
13. The service provider extracts the assertion and validates the digital signature.
14. The service provider then grants access to the protected resource and provides the resource content by replying 200 OK to the browser.

    Configuration on Citrix ADC:

This document covers Citrix ADC configuration only. For SP related configuration, please refer to Cisco documentation.

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

2. Create SAML IdP Policy which is bound to the authentication vserver.

3. Create SAML IdP Profile.

where:
samlIdPCert:
Name of the SSL certificate-key pair of SAML IdP, referred here as idp.test.com. This certificate is used to sign the SAMLResponse that is sent to Service Provider after successful authentication

metadataRefreshInterval:
It is an interval in minutes after which Citrix ADC tries to refresh metadata configuration file from its hosted location.   

assertionConsumerServiceURL:
It is a URL where authenticated users will be redirected at SP.  This parameter will not be used in SAML assertion if Citrix ADC has the ACS indexing information. If Citrix ADC fails to download metadata file from its hosted location, then ACS URL will be used.  

Reject Unsigned Requests:
It is an option you can specify to ensure only Assertions signed with the SP Certificate are accepted. In this example, we have set this to OFF.

Audience:
It is a unique identifier, typically a URL, to identify the SP. However, Cisco UCM doesn’t accept the audience value auto-generated by Citrix ADC in SAML response. This parameter should be manually configured and correct value of audience is the SP EntityID in its metadata, which is “NODE-C1.ucm.test.com”. 

Attribute1:
Cisco UCM expects User Login name to be returned as an attribute in SAML Assertion. Attribute must be defined as “uid”. 

metadataUrl:
As mentioned above in the document, Citrix ADC supports ACS Indexing configuration by importing SP metadata configuration only. Manual configuration is not supported as of now. SP metadata provides information about SP parameters such as SP Entity ID, assertion format and ACS indexing. ADC will download the metadatafile using HTTP/HTTPS. It is highly recommended that metadata file should be hosted external to ADC.
Below is the sample metadata file from Cisco UCM that is imported by Citrix ADC.
 

Some important parameters in the SP metadata are:

EntityID:
Uniquely identifies SP. Usually, it is the publisher node in Cisco UCM cluster.

WantAssertionSigned:
It defines that SAML assertion sent by Citrix ADC must be signed using IdP Certificate or unsigned.

ACS Indexing:
Already explained above.

Name ID Format:
It is the format that the Username is transmitted and expected between the IdP and SP.

 4. Bind SAML IdP Profile to authentication vserver.  

5. Create LDAP profile and bind to authentication vserver.

Generate ADC (IdP) Metadata:

Cisco UCM requires metadata from Citrix ADC to import IdP SAML configuration. Once IdP profile configuration is complete on Citrix ADC, metadata is generated by browsing to authentication virtual server in the following format.
https://idp.test.com/metadata/samlidp/IDP_AUTH_Prof_AAA_EN  

where:
idp.test.com is the FQDN of authentication virtual server.
DP_AUTH_Prof_AAA_EN is the name of SAML IdP Policy bound to authentication VS. 

Below is the sample IdP metadata generated by ADC.

Please note that every time IdP metadata link is refreshed, a new signature is generated in metadata XML file. Therefore, SP should import most recent metadata file with the updated signature.

SAML Traces:

In the following SAML request, Index 0 is requested which corresponds to NODE-C3. You will see that NODE-C3 as destination URL in SAML response.

SAML Request:

  SAML Response:

Troubleshooting:

Exception Reported by Cisco UCM:



In case of SAML exceptions faced at Cisco UCM, always verify that correct ACS index is returned in SAML response.  One common reason for not returning correct index is when Citrix ADC is unable to fetch metadata file, thus responding with incorrect ACS index.

SAML Assertion Failed:

Always verify that signed assertion is sent by ADC using correct signing algorithms. Cisco UCM does not accept unsigned assertions.

Missing Attribute:

Cisco UCM expects username as an attribute in SAML assertions. Without this attribute, Cisco UCM will not successfully parse SAML assertion.

Incorrect Audience:

Cisco UCM does not accept URI as audience. This has to be manually configured as SP ID in SAML IdP policy, otherwise default ADC settings will update audience as URI.