Configure and Troubleshoot SSO for Agents and Partition Admin in ECE

Introduction

This document describes the steps required to configure Single Sign-On (SSO) for Agents and Partition Administrators in an ECE solution.

Prerequisites

Requirements

Cisco recommends that you have knowledge of these topics:

Cisco Packaged Contact Center Enterprise (PCCE)

Cisco Unified Contact Center Enterprise (UCCE)

Enterprise Chat and Email (ECE)

Microsoft Active Directory

Components Used

The information in this document is based on these software and hardware versions:

UCCE Version: 12.6(1)

ECE Version: 12.6(1)

Microsoft Active Directory Federation Service (ADFS) on Windows Server 2016

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

Enterprise Chat and Email (ECE) consoles can be accessed outside of Finesse, however, SSO must be enabled to allow agents and supervisors to log in to ECE through Finesse.

Single Sign-On can also be configured for new partition administrators. This ensures that new users who log in to Cisco Administrator desktop are granted access to the Enterprise Chat and Email Administration Console. 

Important things to note about Single Sign-On:

• The process of configuring a system for single sign-on must be performed to the Security node at the partition level by a partition user with the necessary actions: View Application Security and Manage Application Security.
• For supervisors and administrators to log into the consoles other than the Agent Console, once SSO is enabled, you must provide a valid External URL of the Application in the partition settings. See General Partition Settings for more information.
• A Java Keystore (JKS) certificate is needed to configure SSO to allow users with administrator or supervisor roles to sign in to partition 1 of ECE outside of Finesse using their SSO login credentials. Consult your IT department to receive the JKS certificate.
• A Secure Sockets Layer (SSL) certificate of Cisco IDS must be imported to all application servers in an installation. To obtain the necessary SSL certificate file, contact your IT department or Cisco IDS support.
• DB server collation for Unified CCE is case-sensitive. The username in the claim returned from the user info endpoint URL and the username in Unified CCE must be same. If they are not the same, single sign-on agents are not recognized as logged in and ECE cannot send agent availability to Unified CCE.
• Configuring SSO for Cisco IDS affects users who have been configured in Unified CCE for Single Sign-On. Ensure that the users you wish to enable for SSO in ECE are configured for SSO in Unified CCE. Consult your Unified CCE administrator for more information.

Note:

• Ensure that the users you wish to enable for SSO in ECE are configured for SSO in Unified CCE.
• This document specifies the steps to configure Relying Part Trust for ECE in a Single AD FS Deployment where Resource Federation Server and Account Federation Server are installed on the same machine.
• For a Split AD FS deployment, navigate to the ECE Install and Configure guide for the respective version.

Configuration Steps

Configuring Relying Party Trust for ECE

Open AD FS Management console and navigate to AD FS > Trust Relationships > Relying Party Trust.

In the Actions section, click on Add Relying Party Trust...

In the Add Relying Party Trust wizard, click on Start and complete the next steps:

a. In the Select Data Source page, select the Enter data about the reply party manually option and click Next.

b. In the Specify Display Name page, provide a Display name for the relying party. Click Next

c. In the Configure URL page:

i. Select the Enable support for the SAML 2.0 Web SSO protocol option.

ii. In the Relying Party SAML 2.0 SSO server URL field provide the URL in the format: https://<Web-Server-Or-Load-Balancer-FQDN>/system/SAML/SSO/POST.controller

d. In the Configure Identifiers page, provide the Relying party trust identifier and click Add.

• Value must be in the format: https://<Web-Server-Or-Load-Balancer-FQDN>/

e. In the Choose Access Control Policy page, click next with the default value 'Permit everyone' policy.

f. In the Ready to Add Trust page, click Next.

g. Once the relying party trust is successfully added, click Close.

In the Relying Provider Trusts list, select the Relying Party trust created for ECE and in the actions section click Properties.

In the Properties window, navigate to the Endpoints tab and click the Add SAML.. button

In the Add an Endpoint window, configure as noted:

1. Select the Endpoint type as SAML Logout.
2. Specify the Trusted URL as https://<ADFS-server-FQDN>/adfs/ls/?wa=wsignoutcleanup1.0
3. Click OK.

In the Relying Provider Trusts list, select the trust created for ECE, and in the actions section click Edit Claim Insurance Policy.

In the Edit Claim Insurance Policy window, under the Issuance Transform Rules tab, click the Add Rule... button and configure as shown:

a. In the Choose Rule Type page, select Send LDAP Attributes as Claims from the drop down and click Next.

b. In the Configure Claim Rule page:

1. Provide the Claim rule name and select the Attribute store.
2. Define mapping of LDAP attribute and the outgoing claim type. 

• Select Name ID as the outgoing claim type name.
• Click Finish to go back to the Edit Claim Insurance Policy window and then click OK.

In the Relying Provider Trusts list, double-click the ECE relying party trust which you created. 

In the Properties window that opens, go to the Advanced tab and set the Secure hash algorithm to SHA-1 or SHA-256. Click OK to close the window.

Note: This value must need to match the 'Signing algorithm' value set for the 'Service Provider' under SSO Configurations in ECE

Verify and note down the Federation Service Identifier value.

• In the AD FS Management console, select and right click AD FS > Edit Federation Service Properties > General tab > Federation Service Identifier

Note:

• This value must be added exactly as is when configuring the 'Entity ID' value for Identity Provider under SSO Configurations in ECE.
• Using http:// does NOT mean that ADFS is not secure, this is simply an identifier.

Configuring an Identity Provider

A Java Keystore (JKS) certificate is needed to configure SSO to allow users with administrator or supervisor roles to sign in to partition of ECE outside of Finesse using their SSO login credentials.

If you wish to configure SSO to allow users with administrator or supervisor roles to sign in to the partition of ECE outside of Finesse using their SSO login credentials, the Java Keystore (JKS) certificate must be converted to public key certificate and configured in Relying Party Trust created on the IdP server for ECE.

Consult your IT department to receive the JKS certificate.

Note: These steps are applicable for systems using ADFS as the identity provider. Other identity providers can have different methods to configure public key certificate.

Here is an example of how a JKS file was generated in the lab:

a. Generate JKS:

keytool -genkey -keyalg RSA -alias ece126web1a_saml -keystore C:\Temp\ece126web1a_saml.jks -keysize 2048 -validity 1825

Note: The keystore password, alias name, and key password entered here are used while configuring 'Service Provider' config under SSO Configurations in ECE.

b. Export the certificate:

This keytool command exports the certificate file in the.crt format with file name ece126web1a_saml.crt into the C:\Temp directory.

keytool -exportcert -alias ece126web1a_saml -keystore C:\Temp\ece126web1a_saml.jks -rfc -file C:\Temp\ece126web1a_saml.crt

Configuring an Identity Provider

1. On the AD FS Management console, select and right click the Relying Party Trust created for ECE.
2. Open the Properties window for the trust and under the Signature tab, click the Add button.
3. Add the public certificate (.crt file generated in the previous step) and click OK.

Creating and Importing Certificates

Before configuring SSO to use Cisco IDS for Single Sign-On for Agents, the Tomcat certificate from the Cisco IdS server must be imported into the application.

a. In the ECE Admin console, under partition-level Menu, click the Security option and then select Certificate Management from the left side Menu.

b. In the Certificate Management space, click the New button and enter the appropriate details:

• Name: Type a name for the certificate.
• Description: Add a description for the certificate.
• Component Type: Select CISCO IDS.
• Import Certificate: To import the certificate, click the Search and Add  button and enter the details requested:
• Certificate file: Click the Browse button and select the certificate you wish to import. The certificates can only be imported in the .pem, .der (BINARY), or .cer/cert formats.
• Alias Name: Provide an alias for your certificate.

c. Click Save

Configuring Agent Single Sign-On

1. In the ECE Admin console, under partition-level Menu, click the Security option and then select Single Sign-On > Configurations from the left side Menu.
2. In the Select Configuration drop down, select Agent and set the configuration under the General tab:

• Enable Single Sign-On: Click the Toggle button to enable SSO.
• Single Sign-On Type: Select Cisco IDS.

Click the SSO Configuration tab and provide the configuration details:

a. OpenID Connect Provider

Primary User Info Endpoint URL

• The User Info Endpoint URL of the primary Cisco IDS server.
• This URL validates the user token/User Info API.  
• It is in format: https://cisco-ids-1:8553/ids/v1/oauth/userinfo where cisco-ids-1 indicates the Fully Qualified Domain Name (FQDN) of the Primary Cisco IDS server.

User Identity Claim Name

• The name of the claim returned by the User Info Endpoint URL, which identifies the username in Unified or Packaged CCE. 
• The claim name and the username in Unified or Packaged CCE must match.
• This is one of the claims obtained in response to the Bearer token validation.
• If the username of agents in Unified or Packaged CCE matches the User Principal Name, provide “upn” as the value for User Identity Claim name field.
• If username of agents in Unified or Packaged CCE matches with the SAM Account Name, provide “sub” as the value for User Identity Claim name field.

Secondary User Info Endpoint URL

• The secondary user Info Endpoint URL of the Cisco IDS server.
• It is in format: https://cisco-ids-2:8553/ids/v1/oauth/userinfo where cisco-ids-2 indicates the Fully Qualified Domain Name (FQDN) of the Secondary Cisco IDS server.

User Info Endpoint URL Method

• The HTTP method used by ECE for making Bearer token validation calls to the User Info Endpoint URL.
• Select POST from the list of options presented (POST is selected here to match the IDS server’s method).

POST: Method used to send data to the Cisco IDS server at the specified endpoint.

Access Token Cache Duration (Seconds)

• The duration, in seconds, for which a Bearer token must be cached in ECE. 
• Bearer tokens for which validation calls are successful are only stored in caches. (Minimum value: 1; maximum value 30)

Allow SSO Login Outside Finesse

• Click this Toggle button if you wish to allow users with administrator or supervisor roles to sign into the partition of ECE outside of Finesse using their SSO login credentials.
• If enabled, information under the Identity Provider and Service Provider sections must be provided.
• This requires that your IdP configuration allows for a shared IdP server.

b. Identity Provider

Entity ID

• Entity ID of the IdP server.

Note: This value must match exactly as the 'Federation Service Identifier' value in the AD FS Management console.

Identity Provider Certificate

• The public key certificate.
• The certificate must start with “-----BEGIN CERTIFICATE-----” and end with “-----END CERTIFICATE-----”
• This is the Token-signing certificate in the AD FS Management Console > Service > Certificates > Token-signing.

User Identity Location

• Select SAML Subject Identifier to set the identity location in the certificate to the default SAML subject identifier, as in the subject in the SAML assertion, for example, the username in the <saml:Subject>.
• Select SAML Attribute to assign the identity location to a specific attribute in the certificate, for example, email.address. Provide the attribute in the User Identity  Attribute Name field.

User Identity Attribute Name

• Applicable only when User ID Location value is an SAML attribute.
• This can be adjusted within the SAML assertion and used to select a different attribute for the authentication of users, such as an email address.
• It can also be used to create new users with a SAML Attribute.
• For example, if a user is identified through the value provided in the email.address attribute, and the value of email address provided does not match any user in the system, a new user is created with the provided SAML attributes.

Enable Encrypted Assertion (Optional)

• If you wish to enable encrypted assertion with the Identity Provider for console login, click the Toggle button set the value to Enabled.
• If not, set the value to Disabled.

Assertion Decryption Certificate

If Enable encrypted assertion is set to Enabled, click the Search and Add  button and confirm your choice to change the certificate.

Provide the details in the Assertion Decryption Certificate window:

• Java Keystore File: Provide the file path of your Java Keystore File. This file is in the .jks format and contains the decryption key the system needs to access files secured by the Identity Provider.
• Alias Name: The unique identifier for the decryption key.
• Keystore Password: The password required for accessing the Java Keystore File.
• Key Password: The password required for accessing the Alias' decryption key.

Note: This needs to match the certificate in the 'Encryption' tab of the configured ECE Relying Party Trust on AD FS Management console.

c. Service Provider

Service Provider Initiated Authentication

• Set the toggle button to Enabled.

Entity ID

• Provide the External URL of the ECE application.

Request Signing Certificate

• A Java Keystore (JKS) certificate is needed to provide the necessary information.
• Upload the .jks file using the alias name and keystore/key password generated in step 11.

Note: This needs to match the certificate uploaded to the 'Signature' tab of the configured ECE Relying Party Trust on AD FS Management console.

Signing Algorithm

• Set the signing algorithm for the service provider.
• If using ADFS, this value must match with the algorithm selected in the relying party trust created for ECE under the Advanced tab.

Identity Provider Login URL

• The URL for SAML authentication.
• For example, for ADFS, this would be http://<ADFS>/adfs/ls.

Identity Provider Logout URL

• The URL to which users are redirected upon logging out. This is optional and can be any URL. 
• For example, agents can be redirected to https://www.cisco.com or any other URL after SSO logout.

Click Save

Set the Web Server/LB URL in the Partition settings

Ensure the correct Web Server/LB URL is entered under the Partition settings > select the Apps tab and navigate to General Settings > External URL of the Application

Configuring SSO for Partition Administrators

Note:

• This step applies to PCCE only.
• This is for the ECE gadget accessed within CCE Admin WEB interface https:///cceadmin.

To configure SSO for Partition Administrator

1. In the ECE Admin console, under partition-level Menu, click the Security option and then select Single Sign-On > Configurations from the left side Menu.
2. In the Select Configuration drop down, select Partition Administrators and enter the configuration details:

LDAP URL

• The URL of the LDAP server.
• This can be Domain Controller URL (for example, ldap://LDAP_server:389) or Global Catalog URL (for example, ldap://LDAP_server:3268) of the LDAP server.
• Partition can be added automatically to the system when ECE is accessed via the CCE Administration Console if ECE is configured with LDAP lookup. 
• However, in Active Directory deployments with multiple domains in a single forest or where Alternate UPNs are configured, the Domain Controller URL with the standard LDAP ports of 389 and 636 must not be used.
• The LDAP integration can be configured to use the Global Catalog URL with ports 3268 and 3269.

Note: It is best practice to use Global Catalog URL. If you do not use a GC, an error in the ApplicationServer logs is as follows.

• Exception in LDAP authentication <@>
  javax.naming.PartialResultException: Unprocessed Continuation Reference(s); remaining name 'DC=example,DC=com'

DN attribute

• The attribute of the DN that contains the user login name.
• For example, userPrincipalName.

Base

• The value specified for Base is used by the application as the search base.
• Search base is the starting location for search in LDAP directory tree.
• For example, DC=mycompany, DC=com.

DN for LDAP search

• If your LDAP system does not allow anonymous bind, provide the Distinguished Name (DN) of a user who has search permissions on the LDAP directory tree.
• If the LDAP server allows anonymous bind, leave this field blank.

Password

• If your LDAP system does not allow anonymous bind, provide the password of a user who has search permissions on the LDAP directory tree.
• If the LDAP server allows anonymous bind, leave this field blank.

Click Save

This now completes the Single Sign-On configuration for Agents and Partition Administrators in ECE.

Troubleshooting 

Setting Trace level 

1. In the ECE Admin console, under partition-level Menu, click the System Resources option and then select Process Logs from the left side Menu.
2. From the list of the processes, select the ApplicationServer process > set the desired trace level from the 'Maximum Trace Level' drop down menu.

Note:

• For troubleshooting the SSO login errors during initial setup or re-configuration, set the ApplicationServer process trace to level 7.
• Once the error is reproduced, set the trace level back to the default level 4, to avoid overwriting of the logs.

Troubleshooting Scenario 1

Error

• Error Code: 500
• Error Description: The application is not able to login the user at this time as Identity Provider login failed.

Log Analysis

• IdP login failed - <samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Responder" /></samlp:Status>
• Here the status "Responder" indicates that there is some issue on the AD FS side - in this case, primarily with the "Request Signing certificate" uploaded on ECE Admin console (SSO Configuration > Service Provider) and the certificate uploaded to the ECE Relying Party Trust under the 'Signature' tab.
• This is the certificate that is generated using the Java Keystore File.

unmarshallAndValidateResponse:
2022-09-21 18:18:15.002 GMT+0000 <@> ERROR <@> [392364:qtp1158258131-392364] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:72d5a2a7-5520-4e8a-83a0-bc2b5d87ee38 <@> com.egain.platform.module.security.sso.handler.SAML2_0_Handler <@> unmarshallAndValidateResponse() <@> IdP login failed. Status code is NOT 'Success' in SAML Response token: <samlp:Response ID="_99e9ec67-5c53-43e3-9d53-79afb5fe95ee" Version="2.0" IssueInstant="2022-09-21T18:18:14.640Z" Destination="<fqdn>/system/SAML/SSO/POST.controller" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" InResponseTo="EG_f75b996b-0fe5-4236-a4ad-fa634dcbc6f6" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"><Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">adfs/adfs/services/trust</Issuer><ds:Signature xmlns:ds="<fqdn>/2000/09/xmldsig#"><ds:SignedInfo><ds:CanonicalizationMethod Algorithm="<fqdn>/2001/10/xml-exc-c14n#" /><ds:SignatureMethod Algorithm="<fqdn>/2001/04/xmldsig-more#rsa-sha256" /><ds:Reference URI="#_99e9ec67-5c53-43e3-9d53-79afb5fe95ee"><ds:Transforms><ds:Transform Algorithm="<fqdn>/2000/09/xmldsig#enveloped-signature" /><ds:Transform Algorithm="<fqdn>/2001/10/xml-exc-c14n#" /></ds:Transforms><ds:DigestMethod Algorithm="<fqdn>/2001/04/xmlenc#sha256" /><ds:DigestValue>gAlphYvLYvUBRdX6WJSFCOZ0Ph+/HB2JHnDxUmbluXg=</ds:DigestValue></ds:Reference></ds:SignedInfo><ds:SignatureValue>HRLRYAL94nIB14/LVlrGpxNyz1ddR/pfCN4pDVTVuBWXJCCpXPHcIVuqWYHKh9gnj/QPqNwZktmKcOZTB2tviOucNhDO5r4DiqEk90R29spAVvlWEsUiVmq+hJOafoDwXk0p+uCXGAJuIsEgOVOtMQrGZSi1zHT6r6hzBb9lC2MhKryey+p34bGHxA2doHSshXpbYhVRjVGUAqpkh614Mb9bfW0fzjgVgxrXQzevRAJBKmoj+nuiOInBISxMD+bjJ1mcTCcnUCQQQ7lYwQZ/v/ux0ht5HelI9VGt90ExwjNiEUXQTzxvqGbAlDDX4K/lEGfIS/JwWo+rWDa4j1IN5Q==</ds:SignatureValue><KeyInfo xmlns="<fqdn>/2000/09/xmldsig#"><ds:X509Data><ds:X509Certificate>MIIC6DCCAdCgAwIBAgIQE/XRfyPrEYpMPM0XB1NU/DANBgkqhkiG9w0BAQsFADAwMS4wLAYDVQQDEyVBREZTIFNpZ25pbmcgLSBhZGZzLm9zZmhlYWx0aGNhcmUub3JnMB4XDTIwMDgxNjA5MjkyNVoXDTIzMDgxNjA5MjkyNVowMDEuMCwGA1UEAxMlQURGUyBTaWduaW5nIC0gYWRmcy5vc2ZoZWFsdGhjYXJlLm9yZzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAO7LWemQO5VBCOCuXEhzx89HwlhAUyweAIC9RKkEbZGEI4oqI7OKhwuG5IerHo1qM2I08A4bOYZV7rgWD6Kn8MCyn4UsByw0TRjdu2FZQlMzJA1xnfzVhFMAsWPj3wATjpPnHivqzUK1nBLgalc/GgqSOr7dacjCQSngKqDIAJwgrRLZDapEdbI3ZfTsxHugMR5g9eFwpwAsfoizR63EHhd+NRJ2NUhRQoej/WMGhMqJpxxiZQ0vmllZHfw7CRLRPCpkMlALpEFz0DQnozpOMMlz7uEgTuXxFTfdPhA6j5AL1YoF6ZNBo/8+HiPu6+aE0melxEl6AJOghSQY60JsmkECAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAwTl/KRw4cHb615bO3bqWf9YqkMQ40+hGO27Hv/So3vuQFh5b0vzdK35diOAQSjh8RUgeNT3x7CXOGic5qYtXpZVkYsEFWMO8l0O517v576no1IQNtv+rEa3cU3J0NR5U6JfGXtzfTiqu1MFCoGybVZZi9oZeBSiICObO13YBdavZUDrhIRAXenQD0yWtbWKqMMV5gxEhSAn9LAXpctaYPJx4LAw1Q1xvJ52AzyaSm3AxLkfzw0RPF4twCUuX4O+bCFRw+3ibAib1h1eCCItryBNBeIpP7mMnDpZDVJdEjX40pvku80i3c5gxzuVOwak+dd5KzqghxrSUblIdEBWoEg==</ds:X509Certificate></ds:X509Data></KeyInfo></ds:Signature><samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Responder" /></samlp:Status></samlp:Response>. => Check IdP error log at the time of this error. <@>
2022-09-21 18:18:15.002 GMT+0000 <@> INFO <@> [392364:qtp1158258131-392364] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:72d5a2a7-5520-4e8a-83a0-bc2b5d87ee38 <@> com.egain.platform.module.security.sso.admin.SSOAdministrator <@> validateRequestWithAttributes() <@> tokenState: NULL <@>

L10N_USER_STATUS_CODE_ERROR:
2022-09-21 18:18:15.002 GMT+0000 <@> ERROR <@> [392364:qtp1158258131-392364] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:72d5a2a7-5520-4e8a-83a0-bc2b5d87ee38 <@> com.egain.platform.module.security.sso.controller.SSOControllerServlet <@> redirectToApiErrorPage() <@> User SSO: SSOLoginException caught. L10N file path: pl/resourcetype/sso. L10N string: L10N_USER_STATUS_CODE_ERROR <@> - com.egain.platform.module.security.sso.exception.SSOLoginException: null
at com.egain.platform.module.security.sso.handler.SAML2_0_Handler.unmarshallAndValidateResponse(SAML2_0_Handler.java:514) ~[egpl_application_classes.jar:?]
at com.egain.platform.module.security.sso.handler.SAML2_0_Handler.validateReqWithAttributes(SAML2_0_Handler.java:208) ~[egpl_application_classes.jar:?]
at com.egain.platform.module.security.sso.handler.SAML2_0_Handler.validateReqWithAttributes(SAML2_0_Handler.java:163) ~[egpl_application_classes.jar:?]
at com.egain.platform.module.security.sso.handler.OpenIDConnect_Handler.validateReqWithAttributes(OpenIDConnect_Handler.java:441) ~[egpl_application_classes.jar:?]
at com.egain.platform.module.security.sso.admin.SSOAdministrator.validateRequestWithAttributes(SSOAdministrator.java:131) ~[egpl_application_classes.jar:?]
at com.egain.platform.module.security.sso.controller.SSOControllerServlet.doPost(SSOControllerServlet.java:106) ~[egpl_application_classes.jar:?]
.
.
.
.
at java.lang.Thread.run(Thread.java:834) ~[?:?]

errorCode=500&errorString=The application is not able to login the user at this time as Identity Provider login failed:
2022-09-21 18:18:15.003 GMT+0000 <@> DEBUG <@> [392364:qtp1158258131-392364] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:72d5a2a7-5520-4e8a-83a0-bc2b5d87ee38 <@> com.egain.platform.client.util.i18n.L10NUtil <@> getLocalizedMessage(CallerContext, Locale, String, l10nKey, String[]) <@> In method getLocalizedMessage: pl/resourcetype/sso L10N_USER_STATUS_CODE_ERROR null <@>
2022-09-21 18:18:15.003 GMT+0000 <@> DEBUG <@> [392364:qtp1158258131-392364] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:72d5a2a7-5520-4e8a-83a0-bc2b5d87ee38 <@> com.egain.platform.module.security.sso.controller.SSOControllerServlet <@> redirectToApiErrorPage() <@> WS API SSO errorURL => /system/web/view/platform/admin/security/sso/context/errorpage.html?errorCode=500&errorString=The application is not able to login the user at this time as Identity Provider login failed. If the problem persists, please contact your system administrator.&errorKey=L10N_USER_STATUS_CODE_ERROR&locale=en-US <@>

Resolution

• Refer the 'Request Signing Certificate' configuration under the section 'Configuring Agent Single Sign-On - Service Provider'.
• Ensure the Java Keystore .jks file generated in Step 11 is uploaded to the "Request Signing certificate" field on ECE Admin console under SSO Configuration > Select Configuration 'Agent' > 'SSO Configuration' tab > Service Provider > Request Signing certificate.
• Ensure the .crt file is uploaded under the 'Signature' tab of the ECE Relying Party Trust (Step 12).

Troubleshooting Scenario 2

Error

• Error Code: 400
• Error Description: SAML Response token is invalid: signature validation failed.

Log Analysis

• This error indicates that there is a mismatch in the certificate between the 'Token-signing certificate' on ADFS and the 'Identity provider certificate' on the ECE SSO Configuration.

Entering 'validateSSOCertificate' and validating the saml response against certificate:
2022-10-07 15:27:34.523 GMT+0000 <@> DEBUG <@> [537838:qtp1158258131-537838] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:a5a413c1-24a0-aaaa-bed2-83b50f1a9915 <@> com.egain.platform.module.security.sso.handler.SAML2_0_Handler <@> validateSSOCertificate() <@> Entering validateSignatureAndCertificate() method.validating the saml response against certificate <@>
2022-10-07 15:27:34.520 GMT+0000 <@> DEBUG <@> [537838:qtp1158258131-537838] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:a5a413c1-24a0-aaaa-bed2-83b50f1a9915 <@> com.egain.platform.module.sso.util.SSOUtil <@> decodeBase64String() <@> Exiting decodeBase64String() method with retString: <samlp:Response ID="_2e893c54-7a6f-4bdf-bca8-8ae31a4a6074" Version="2.0" IssueInstant="2022-10-07T15:27:32.518Z" Destination="fqdn/system/SAML/SSO/POST.controller" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" InResponseTo="EG_a9ebbc9a-e457-4cac-a22e-bd3e92ad13eb" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"><Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">adfs/adfs/services/trust</Issuer><samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" /></samlp:Status><Assertion ID="_046b645f-7352-4c6b-af3c-3aec8817df54" IssueInstant="2022-10-07T15:27:32.518Z" Version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><Issuer>adfs/adfs/services/trust</Issuer><ds:Signature xmlns:ds="<fqdn/2000/09/xmldsig#"><ds:SignedInfo><ds:CanonicalizationMethod Algorithm="<fqdn/2001/10/xml-exc-c14n#" /><ds:SignatureMethod Algorithm="<fqdn/2001/04/xmldsig-more#rsa-sha256" /><ds:Reference URI="#_046b645f-7352-4c6b-af3c-3aec8817df54"><ds:Transforms><ds:Transform Algorithm="<fqdn/2000/09/xmldsig#enveloped-signature" /><ds:Transform Algorithm="<fqdn/2001/10/xml-exc-c14n#" /></ds:Transforms><ds:DigestMethod Algorithm="<fqdn/2001/04/xmlenc#sha256" /><ds:DigestValue>+++=</ds:DigestValue></ds:Reference></ds:SignedInfo><ds:SignatureValue>...
2022-10-07 15:27:34.521 GMT+0000 <@> DEBUG <@> [537838:qtp1158258131-537838] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:a5a413c1-24a0-aaaa-bed2-83b50f1a9915 <@> com.egain.platform.module.security.sso.handler.SAML2_0_Handler <@> validateReqWithAttributes() <@> Exiting getDecodedSAMLResponse() method with decodedString: <samlp:Response ID="_2e893c54-7a6f-4bdf-bca8-8ae31a4a6074" Version="2.0" IssueInstant="2022-10-07T15:27:32.518Z" Destination="fqdn/system/SAML/SSO/POST.controller" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" InResponseTo="EG_a9ebbc9a-e457-4cac-a22e-bd3e92ad13eb" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"><Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">adfs/adfs/services/trust</Issuer><samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" /></samlp:Status><Assertion ID="_046b645f-7352-4c6b-af3c-3aec8817df54" IssueInstant="2022-10-07T15:27:32.518Z" Version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><Issuer>adfs/adfs/services/trust</Issuer><ds:Signature xmlns:ds="<fqdn/2000/09/xmldsig#"><ds:SignedInfo><ds:CanonicalizationMethod Algorithm="<fqdn/2001/10/xml-exc-c14n#" /><ds:SignatureMethod Algorithm="<fqdn/2001/04/xmldsig-more#rsa-sha256" /><ds:Reference URI="#_046b645f-7352-4c6b-af3c-3aec8817df54"><ds:Transforms><ds:Transform Algorithm="<fqdn/2000/09/xmldsig#enveloped-signature" /><ds:Transform Algorithm="<fqdn/2001/10/xml-exc-c14n#" /></ds:Transforms><ds:DigestMethod Algorithm="<fqdn/2001/04/xmlenc#sha256" /><ds:DigestValue>+++=</ds:DigestValue></ds:Reference></ds:SignedInfo><ds:SignatureValue>...
2022-10-07 15:27:34.521 GMT+0000 <@> DEBUG <@> [537838:qtp1158258131-537838] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:a5a413c1-24a0-aaaa-bed2-83b50f1a9915 <@> com.egain.platform.module.security.sso.handler.SAML2_0_Handler <@> unmarshallAndValidateResponse() <@> Entering unmarshallAndValidateResponse() method with base64decodedResponse: <samlp:Response ID="_2e893c54-7a6f-4bdf-bca8-8ae31a4a6074" Version="2.0" IssueInstant="2022-10-07T15:27:32.518Z" Destination="fqdn/system/SAML/SSO/POST.controller" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" InResponseTo="EG_a9ebbc9a-e457-4cac-a22e-bd3e92ad13eb" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"><Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">adfs/adfs/services/trust</Issuer><samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" /></samlp:Status><Assertion ID="_046b645f-7352-4c6b-af3c-3aec8817df54" IssueInstant="2022-10-07T15:27:32.518Z" Version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><Issuer>adfs/adfs/services/trust</Issuer><ds:Signature xmlns:ds="<fqdn/2000/09/xmldsig#"><ds:SignedInfo><ds:CanonicalizationMethod Algorithm="<fqdn/2001/10/xml-exc-c14n#" /><ds:SignatureMethod Algorithm="<fqdn/2001/04/xmldsig-more#rsa-sha256" /><ds:Reference URI="#_046b645f-7352-4c6b-af3c-3aec8817df54"><ds:Transforms><ds:Transform Algorithm="<fqdn/2000/09/xmldsig#enveloped-signature" /><ds:Transform Algorithm="<fqdn/2001/10/xml-exc-c14n#" /></ds:Transforms><ds:DigestMethod Algorithm="<fqdn/2001/04/xmlenc#sha256" /><ds:DigestValue>+++=</ds:DigestValue></ds:Reference></ds:SignedInfo><ds:SignatureValue>...
2022-10-07 15:27:34.521 GMT+0000 <@> DEBUG <@> [537838:qtp1158258131-537838] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:a5a413c1-24a0-aaaa-bed2-83b50f1a9915 <@> com.egain.platform.module.security.sso.handler.SAML2_0_Handler <@> getRootElement() <@> Entering getRootElement() with responseSAMLString: <samlp:Response ID="_2e893c54-7a6f-4bdf-bca8-8ae31a4a6074" Version="2.0" IssueInstant="2022-10-07T15:27:32.518Z" Destination="fqdn/system/SAML/SSO/POST.controller" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" InResponseTo="EG_a9ebbc9a-e457-4cac-a22e-bd3e92ad13eb" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"><Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">adfs/adfs/services/trust</Issuer><samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" /></samlp:Status><Assertion ID="_046b645f-7352-4c6b-af3c-3aec8817df54" IssueInstant="2022-10-07T15:27:32.518Z" Version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><Issuer>adfs/adfs/services/trust</Issuer><ds:Signature xmlns:ds="<fqdn/2000/09/xmldsig#"><ds:SignedInfo><ds:CanonicalizationMethod Algorithm="<fqdn/2001/10/xml-exc-c14n#" /><ds:SignatureMethod Algorithm="<fqdn/2001/04/xmldsig-more#rsa-sha256" /><ds:Reference URI="#_046b645f-7352-4c6b-af3c-3aec8817df54"><ds:Transforms><ds:Transform Algorithm="<fqdn/2000/09/xmldsig#enveloped-signature" /><ds:Transform Algorithm="<fqdn/2001/10/xml-exc-c14n#" /></ds:Transforms><ds:DigestMethod Algorithm="<fqdn/2001/04/xmlenc#sha256" /><ds:DigestValue>+++=</ds:DigestValue></ds:Reference></ds:SignedInfo><ds:SignatureValue>...
2022-10-07 15:27:34.523 GMT+0000 <@> DEBUG <@> [537838:qtp1158258131-537838] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:a5a413c1-24a0-aaaa-bed2-83b50f1a9915 <@> com.egain.platform.module.sso.util.SSOUtil <@> loadcertificate() <@> Entering loadcertificate() method with publicCertificateString: ----BEGIN CERTIFICATE-----
.....
-----END CERTIFICATE----- <@>
2022-10-07 15:27:34.523 GMT+0000 <@> INFO <@> [537838:qtp1158258131-537838] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:a5a413c1-24a0-aaaa-bed2-83b50f1a9915 <@> com.egain.platform.module.sso.util.SSOUtil <@> loadcertificate() <@> cf: java.security.cert.CertificateFactory@10365e4c <@>

Error: Could not parse certificate: java.io.IOException: Incomplete data:
2022-10-07 15:27:34.523 GMT+0000 <@> ERROR <@> [537838:qtp1158258131-537838] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:a5a413c1-24a0-aaaa-bed2-83b50f1a9915 <@> com.egain.platform.module.sso.util.SSOUtil <@> loadcertificate() <@> Could not parse certificate: java.io.IOException: Incomplete data <@>
2022-10-07 15:27:34.524 GMT+0000 <@> DEBUG <@> [537838:qtp1158258131-537838] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:a5a413c1-24a0-aaaa-bed2-83b50f1a9915 <@> com.egain.platform.module.sso.util.SSOUtil <@> loadcertificate() <@> Exiting loadcertificate() method with xcert: null <@>
2022-10-07 15:27:34.525 GMT+0000 <@> DEBUG <@> [537838:qtp1158258131-537838] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:a5a413c1-24a0-aaaa-bed2-83b50f1a9915 <@> com.egain.platform.module.security.sso.handler.SAML2_0_Handler <@> validateSSOCertificate() <@> certificate: null <@>
2022-10-07 15:27:34.525 GMT+0000 <@> DEBUG <@> [537838:qtp1158258131-537838] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:a5a413c1-24a0-aaaa-bed2-83b50f1a9915 <@> com.egain.platform.module.security.sso.handler.SAML2_0_Handler <@> validateSSOCertificate() <@> Exiting validateSignatureAndCertificate() with retBoolean: false <@>

Signature validation failed:
2022-10-07 15:27:34.525 GMT+0000 <@> ERROR <@> [537838:qtp1158258131-537838] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:a5a413c1-24a0-aaaa-bed2-83b50f1a9915 <@> com.egain.platform.module.security.sso.handler.SAML2_0_Handler <@> unmarshallAndValidateResponse() <@> Signature validation failed. SAML Response: <samlp:Response ID="_2e893c54-7a6f-4bdf-bca8-8ae31a4a6074" Version="2.0" IssueInstant="2022-10-07T15:27:32.518Z" Destination="fqdn/system/SAML/SSO/POST.controller" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" InResponseTo="EG_a9ebbc9a-e457-4cac-a22e-bd3e92ad13eb" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"><Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">adfs/adfs/services/trust</Issuer><samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" /></samlp:Status><Assertion ID="_046b645f-7352-4c6b-af3c-3aec8817df54" IssueInstant="2022-10-07T15:27:32.518Z" Version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><Issuer>adfs/adfs/services/trust</Issuer><ds:Signature xmlns:ds="<fqdn/2000/09/xmldsig#"><ds:SignedInfo><ds:CanonicalizationMethod Algorithm="<fqdn/2001/10/xml-exc-c14n#" /><ds:SignatureMethod Algorithm="<fqdn/2001/04/xmldsig-more#rsa-sha256" /><ds:Reference URI="#_046b645f-7352-4c6b-af3c-3aec8817df54"><ds:Transforms><ds:Transform Algorithm="<fqdn/2000/09/xmldsig#enveloped-signature" /><ds:Transform Algorithm="<fqdn/2001/10/xml-exc-c14n#" /></ds:Transforms><ds:DigestMethod Algorithm="<fqdn/2001/04/xmlenc#sha256" /><ds:DigestValue>+++=</ds:DigestValue></ds:Reference></ds:SignedInfo><ds:SignatureValue>...
2022-10-07 15:27:34.525 GMT+0000 <@> INFO <@> [537838:qtp1158258131-537838] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:a5a413c1-24a0-aaaa-bed2-83b50f1a9915 <@> com.egain.platform.module.security.sso.admin.SSOAdministrator <@> validateRequestWithAttributes() <@> tokenState: NULL <@>
2022-10-07 15:27:34.525 GMT+0000 <@> ERROR <@> [537838:qtp1158258131-537838] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:a5a413c1-24a0-aaaa-bed2-83b50f1a9915 <@> com.egain.platform.module.security.sso.controller.SSOControllerServlet <@> redirectToApiErrorPage() <@> User SSO: SSOLoginException caught. L10N file path: pl/resourcetype/sso. L10N string: L10N_USER_SIGNATURE_INVALID <@>
2022-10-07 15:27:34.525 GMT+0000 <@> DEBUG <@> [537838:qtp1158258131-537838] <@> ProcessId:3272 <@> PID:1 <@> UID:12 <@> UserSessionId:a5a413c1-24a0-aaaa-bed2-83b50f1a9915 <@> com.egain.platform.client.util.i18n.L10NUtil <@> getLocalizedMessage(CallerContext, Locale, String, l10nKey, String[]) <@> In method getLocalizedMessage: pl/resourcetype/sso L10N_USER_SIGNATURE_INVALID null <@>

Resolution

• The error seen in the log snippet, 'Could not parse certificate: java.io.IOException: Incomplete data', indicates that the 'Identity Provider Certificate' content is not entered correctly 
• To resolve this: On the AS FS Management > AD FS > Service > Certificates > Token-Signing > Export this certificate > open in a text editor > copy all the contents > paste under 'Identity provider certificate' filed in the SSO configuration > Save.
• Refer the 'Identity Provider Certificate' configuration under the section 'Configuring Agent single sign-on - Identity Provider' (Step 15).

Troubleshooting Scenario 3

Error

• Error Code: 401-114
• Error Description: User Identity not found in SAML attribute.

Log Analysis

getSSODataFromSAMLToken:
2024-02-01 01:44:32.081 GMT+0000 <@> ERROR <@> [1220:qtp815320891-1220] <@> ProcessId:7716 <@> PID:1 <@> UID:12 <@> UserSessionId:  <@> ClientIP: <@> com.egain.platform.module.security.sso.handler.SAML2_0_Handler <@> getSSODataFromSAMLToken() <@> User identity not found in   SAML_ATTRIBUTE <@> 
2024-02-01 01:44:32.081 GMT+0000 <@> TRACE <@> [1220:qtp815320891-1220] <@> ProcessId:7716 <@> PID:1 <@> UID:12 <@> UserSessionId:  <@> ClientIP: <@> com.egain.platform.module.security.sso.controller.SSOControllerServlet <@> redirectToApiErrorPage() <@> Entering redirectToApiErrorPage() <@> 

L10N_USER_IDENTIFIER_NOT_FOUND_IN_ATTRIBUTE:
2024-02-01 01:44:32.081 GMT+0000 <@> ERROR <@> [1220:qtp815320891-1220] <@> ProcessId:7716 <@> PID:1 <@> UID:12 <@> UserSessionId:  <@> ClientIP: <@> com.egain.platform.module.security.sso.controller.SSOControllerServlet <@> redirectToApiErrorPage() <@> User SSO: SSOLoginException caught. L10N file path: pl/resourcetype/sso. L10N string: L10N_USER_IDENTIFIER_NOT_FOUND_IN_ATTRIBUTE. Dynamic strings: upn <@> 
com.egain.platform.module.security.sso.exception.SSOLoginException: null
 at com.egain.platform.module.security.sso.handler.SAML2_0_Handler.getSSODataFromSAMLToken(SAML2_0_Handler.java:762) ~[egpl_application_classes.jar:?]
 at com.egain.platform.module.security.sso.handler.SAML2_0_Handler.unmarshallAndValidateResponse(SAML2_0_Handler.java:604) ~[egpl_application_classes.jar:?]
 at com.egain.platform.module.security.sso.handler.SAML2_0_Handler.validateReqWithAttributes(SAML2_0_Handler.java:208) ~[egpl_application_classes.jar:?]
 at com.egain.platform.module.security.sso.handler.SAML2_0_Handler.validateReqWithAttributes(SAML2_0_Handler.java:163) ~[egpl_application_classes.jar:?]
 at com.egain.platform.module.security.sso.handler.OpenIDConnect_Handler.validateReqWithAttributes(OpenIDConnect_Handler.java:445) ~[egpl_application_classes.jar:?]
 at com.egain.platform.module.security.sso.admin.SSOAdministrator.validateRequestWithAttributes(SSOAdministrator.java:131) ~[egpl_application_classes.jar:?]
 at com.egain.platform.module.security.sso.controller.SSOControllerServlet.doPost(SSOControllerServlet.java:113) ~[egpl_application_classes.jar:?]
.
.
.
 at java.lang.Thread.run(Thread.java:830) [?:?]

errorCode=401-114&errorString=User Identity not found in SAML attribute: 'upn':
2024-02-01 01:44:32.083 GMT+0000 <@> DEBUG <@> [1220:qtp815320891-1220] <@> ProcessId:7716 <@> PID:1 <@> UID:12 <@> UserSessionId:  <@> ClientIP: <@> com.egain.platform.module.security.sso.controller.SSOControllerServlet <@> redirectToApiErrorPage() <@> WS API SSO errorURL => /system/web/view/platform/admin/security/sso/context/errorpage.html?errorCode=401-114&errorString=User Identity not found in SAML attribute: 'upn'.&errorKey=L10N_USER_IDENTIFIER_NOT_FOUND_IN_ATTRIBUTE&locale=en-US <@> 
2024-02-01 01:44:32.083 GMT+0000 <@> TRACE <@> [1220:qtp815320891-1220] <@> ProcessId:7716 <@> PID:1 <@> UID:12 <@> UserSessionId:  <@> ClientIP: <@> com.egain.platform.module.security.sso.controller.SSOControllerServlet <@> redirectToApiErrorPage() <@> Exiting redirectToApiErrorPage() <@>

Resolution

• This error indicates a configuration issue/mismatch in the 'User Identity Location' and the 'User Identity Attribute Name' fields.
• Check and correct the 'User Identity Location' and the 'User Identity Attribute Name' in the ECE Admin console, under Single Sign-On > Configurations > in the Select Configuration drop down, select Agent > SSO Configuration tab > Identify Provider (Step 15).

Related Information

These are the key documents you must review thoroughly before you start any ECE installation or integration. This is not a comprehensive list of ECE documents.

Note:

• Most ECE documents have two versions. Please ensure that you download and use the versions that are for PCCE. The document title has either for Packaged Contact Center Enterprise or (For PCCE) or (For UCCE and PCCE) after the version number.
• Ensure that you check the start page for Cisco Enterprise Chat and Email documentation for any updates prior to any install, upgrade, or integration.
• https://www.cisco.com/c/en/us/support/customer-collaboration/cisco-enterprise-chat-email/series.html

ECE Version 12.6(1)

• Enterprise Chat and Email Administrator’s Guide