Configure the Identity Provider for Cisco Identity Service to enable SSO

Introduction

This document describes the configuration on the Identity Provider (IdP) to enable Single Sign On (SSO).

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.

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 screenshots and examples, however the configuration is similar with respect to the Cisco Identitify Service (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, make sure that you understand the potential impact of any command.

Background Information

Overview of SSO

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

SSO using 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 Identity Service supports only form based authentication of Identity Provider.

Please refer these MSDN articles 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 refer to this Microsoft TechNet article,
  https://blogs.msdn.microsoft.com/josrod/2014/10/15/enabled-forms-based-authentication-in-AD FS-3-0/

Note: Cisco Identity Service 11.6 and above supports both form based authentication and Kerberos authentication. For Kerberos authentication to work, you must disable the Form based authentication.

Establish Trust Relationship 

For onboarding and enabling applications to use Cisco Identity Service for Single Sign-On, perform the metadata exchange between the Identity Service (IdS) and IdP.

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

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

• On the Identity Service Management page, upload the Identity Provider Metadata file that was downloaded in 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 ADFS server navigate to, Start > All Programs > Administrative Tools > AD FS 2.0 Management, as shown in the image:

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

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

Step 4. Complete the establishing of the relying party trust.

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

Step 6. Set the identifier as the fully qualified hostname of Cisco Identity Server from which sp.xml is downloaded.

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

You need to 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 to identify the authenticated user.
user_principal - This attribute is needed by Cisco Identity Service 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):

• Select Attribute store as Active Directory.
• Map Ldap attribute User-Principal-Name to user_principal (lowercase).
• Choose the LDAP attribute that has to 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 has to 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 has to be used as user Id -

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

Note: We need to ensure that the LDAP attribute configured for User ID on CUCM LDAP sync should match what is configured as the LDAP Attribute for uid in the ADFS claim rule NameID. This is for proper functioning of Cisco Unified Intelligence Center (CUIC) and Finesse login.

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

Claim Rule 2:

• Add another rule of type custom claim rule with name as the Fully Qualified Hostname (FQDN) 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 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 (including case) with the Cisco Identity Server FQDN.
  
  
• The <ADFS Server FQDN> is case-sensitive, so it matches exactly (including case) with the ADFS FQDN.

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

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

Step 10. Click OK.

ADFS 3.0:

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

Step 2. Navigate to AD FS > Trust Relationship > Relying Party Trust.

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

Step 4. Complete the establishing of the relying party trust.

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

Step 6. Set the identifier as the fully qualified hostname of Cisco Identity Server from which sp.xml is downloaded.

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

You need to 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 to identify the authenticated user.
user_principal - This attribute is needed by Cisco Identity Service 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):

• Select Attribute store as Active Directory.
• Map Ldap attribute User-Principal-Name to user_principal (lowercase).
• Choose the LDAP attribute that has to 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 has to 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 has to be used as user Id -

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

Note: We need to ensure that the LDAP attribute configured for User ID on CUCM LDAP sync should match what is configured as the LDAP Attribute for uid in the ADFS claim rule NameID. This is for proper functioning of Cisco Unified Intelligence Center (CUIC) and Finesse login.

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

Claim Rule 2:

• Add another rule of type custom claim rule with name as the Fully Qualified Hostname (FQDN) 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 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 (including case) with the Cisco Identity Server FQDN.
  
  
• The <ADFS Server FQDN> is case-sensitive, so it matches exactly (including case) with the ADFS FQDN.

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

Step 9. As shown in the image, select Secure Hash Algorithm (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 Identity Service)

Step 1. Click Start and enter powershell to open windows powershell.

Step 2. Add ADFS CmdLet to the powershell by running the command Add-PSSnapin Microsoft.Adfs.Powershell.

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

-SamlResponseSignature "MessageAndAssertion".

          

Note: Step 2 may not be needed if you are using ADFS 3.0 since the CmdLet is already installed as a part of adding the roles and features.

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

Note: Starting UCCX version 12.0 Cisco Identity Service supports SHA-256. The relying party trust uses SHA-256 for signing the SAML request and expects ADFS to do the same in the response.

For a Multi-domain Configuration for Federated ADFS

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

For this sections, the term primary ADFS refers to the ADFS that has to be used in IdS. The term Federated ADFS indicates those ADFS, whose users are allowed to log in via IdS and thus, is the primary ADFS.

Federated ADFS Configuration

In each of the federated ADFS, the relying party trust has to be created for 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, the following additional configuration is needed.

Add Claim Provider Trust with the ADFS to which federation has to be setup.

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 Incoming Claim Type drop box
• Choose Transient as the option for Incoming NameID format
• uid: This is a custom claim. Enter the value uid in the Incoming Claim Type drop box.
• user_principal: This is a custom claim. Type the value user_principal in the Incoming Claim Type drop box.

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 drop box
• Choose Transient as the option for Incoming NameID format
• uid: This is a custom claim. Type the value uid in the Incoming Claim Type drop box
• user_principal: This is a custom claim. Type the value user_principal in the Incoming Claim Type drop box

ADFS Automatic Certificate Rollover

• Automatic Certificate Rollover is supported for UCCX 11.6.1 and above. [This was fixed in UCCX 11.6 by upgrading the Fedlet library to Version 14.0]

Kerberos Authentication (Integrated Windows Authentication)

Integrated Windows Authentication (IWA) provides mechanism for authentication of 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 to allow nodes communicating over a non-secure network to prove their identity to one another in a secure manner. It allows users to login to a domain after login into their windows machines. 

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

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

Step 1. Open Windows command prompt and run as Admin user to register http service with setspn command 

             setspn -s http/<ADFS url> <domain>\<account name> .

Step 2. Disable Form Authentication and enable Windows Authentication for Intranet sites. Go 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 needs to be added to Security >Intranet zones > Sites (winadcom215.uccx116.com is ADFS url)

Step 3. Ensure that Internet Exporer  > 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 into the configuration mode for Firefox. Open Firefox and enter about:config on 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's Tools >Internet Options dialog, or from Control Panel under Internet Options within sub-category Network and Internet.

Further Configuration for SSO:

This document describes the configuration from the IdP aspect for SSO to integrate with the Cisco Identity Service. 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 will provide the login form. This will be available when the above configuration is right.
• On successful authentication, browser should redirect to https://<IDS_FQDN>:8553/ids/saml/response and a checklist page will appear.

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 troubleshoot refer - 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

• URL for Cisco Unified CCX Administration:https://<IP_or_FQDN>/appadmin/recovery_login.htm
• URL for Cisco Unified CCX Serviceability:https://<IP_or_FQDN>/uccxservice/recovery_login.htm

Disabling SSO

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

Screenshots

CCX Administration - Non_SSO:

CCX Administration - SSO Enabled:

Finesse Login - Non-SSO:

Finesse Login - SSO Enabled:

CUIC - Non_SSO:

CUIC - SSO Enabled: