Configure the Identity Provider for Cisco Identity Service to Enable SSO

Introduction

This document describes the configuration of the Identity Provider (IdP) for Cisco Identity Service (IdS) in order to enable Single Sign On (SSO).

Prerequisites

Requirements

Cisco recommends that you have knowledge of these topics:

• Cisco Unified Contact Center Express (UCCX) Release 11.5 or Cisco Unified Contact Center Enterprise Release 11.5 or Packaged Contact Center Enterprise (PCCE) Release 11.5 as applicable
• Microsoft Active Directory - AD installed on Windows Server
• Active Directory Federation Service (ADFS) Version 2.0/3.0

Note: This document references UCCX in the screen captures and examples, however, the configuration is similar with respect to the Cisco IdS (UCCX/UCCE/PCCE) and the IdP.

Components Used

This document is not restricted to specific software and hardware versions.

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, ensure that you understand the potential impact of any command.

Background Information

Cisco IdS Deployment Models

Product	Deployment
UCCX	Co-resident
PCCE	Co-resident with CUIC (Cisco Unified Intelligence Center) and LD (Live Data)
UCCE	Co-resident with CUIC and LD for 2k deployments. Standalone for 4k and 12k deployments.

Overview of SSO

Cisco provides many services in different forms and as an end user, you want to sign in only once to have access to all of the Cisco Services. If you want to find and manage contacts from any of the Cisco applications and devices, leverage all possible sources (Corporate Directory, Outlook, Mobile contacts, Facebook, LinkedIn, History), and have them rendered in a standard and consistent manner that provides the needed information to know their availability and how best to contact them.

SSO with SAML (Security Assertion Markup Language) targets this requirement. SAML/SSO provides the ability for users to log into multiple devices and services through a common account and authorization identity called the IdP. The SSO functionality is available in UCCX/UCCE/PCCE 11.5 onwards.

Configuration Overview

Configure

Authentication Types

Cisco IdS supports only form-based authentication of IdPs.

Refer to these MSDN articles in order to learn how to enable Form Authentication in ADFS.

• For ADFS 2.0 refer to this Microsoft TechNet article,
  http://social.technet.microsoft.com/wiki/contents/articles/1600.ad-fs-2-0-how-to-change-the-local-authentication-type.aspx.
• For ADFS 3.0 refer to this Microsoft TechNet article,
  https://learn.microsoft.com/en-us/archive/blogs/josrod/enabled-forms-based-authentication-in-adfs-3-0

Note: Cisco IdS 11.6 and later supports both form-based and Kerberos authentication. For Kerberos authentication to work, you must disable the Form based authentication.

Establish Trust Relationship

For onboarding and in order to enable applications to use Cisco IdS for SSO, perform the metadata exchange between the IdS and IdP.

• Download the SAML SP Metadata file  sp.xml.
• From Settings, navigate to IdS Trust tab on the IdS Management page.

• Download the IdP Metadata file from the IdP from the URL:
  https://<ADFSServer>/federationmetadata/2007-06/federationmetadata.xml

• On the IdS Management page, upload the IdP Metadata file that was downloaded in the previous step.

This is the procedure to upload the IdS metadata and add Claim Rules. This is outlined for ADFS 2.0 and 3.0.

ADFS 2.0

Step 1. In the ADFS server navigate to, Start > All Programs > Administrative Tools > ADFS 2.0 Management, as shown in the image:

Step 2. Navigate to Add ADFS 2.0 > Trust Relationship > Relying Party Trust, as shown in the image:

Step 3. As shown in the image, choose the option Import data about the relying party from a file.

Step 4. Complete the establishment of the Relying Party Trust.

Step 5. In the properties of the Relying Party Trust, choose the Identifier tab.

Step 6. Set the identifier as the Fully Qualified Hostname of the Cisco Identity Server from which sp.xml is downloaded.

Step 7. Right-click on the Relying Party Trust and then click Edit Claim Rules.

You must add two claim rules, one is when the LDAP (Lightweight Directory Access Protocol) attributes are matched while the second is through custom claim rules.

uid - This attribute is needed for the applications in order to identify the authenticated user.
user_principal - This attribute is needed by Cisco IdS in order to identify the realm of the authenticated user.

Claim Rule 1:

Add a rule by name NameID of the type (send the values of LDAP attribute as claims):

• Choose Attribute store as Active Directory
• Map LDAP attribute User-Principal-Name to user_principal (lowercase)
• Choose the LDAP attribute that must be used as userId for application users in order to log in and map it to uid (lowercase)

Example of Configuration when SamAccountName is to be used as the User Id:

• Map the LDAP attribute SamAccountName to uid.
• Map the LDAP attribute User-Principal-Name to user_principal.

Example Configuration when UPN must be used as the User Id:

• Map the LDAP attribute User-Principal-Name to uid.
• Map the LDAP attribute User-Principal-Name to user_principal.

Example of Configuration when PhoneNumber must be used as the User Id:

• Map the LDAP attribute telephoneNumber to uid .
• Map the LDAP attribute User-Principal-Name to user_principal.

Note: You must ensure that the LDAP attribute configured for the User ID on CUCM LDAP sync matches what is configured as the LDAP Attribute for uid in the ADFS claim rule NameID. This is for the proper functioning of the CUIC and Finesse login.

Note: This document references constraints on the claim rule name and displays names such as NameID, Fully Qualified Domain Name (FQDN) of UCCX, and so on. Though custom fields and names can be applicable at various sections, the claim rule names and display names are kept standard throughout to maintain consistency and for best practices in the naming convention.

Claim Rule 2:

• Add another rule of type custom claim rule with the name as the Fully Qualified Hostname of Cisco Identity Server and add this rule text.
  
  

  c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"] => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, 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://<ADFS Server FQDN>/ADFS/services/trust", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spnamequalifier"] = "<fully qualified hostname of IdS/UCCX>");

  
  
• In the Cisco Identity Server cluster, all Fully Qualified Hostnames are that of the Cisco Identity Server primary or publisher node.
• The <fully qualified hostname of Cisco Identity Server> is case-sensitive, so it matches exactly (case included) with the Cisco Identity Server FQDN.
• The <ADFS Server FQDN> is case-sensitive, so it matches exactly (case included) with the ADFS FQDN.

Step 8. Right-click on the Relying Party Trust and then click Properties and choose the advanced tab, as shown in the image.

Step 9. As shown in the image, choose Secure Hash Algorithm (SHA) as SHA-256.

Step 10. Click OK.

ADFS 3.0

Step 1. In the ADFS server, navigate to Server Manager > Tools > ADFS Management.

Step 2. Navigate to ADFS > Trust Relationship > Relying Party Trust.

Step 3. Choose the option Import data about the relying party from a file.

Step 4. Complete the establishment of the Relying Party Trust.

Step 5. In properties of the Relying Party Trust, choose the Identifier tab.

Step 6. Set the identifier as the Fully Qualified Hostname of the Cisco Identity Server from which sp.xml is downloaded.

Step 7. Right-click the Relying Party Trust and then click Edit Claim Rules.

You must add two claim rules, one is when the LDAP attributes are matched while the second is through custom claim rules.

uid - This attribute is needed for the applications to identify the authenticated user.
user_principal - This attribute is needed by Cisco IdS in order to identify the realm of the authenticated user.

Claim Rule 1:

Add a rule by name NameID of type (send the values of LDAP attribute as claims):

• Choose Attribute store as Active Directory
• Map LDAP attribute User-Principal-Name to user_principal (lowercase)
• Choose the LDAP attribute that must be used as userId for application users to log in and map it to uid(lowercase)

Example Configuration when SamAccountName is to be used as User Id:

• Map the LDAP attribute SamAccountName to uid.
• Map the LDAP attribute User-Principal-Name to user_principal.

Example Configuration when UPN must be used as User Id:

• Map the LDAP attribute User-Principal-Name to uid.
• Map the LDAP attribute User-Principal-Name to user_principal.

Example Configuration when PhoneNumber must be used as the User Id:

• Map the LDAP attribute telephoneNumber to uid.
• Map the LDAP attribute User-Principal-Name to user_principal.

Note: You must ensure that the LDAP attribute configured for the User ID on CUCM LDAP sync matches what is configured as the LDAP Attribute for uid in the ADFS claim rule NameID. This is for the proper function of CUIC and Finesse login.

Note: This document references constraints on the claim rule name and display names such as NameID, FQDN of UCCX, and so on. Though custom fields and names can be applicable at various sections, the claim rule names and display names are kept standard throughout in order to maintain consistency and for best practices in the naming convention.

Claim Rule 2:

• Add another rule of type custom claim rule with the name as the Fully Qualified Hostname of Cisco Identity Server and add this rule text.
                                

  c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"] => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, 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://<ADFS Server FQDN>/ADFS/services/trust", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spnamequalifier"] = "<fully qualified hostname of IdS/UCCX>");

  
  
• In the Cisco Identity Server cluster, all Fully Qualified Hostnames are that of the Cisco Identity Server primary or publisher node.
• The <fully qualified hostname of Cisco Identity Server> is case-sensitive, so it matches exactly (case included) with the Cisco Identity Server FQDN.
• The <ADFS Server FQDN> is case-sensitive, so it matches exactly (case included) with the ADFS FQDN.

Step 8. Right-click the Relying Party Trust and then click Properties and choose the advanced tab.

Step 9. As shown in the image, choose SHA as SHA-256.

Step 10. Click OK.

These steps are mandatory after Step 10.

Enable Signed SAML Assertions for the Relying Party Trust (Cisco IdS)

Step 1. Click Start and enter the PowerShell in order to open windows powershell.

Step 2. Add ADFS CmdLet to the PowerShell with the command Add-PSSnapin Microsoft.Adfs.Powershell.

Step 3. Run the command, Set-ADFSRelyingPartyTrust -TargetName <Relying Party Trust Name> -SamlResponseSignature "MessageAndAssertion".

          

Note: Step 2. is not needed if you use ADFS 3.0 since the CmdLet is already installed as a part of the addition of the roles and features.

Note: The <Relying Party Trust Identifier> is case-sensitive, so it matches (case included) with what is set in the Identifier tab of the Relying Party Trust properties.

Note: From UCCX version 12.0 Cisco IdS supports SHA-256. The Relying Party Trust uses SHA-256 to sign the SAML request and expects the same response from ADFS.

For a Multi-Domain Configuration for Federated ADFS

In the case of Federation in ADFS, where an ADFS in a particular domain provides federated SAML authentication for users in other configured domains, these are needed additional configurations.

For this section, the term primary ADFS refers to the ADFS that must be used in IdS. The term Federated ADFS indicates those ADFS, whose users can log in via IdS and thus, are the primary ADFS.

Federated ADFS Configuration

In each of the federated ADFS, the Relying Party Trust must be created for the primary ADFS and the claim rules configured as mentioned in the previous section.

Primary ADFS Configuration

For primary ADFS, apart from the Relying Party Trust for IdS, this additional configuration is needed.

Add Claim Provider Trust with the ADFS to which the federation must be set up.

In the Claim Provider Trust, ensure that the Pass through or Filter an Incoming Claim rules are configured with pass-through all claim values as the option:

• Name ID
• Choose Name ID from the Incoming Claim Type dropbox
• Choose Transient as the option for Incoming NameID format
• uid: This is a custom claim. Enter the value uid in the Incoming Claim Type dropbox
• user_principal: This is a custom claim. Type the value user_principal in the Incoming Claim Type dropbox

In the Relying Party Trust for IdS, add Pass though or Filter an Incoming Claim rules with pass-through all claim values as the option.

• NameIDFromSubdomain
• Choose Name ID from Incoming Claim Type dropbox
• Choose Transient as the option for Incoming NameID format
• uid: This is a custom claim. Type the value uid in the Incoming Claim Type dropbox
• user_principal: This is a custom claim. Type the value user_principal in the Incoming Claim Type dropbox

ADFS Automatic Certificate Rollover

Automatic Certificate Rollover is supported for UCCX 11.6.1 and later. (The Fedlet library upgrade to Version 14.0 in UCCX 11.6 resolved this issue.)

Kerberos Authentication (Integrated Windows Authentication)

Integrated Windows Authentication (IWA) provides a mechanism for the authentication of the users but does not allow credentials to be transmitted over the network. When you enable integrated Windows authentication, it works on the basis of tickets in order to allow nodes to communicate over a non-secure network in order to prove their identity to one another in a secure manner. It enables users to log into a domain after login to their Windows machines.

Note: Kerberos authentication is supported only from 11.6 and later.

Domain users who are already logged into the domain controller (DC)  are seamlessly logged into SSO clients without the need to re-enter the credentials. For non-domain users, IWA falls back to New Technology Local Area Network Manager (NTLM) and the login dialog appears. The qualification for IdS with IWA authentication is done with Kerberos against ADFS 3.0.

Step 1. Open the Windows command prompt and run as an Admin user in order to register HTTP service with the setspn command setspn -s http/<ADFS url> <domain>\<account name>.

Step 2. Disable Form Authentication and enable Windows Authentication for Intranet sites. Navigate to ADFS Management > Authentication Policies > Primary Authentication > Global Settings > Edit. Under Intranet, ensure that only Windows Authentication is checked (uncheck Form Authentication).

Configuration for Microsoft Internet Explorer for IWA Support

Step 1. Ensure that Internet Explorer > Advanced > Enable Integrated Windows Authentication is checked.

Step 2. ADFS URL must be added to Security > Intranet zones > Sites  (winadcom215.uccx116.com is the ADFS URL).

Step 3. Ensure thatInternet Explorer > Security > Local Intranet > Security Settings > User Authentication - Logon  is configured in order to use the logged-in credentials for intranet sites.

Configuration Required for Mozilla Firefox for IWA Support

Step 1. Enter the configuration mode for Firefox. Open Firefox and enter about:config  in the URL. Accept the risks statement.

Step 2. Search for ntlm  and enable the network.automatic-ntlm-auth.allow-non-fqdn  and set it to true.

Step 3. Set the network.automatic-ntlm-auth.trusted-uris  to the domain or explicitly the ADFS URL.

Configuration Required for Google Chrome for IWA Support

Google Chrome in Windows uses the Internet Explorer settings, so configure within Internet Explorer Tools > Internet Options dialog, or from Control Panel under Internet Options within the sub-category Network and Internet.

Further Configuration for SSO

This document describes the configuration from the IdP aspect for SSO in order to integrate with the Cisco IdS. For further details, refer to the individual product configuration guides:

• UCCX
• UCCE
• PCCE

Verify

This procedure is used to determine if the Relying Party Trust is established properly between Cisco IdS and IDP.

• From broswer enter the URL https://<ADFS_FQDN>/adfs/ls/IdpInitiatedSignOn.aspx?loginToRp=<IDS_FQDN>
• ADFS provides the login form. This is available when the mentioned configuration is right.
• On successful authentication, the browser must redirect to https://<IDS_FQDN>:8553/ids/saml/response, and a checklist page appears.

Note: The Checklist page which appears as a part of the verification process is not an error but a confirmation that the trust is properly established.

Troubleshoot

For troubleshooting refer to https://www.cisco.com/c/en/us/support/docs/customer-collaboration/unified-contact-center-express/200662-ADFS-IdS-Troubleshooting-and-Common-Prob.html.

UCCX SSO Bypass/Recovery URLs

• Cisco Unified CCX Administration
• Cisco Unified CCX Serviceability

Disable SSO

• GUI: Navigate to CCX Administration > Single Sign-On (SSO) > Disable.
• CLI: set authmode non_sso (this command must disable SSO for both Pub and Sub - can be executed from either on the UCCX nodes in case of a High Availability (HA) cluster).

Screencaptures

CCX Administration - Non_SSO

CCX Administration - SSO Enabled

Finesse Login - Non-SSO

Finesse Login - SSO Enabled

CUIC - Non_SSO

CUIC - SSO Enabled