Table of Contents
- Understanding Service Provider and Identity Provider
- Understanding SAML Protocol
- Prerequisites for Enabling SAML SSO
- Configuring SAML SSO in Unity Connection
- Access to Web Applications in Unity Connection Using SAML SSO
- Running CLI Commands in Unity Connection
- Troubleshooting SAML SSO in Unity Connection
Cisco Unity Connection supports the single sign-on feature that allows users to log in once and gain access to Unity Connection web applications, such as Cisco Unity Connection Administration and Cisco Personal Communications Assistant. With Unity Connection 10.0(1), an enhancement to the sign-on feature, SAML SSO, is introduced that allows a user to gain single sign-on access with Unity Connection subscriber web interfaces and across the administrative web applications on the following Unified Communication products:
The SAML SSO feature is based on open industry standard protocol SAML (Security Assertion Markup Language). For more information on SAML protocol, see the Understanding SAML Protocol section.
SAML SSO supports both LDAP and non-LDAP users to gain single sign-on access. LDAP users are the users integrated to Active Directory. Non-LDAP users are the users that reside locally on Unity Connection server.
- The LDAP user are allowed to login with a username and password that authenticates on Identity Provider. For more information on Identity Provider, see the Understanding Service Provider and Identity Provider section.
- The non-LDAP users with administrator rights login to Cisco Unity Connection Administration using Recovery URL. Recovery URL provides alternate access to the administrative and serviceability web applications via username and password. A non-LDAP user can access the following web applications on Unity Connection using Recovery URL:
Service Provider (SP) is a protected entity on Unity Connection that provides the web applications. A Service Provider relies on a trusted Identity Provider (IdP) or Security Token Service (STS) for authentication and authorization.
Identity Provider is an online service or website that authenticates users by means of security tokens. It authenticates the end user and returns a SAML Assertion. SAML Assertion shows either a Yes (authenticated) or No (authentication failed) response.
A user must authenticate his or her user credentials on Identity Provider to gain access to the requested web application. If the authentication gets rejected at any point, the user will not gain access to any of the requested web applications. If the authentication is accepted, then the user is allowed to gain single sign-on access to the requested web application.
- OpenAM version 10.1
- ADFS (Active Directory Federated Services) version 2.0
- Ping Federate version 22.214.171.124
- Oracle Identity Manager version 11.0
Security Assertion Markup Language (SAML) is an XML based open standard data format for exchanging data. It is an authentication protocol used by Service Providers to authenticate a user. The security authentication information is passed between an Identity Provider and Service Provider.
All Cisco Unified Communication web interfaces (e.g. CUCM or Unity Connection) use SAML 2.0 protocol in SAML SSO feature. To authenticate the LDAP user, Unity Connection delegates an authentication request to the Identity Provider. This authentication request generated by the Unity Connection is SAML Request.
SAML 2.0 protocol is a building block that helps to enable single sign-on access across collaboration services and also helps to enable federation between collaboration services and customer's Identity Provider.
Once SSO has been enabled on Unity Connection server, a .xml file named, SPMetadata<hostname of Unity Connection>.xml is generated by Unity Connection that acts as a Service Provider metadata. The SAML SP metadata must be exported from SAML Service Provider (on Unity Connection) and then import it to Identity Provider (ADFS).
The administrator must export SAML metadata from Cisco Unity Connection Administration and import that metadata on Identity Provider. The administrator must also export SAML metadata from Identity Provider and import that metadata on Cisco Unity Connection Administration. This is a two way handshake process between the Service Provider (that resides on Unity Connection) and Identity Provider that is essential for SAML Authentication.
- URL information for Identity Provider and Service Provider.
- Service Provider Assertion Consumer Service (ACS) URLs that instructs Identity Provider where to POST assertions.
- Certificate information for Identity Provider and Service Provider.
The exchange of SAML metadata builds a trust relationship between Identity Provider and Service Provider. Identity Provider issues SAML assertion and Identity Provider digitally signs it. On receiving the SAML assertion, Service Provider validates the assertion, using Identity Provider certificate information that guarantees that assertion was issued by Identity Provider.
When single sign-on login fails (e.g. If Identity Provider or Active Directory is inactive), Recovery URL provides alternate access to administrative and serviceability web applications via username and password.
- Unity Connection 10.0(1) and later release on both the servers in the cluster.
- Install Identity Provider on Microsoft Windows 2008 with SP2 platform. You must configure Identity Provider on the same domain as Unity Connection server.
- Make sure that the clocks on Unity Connection and Identity Provider (chosen for SAML SSO) synchronize with each other.
- When enabling SSO mode from Cisco Unity Connection Administration, make sure you have at least one LDAP user with administrator rights in Unity Connection to Run SSO Test for SAML SSO.
- Assign the system administrator role to the user accounts to allow them to access Unity Connection administrative and serviceability web applications.
This section outlines the key steps and/or instructions that must be followed for Unity Connection specific configuration. However, if you are configuring SAML SSO feature for the first time, it is strongly recommended to follow the detailed instructions given below:
Step 2 From Administrative Tools, select the ADFS 2.0 Management menu to launch the ADFS configuration wizard. Select the ADFS 2.0 Federation Server Configuration Wizard Link from the ADFS Management console.
Step 5 Select Required: Add a trusted relying party and select Start. If you have a URL or file containing the configuration use this option otherwise select Enter data about the relying party manually and then select Next.
Step 7 Select Enable support for SAML 2.0 WebSSO protocol and then enter the URL to the service providing the integration. Select Next and enter the Relying party trust identifier. Select Add and then select Next.
- Launch ADFS 2.0 from programs menu and select Add Relying Party Trust.
- Select Start button and select Import data option about the relying party from a file. Select Fedlet metadata file from a desktop which you downloaded either from Cisco Unified CM or using REST API. Select Next.
- Enter Display Name and select Next. Select Permit all users to access this relying party and select Next.
- Review the settings and select Next. Select Close and ensure that the Add Claim Rules check box is checked.
- Select Add Rule. Enter the claim rule name and select the Attribute Store.The syntax for the Name ID claim rule is:
"c:[Type=="http://schemas.microsoft.com/ws/2008/06/identity/claims/windows account name"]=> issue(Type= "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer= c.Issuer, Originallssuer= c.Originallssuer, Value= c.Value, ValueType=c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"]="urn:oasis:names:tc:SAML:2.0:nameid-format: transient", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/namequalifier"]="http:// <FQDN of ADFS server>/adfs/com/adfs/service/trust", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spnamequalifier"]="<FQDN of Unity Connection server>");"
- Select Next with default claim rule template. On Send LDAP Attributes as Claims In Configure Rule, enter the Claim Rule name and select Attribute store as Active Directory. Configure LDAP Attribute and Outgoing Claim Types. Select Finish and Apply followed by OK.
Step 1 To configure policies on OpenAM server, you must log in to OpenAM and select the Access Control tab. Click the Top Level Realm option, select the Policies tab, and then create a new policy. Follow the steps as given in the Cisco white paper, https://supportforums.cisco.com/docs/DOC-14462 , for creating a new policy. While following the instructions given in the white paper, make sure to create policies with the below mentioned Unity Connection-specific information:
Step 2 Configure a Windows Desktop SSO login module instance. Follow the instructions for configuring Windows Desktop as given in the Cisco white paper, https://supportforums.cisco.com/docs/DOC-14462 .
Step 3 Configure a J2EE Agent Profile for Policy Agent 3.0. Follow the instructions to create a new J2EE agent as given in the Cisco white paper, https://supportforums.cisco.com/docs/DOC-14462 with the below mentioned Unity Connection-specific settings:
- The name mentioned as agent profile name is the name that you need to enter when enabling SSO on the Unity Connection server, when it prompts as: “Enter the name of the profile configured for this policy agent.”
- The agent password entered here is the password that is entered on the Unity Connection server when it prompts as: “Enter the password of the profile name.”
- Make sure to add the following URIs to the Login Form URI section on the Application tab:
- Under the Application tab, add the following URI in the Not Enforced URI Processing session: –/inbox/gadgets/msg/msg-gadget.xml
- Import users from LDAP to Unity Connection. Users must be configured with the appropriate roles to log in to Cisco Unity Connection Administration, or Cisco Unity Connection Serviceability.
- Upload the OpenAM certificate into Unity Connection as described in the Configuring SSO on Cisco Unified Communications Manager 8.6 section of the Cisco white paper, https://supportforums.cisco.com/docs/DOC-14462 .
Step 1 Install JDK. Download JDK from the given location: www.oracle.com/technetwork/java/javase/downloads.
- Select Roles and Protocols.
- Provide the Base URL and Realm. Base URL is the IP address of Ping Federate server.
Step 4 Select Federations. In the Federations window, select Add New Federations. In this case the Metadata file is imported from Cisco Unified CM. After the Metadata has been loaded, the Cisco Unified CM hostname is displayed under Federations.
NoteThe cluster status is not affected while enabling or disabling the SAML SSO feature. SAML SSO cannot be enabled from publisher server if subscriber server is inactive or vice versa. SAML SSO cannot be enabled from publisher server if subscriber server is inactive or vice versa.
Step 3 To initiate the IdP Metadata import, navigate to Identity Provider (IdP) Metadata Trust File and select the Browse to upload the IdP metadata option from your system. Then select the Import IdP Metadata option. Follow the link below to download IdP metadata trust file for ADFS:
Caution If the Trust Metadata has not been imported then a warning message prompts on the screen as The server metadata file must be installed on the IdP before this test is run.
Select Next and a window appears for valid administrator IDs that automatically populates the LDAP user with administrator rights into that window. If you find the LDAP user with administrator rights automatically populated in the above window, then select Run Test to continue.
NoteAfter enabling/disabling SAML SSO on Unity Connection, a user must wait for approximately (2-3 minutes) to get the web applications initialized properly and then the Tomcat service needs to be restarted from Cisco Unity Connection Serviceability page or using the CLI command utils service restart Cisco Tomcat.
SAML SSO allows a LDAP user to login to client applications using username and password that authenticates on Identity Provider. A user sign-in to any of the supported web applications on Unified Communication products (after enabling the SAML SSO feature) also gains access to the following web applications on Unity Connection (apart from Cisco Unified Communications Manager and Cisco Unified CM IM/Presence):
NoteTo access Web Inbox and Mini Web Inbox, you must have a user with mailbox. Also navigate to Unity Connection Administration> Class of Service> Licensed features and make sure that Allow Users to Use the Web Inbox, Messaging Inbox and RSS Feeds check box is checked.
The non-LDAP users with administrator role can login to Cisco Unity Connection Administration using Recovery URL. The Recovery URL option is present in Unity Connection product deployment selection window just below the Cisco Unity Connection option. When SSO login fails (if Identity Provider or Active Directory is inactive), Recovery URL provides alternate access to the administrative and serviceability web applications via username and password.
- utils sso enable
- utils sso disable
- utils sso status
- utils sso recovery-url enable
- utils sso recovery-url disable
- set samltrace level <trace level>
- show samltrace level
This command when executed returns an informational text message that prompts that the administrator can enable SSO feature only from graphical user interface (GUI). Both OpenAM SSO and SAML SSO cannot be enabled from CLI interface.
This command disables (both OpenAM based or SAML based) SSO mode. Within a cluster, the command needs to be executed on both the nodes. You may also disable the SSO from graphical user interface (GUI) by selecting the Disable option under the specific SSO mode.
SAML SSO allows a user to have single sign-on access to web applications until a web browser is active. Ensure that you have taken care of all the requirements and checklist while enabling the SAML SSO mode. However, for any SAML SSO related issues, see Troubleshooting Guide for Cisco Unity Connection Release 10.x, available at