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.

Note

 

Make sure that the uid value received from Azure matches the User ID of the end-user created on Unified Communications Manager > User Management > End User Configuration window.

The user needs to be the same end user used to integrate Azure and Unified Communications Manager

User IDs should not be the given First Name or Last Name. It should be displayed as uid.

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

Table 1. UC Metadata Files Exported

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:

  • One metadata XML file for the Unified CM cluster with Unified CM and IM and Presence Service nodes

  • One metadata XML file for the Unity Connection cluster

  • One metadata XML file for the Expressway-C cluster

Example for node-wise agreement:

You would export two zip files with 11 XML metadata files total:

  • Unified CM zip with five metadata XML files for Unified CM nodes and three metadata XML files for IM and Presence nodes

  • Unity Connection zip file with two metadata XML files for Unity Connection nodes

  • One metadata XML file for the Expressway-C cluster

Expressway is in a Per node (Peer) agreement

You would have three zip files with 13 metadata XML files total:

  • Unified CM zip contains five metadata XML files for Unified CM nodes and three metadata XML files for IM and Presence Service nodes

  • Unity Connection zip contains two metadata XML files for Cisco Unity Connection nodes

  • Expressway zip contains three metadata XML files for the Expressway-C cluster nodes

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:

  • Unified CM zip contains five Unified CM metadata XML files (per node) or one XML file (clusterwide)

  • For IM and Presence, either one metadata XML file (clusterwide) or one zip file containing three metadata XML files (per node) for the IM and Presence Service nodes and one metadata XML file for the Unified CM publisher node that is in the IM and Presence Service central cluster

  • Unity Connection zip contains two metadata XML files (per node) or one XML file (clusterwide).

  • For Expressway, either one Expressway metadata XML file (cluster agreement) or an Expressway zip file with three metadata XML files for the Expressway-C cluster (peer agreement)

Configure Azure as Identity Provider

Complete these tasks to configure Microsoft Azure as your Identity Provider for Cisco Collaboration applications.

Before you begin

Your LDAP Directory sync must be synced from an on-premise directory server. Syncing users or enterprise groups from the Azure Active Directory is not supported.

Procedure

  Command or Action Purpose

Step 1

Export UC Metadata Files

Export metadata files from your Cisco UC applications.

Step 2

Generate Certificate Signing for Azure Responses

Generate a certificate for the IdP connection.

Step 3

Configure Azure Custom Application

Import UC metadata files into Azure and configure Azure to provide identity services. Export a Federation Metadata File from Azure.

Step 4

Enable SAML SSO for Collaboration Applications

Import the Azure metadata file into your Cisco UC applications and complete the SSO configuration.

Export UC Metadata Files

Before you configure Azure, you must export UC metadata from your Cisco Collaboration deployment.

Procedure


Step 1

Export UC metadata from Cisco Unified Communications Manager:

  1. From Cisco Unified CM Administration, go to System > SAML Single Sign On.

  2. For the SSO Mode, select either Cluster wide or Per node.

  3. In the Certificates section, choose either Use Tomcat certificate or Use system-generated self-signed certificate.

  4. Click Export All Metadata and download the metadata file.

  5. After the metadata zip file downloads, unzip the file and verify that you have a separate file for each cluster node.

    Note

     
    If you have the IM and Presence Service deployed in a Standard Deployment (non-centralized), your metadata zip file also includes IM and Presence Service nodes.

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:

  1. In Cisco Unity Connection Administration, choose System Settings > SAML Single Sign On.

  2. For the SSO Mode, select either Cluster wide or Per Node agreement.

  3. Click Export All Metadata and download the metadata file.

    Note

     
    With Clusterwide agreements, you will get an XML file download. With Per Node agreements, you will get a zip file that contains XML files for each Unity Connection cluster node.

Step 4

Export UC metadata from Cisco Expressway.

  1. On the Expressway-C primary peer, go to Configuration > Unified Communications > Configuration.

  2. In the MRA Access Control section, set the Authentication path to either SAML SSO authentication or SAML SSO or UCM/LDAP.

  3. Set SAML Control to either Cluster or Peer, depending on which type of SAML agreement you want.

  4. Click Export SAML data.

  5. Download the metadata file to a secure location.

    Note

     
    With Cluster agreements, you will get an XML file download. With Peer agreements, you will get a zip file that contains XML files for each Expressway-C cluster node.

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:

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 1095 -out certificate.pem

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.

openssl pkcs12 -export -out certificate.pfx -inkey key.pem -in certificate.pem

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:

  1. Click Non-gallery application.

  2. Enter the Name of your new application (for example, UnifiedCM_Publisher) and click Add.

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.

  1. Under Required claim, click on Unique User Identifier (Name ID).

  2. For the name identifier format, select Default.

  3. For Source attribute, choose user.onpremisessamaccountname.

  4. Click Save.

  5. Under Additional claims, delete all existing claims. For each claim, click () and select Delete. Click OK to confirm.

  6. Click Add new claim to add the uid claim.

  7. For Name, enter uid.

  8. Leave the Namespace field blank.

  9. For Source, check the Attribute radio button.

  10. From the Source attribute drop-down, select user.givenname.

    Note

     
    uid attribute name depends on the LDAP System Settings configured in the Cisco Unified CM Administration user interface.
  11. Click Save.

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:

  1. Click Import Certificate.

  2. In the Certificate field, click the cloud to browse to and open the certificate.pfx file that you created earlier.

  3. Enter the password and click Add.

    Note

     
    This must be the only certificate in the list and must be active.
  4. If this certificate is not active, click the adjacent dots (), select Make certificate active and then click Yes.

  5. If there are other certificates in the list, click the adjacent dots () for those certificates, select Delete Certificate and click Yes to delete those certificates.

  6. Click Save.

Step 10

Expressway only. In the SAML Signing Certificate section, click Edit and set the Expressway options:

  1. Set Signing Option to Sign SAML Response and Assertion.

  2. Set the Signing Algorithm to the appropriate SHA algorithm. For example, SHA-256.

  3. Click Save.

Step 11

Download the Federation Metadata XML file.

Note

 
You need to do download metadata from the IdP once only for your UC deployment. You can import the same IdP metadata file into all your applications.

Step 12

Enable the Application in Azure and Assign Users:

Note

 
Azure provides you with the ability to assign individual users for SSO with Azure, or all users. For this example, it is assumed that you are enabling SSO for all users.
  1. In the left navigation bar, select Manage > Properties.

  2. Set Enabled for users to sign in? to Yes.

  3. Set Visible to users? to No.

  4. Click Save.

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:

  • With Cluster agreements—Complete this procedure a single time only for the Expressway-C cluster. You don't need to complete the procedure for the Expressway-E cluster.

  • With Peer agreements—Complete this procedure separately for each Expressway-C node. You don't need to complete the procedure for Expressway-E nodes.

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:


<KeyDescriptor use="signing">
<KeyInfo>
<X509Data>
<X509Certificate>
--actual X.509 certificate--
</X509Certificate>
</X509Data>
</KeyInfo>
</KeyDescriptor>

Enable SAML SSO for Collaboration Applications

Complete the SAML SSO configuration in your Cisco Collaboration environment.

Procedure


Step 1

Enable SAML SSO on Cisco Unified Communications Manager:

  1. From Cisco Unified CM Administration, navigate to System > SAML Single Sign On.

  2. Click Enable SAML SSO, click Continue and follow the prompts.

  3. Import the IdP Metadata file into Cisco Unified Communications Manager.

  4. Test the SSO connection.

  5. Restart the Cisco Tomcat Service.

  6. Repeat this step on each Cisco Unified Communications Manager cluster node.

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:

  1. In Cisco Unity Connection Administration, go to System Settings > SAML Single Sign On.

  2. Click Enable SAML Single Sign On.

  3. Click Continue and follow the prompts.

  4. Import the IdP metadata file into Cisco Unity Connection.

  5. Test the SSO Connection.

  6. Restart the Cisco Tomcat service.

  7. Repeat this procedure on each Cisco Unity Connection node.

Step 4

Enable SAML SSO on Expressway:

  1. On the Expressway-C primary peer go to Configuration > Unified Communications > Identity providers (IdP).

  2. Click Import new IdP from SAML.

  3. Locate and select the metadata file.

  4. Set Digest to the required SHA algorithm and click Upload.

  5. Verify that your Identity Provider appears.

  6. Click Associate domains.

  7. Check each of the domains that you want to associate to this IdP.

  8. Click Save.


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)