SAML SSO Microsoft Azure Identity Provider
Revision History
Date |
Revision |
||
---|---|---|---|
August 29, 2021 |
Corrected the uid value for source attribute from user.onpremisessamaccountname to user.givenname in section 'Configure Azure Custom Application'. The uid attribute value is dependent on the LDAP user attribute configured in LDAP Directory configuration.
|
||
June 21, 2022 |
Added support for clusterwide agreements with Azure for Unified CM, IM and Presence Service, and Unity Connection. |
Introduction
This document provides a configuration example of how to configure Microsoft Azure as the SAML SSO Identity Provider (IdP) for the following applications:
-
Cisco Unified Communications Manager
-
IM and Presence Service
-
Cisco Unity Connection
-
Cisco Expressway
Single sign-on (SSO) is a session or user authentication process that enables a user to provide credentials to access one or more applications. The process authenticates the user for all applications they have been given rights to and eliminates further prompts when they switch applications during a particular session.
For detailed information about the SAML SSO Solution, see the SAML SSO Deployment Guide for Cisco Unified Communications Applications.
Metadata Requirements
The following conditions apply for metadata agreements with Microsoft Azure:
-
Cisco Unified Communications Manager, IM and Presence Service, and Cisco Unity Connection supports either clusterwide or Per Node agreements with Microsoft Azure.
-
Cisco Expressway supports either clusterwide or per node agreements between Microsoft Azure and the Expressway-C cluster.
Metadata Examples
Given the below UC deployment, see the following table for an example of the total number of metadata files that this deployment would give you for export. Note that the IM and Presence Service is deployed in a Standard Deployment, unless otherwise indicated.
-
A five-node Cisco Unified Communications Manager cluster
-
A three-node IM and Presence Service cluster (Standard deployment)
-
A two-node Cisco Unity Connection cluster
-
A three-node Expressway-C cluster
-
A three-node Expressway-E cluster
With this type of deployment |
These are the XML files that you get... |
---|---|
Expressway is in a Clusterwide agreement |
Example for Clusterwide agreement: You would export three metadata XML files total:
Example for node-wise agreement: You would export two zip files with 11 XML metadata files total:
|
Expressway is in a Per node (Peer) agreement |
You would have three zip files with 13 metadata XML files total:
|
IM and Presence Service is in a Centralized Deployment |
If your IM and Presence Service nodes are in a Centralized Deployment, your IM and Presence metadata is exported separately from your Unified CM telephony cluster. This gives you an extra zip file along with one extra metadata file for the standalone Unified CM node that is in the IM and Presence central cluster. This results in either 5 (clusterwide) or 14 (per node) XML metadata files total, depending on the Expressway agreement type:
|
Configure Azure as Identity Provider
Before you begin
Procedure
Command or Action | Purpose | |
---|---|---|
Step 1 |
Export metadata files from your Cisco UC applications. |
|
Step 2 |
Generate a certificate for the IdP connection. |
|
Step 3 |
Import UC metadata files into Azure and configure Azure to provide identity services. Export a Federation Metadata File from Azure. |
|
Step 4 |
Import the Azure metadata file into your Cisco UC applications and complete the SSO configuration. |
Export UC Metadata Files
Procedure
Step 1 |
Export UC metadata from Cisco Unified Communications Manager: |
Step 2 |
If you have deployed the Centralized Deployment for the IM and Presence Service, repeat the previous step on the Unified CM publisher node that is located within your IM and Presence central cluster. This gives you a separate zip file for the IM and Presence Service cluster. |
Step 3 |
Export UC metadata from Cisco Unity Connection: |
Step 4 |
Export UC metadata from Cisco Expressway. |
Generate Certificate Signing for Azure Responses
If you have OpenSSL installed, generate a certificate for Azure and provision it on the Azure application. Azure will include this certificate in its IdP metadata export and use this certificate to sign the SAML assertions that it sends to Cisco Unified Communications Manager, Cisco Expressway, IM and Presence Service and Cisco Unity Connection nodes. Azure requires that the same certificate be used for all nodes in the cluster.
There is no need to install this certificate on any Cisco UC applications.
If you don’t have OpenSSL, use your enterprise CA to generate a certificate.
![]() Note |
Do not store private keys on your laptop or PC. |
Procedure
Step 1 |
First create a certificate and a private key:
|
Step 2 |
Combine the certificate and the key into a password-protected PFX file, which is required by Azure. Make sure to take note of the password.
|
Step 3 |
Generate a single certificate for all nodes and custom apps in the cluster. |
Step 4 |
Upload the certificate to the Azure Identity Provider. |
Configure Azure Custom Application
Complete the following procedure separately for each cluster node in your Cisco Unified Communications Manager, IM and Presence Service, and Cisco Unity Connection deployment.
For Cisco Expressway, if you have a cluster agreement, complete the procedure once for the Expressway-C cluster. Otherwise, if you are using a peer agreement, complete the procedure separately for each Expressway-C node.
Procedure
Step 1 |
In Microsoft Azure at Enterprise applications | All applications , select Add an application. |
||
Step 2 |
In the Add an application window, do the following:
|
||
Step 3 |
In the left navigation bar, click Single sign-on. |
||
Step 4 |
Click SAML. The Set up Single Sign-On with SAML window appears.
|
||
Step 5 |
Click Upload metadata file and then browse to the UC metadata XML file for the server for which you are configuring an agreement. After you select and open the file, click Add. The Basic SAML Configuration populates with Identifier (EntityID) and Reply URL (Assertion customer service URL) for the Collaboration server.
|
||
Step 6 |
Click Save. |
||
Step 7 |
Edit the User Attributes & Claims section. |
||
Step 8 |
Click SAML-based Sign-on to return to the SAML summary. |
||
Step 9 |
Unified CM, IM and Presence Service, and Unity Connection nodes only. In the the SAML Signing Certificate section, click Edit: |
||
Step 10 |
Expressway only. In the SAML Signing Certificate section, click Edit and set the Expressway options:
|
||
Step 11 |
Download the Federation Metadata XML file.
|
||
Step 12 |
Enable the Application in Azure and Assign Users:
|
||
Step 13 |
With per node agreement, repeat this procedure separately for each Cisco Unified Communications Manager, IM and Presence Service, and Cisco Unity Connection node. For clusterwide agreement, perform this procedure a single time with Cisco Unified Communications Manager, IM and Presence Service, and Cisco Unity Connection. For Cisco Expressway, how many times you complete the procedure depends on the agreement type you chose in Expressway-C:
|
||
Step 14 |
As a final check, after you have created agreements for all of your Cisco UC applications, check the IdP metadata file and make sure that the certificate that you created previously is present in the <X509Certificate> field as the signing certificate in the IdP metadata file. The format is as follows:
|
Enable SAML SSO for Collaboration Applications
Procedure
Step 1 |
Enable SAML SSO on Cisco Unified Communications Manager:
|
Step 2 |
If you have an IM and Presence Centralized Deployment, repeat Step 1 on the Unified CM publisher node that is located in the IM and Presence central cluster. |
Step 3 |
Enable SAML SSO on Cisco Unity Connection:
|
Step 4 |
Enable SAML SSO on Expressway:
|
Troubleshooting
For debugging purposes, use a tool like the SAML tracer.
Make sure that the X.509 Certificate data that is sent as part of the SAML assertion matches with the certificate that you created for Azure.
Check the ssosp logs for errors. Following is an example of a certificate issue that might appear in the ssosp logs:
2020-09-21 05:45:39,131 ERROR [http-bio-8443-exec-51] fappend.SamlLogger - FMSigProvider.verify: The cert contained in the document is NOT the same as the one being passed in.
2020-09-21 05:45:39,134 ERROR [http-bio-8443-exec-51] authentication.SAMLAuthenticator - Error while processing saml response The signing certificate does not match what's defined in the entity metadata.
com.sun.identity.saml2.common.SAML2Exception: The signing certificate does not match what's defined in the entity metadata.
at com.sun.identity.saml2.xmlsig.FMSigProvider.verify(FMSigProvider.java:334)
at com.sun.identity.saml2.assertion.impl.AssertionImpl.isSignatureValid(AssertionImpl.java:651)