Single Sign-On for SAML 2.0 Systems

Important things to note about SAML 2.0 Single Sign-On:

An identity provider (IdP) certificate is required for SAML 2.0 configurations. Consult your IT department about obtaining the IdP certificate.
Encrypted SAML assertion is supported. If you wish to enable encrypted SAML assertion, you will need a Java Keystore (JKS) file for the decryption certificate. A Java Keystore (JKS) file is necessary if the service provider is enabled to authenticate users in SAML 2.0, as well. Contact your IT department to obtain the Java Keystore file.
SAML is a time sensitive protocol and the IdP determines the time-based validity of a SAML assertion. If the identity provider and the service provider clocks are not synchronized, the assertion becomes invalid and stops the SAML SSO feature. For SAML SSO to operate, you must install the correct Network Time Protocol (NTP) setup and ensure the time for the IdP and SP applications is completely synchronized. Consult your IT department about synchronizing the IdP clock with the SP clock.
SAML 2.0 provides a well-defined, interoperable metadata format that can be used to expedite the trust process between the Service Provider (SP) and the Identity Provider (IdP). Metadata ensures a secure transaction between an identity provider and a service provider. To enable SAML, a Circle of Trust (COT) between the service provider and identity provider must be established. Consult your IT department about obtaining IdP and SP metadata. Note: SP metadata for customer portals, chat, agent portals, and the agent desktop should be provided separately. SAML metadata samples are also available for configuration. For details, see SAML 2.0 Metadata.

Configuring SAML 2.0 SSO with External Identity Providers

When configuring SAML 2.0 SSO with external Identity Providers (IdPs) such as ADFS or Okta, configuration is required on both the external IdP and the eGain application. The sequence of configuration may vary depending on whether the IdP supports metadata-based configuration and whether its endpoints are predefined.

Case 1: IdP URIs Are Predefined and Relying Party Creation Supports Metadata

Some IdPs, such as ADFS, provide predefined URLs for the Entity ID, login endpoint, and logout endpoint. In such cases, you can begin the SSO configuration in the eGain application first and then use the generated metadata to configure the relying party in the IdP.

Step 1: Obtain IdP Details

Obtain the following information from the external IdP administrator. The values below are sample values.

Mandatory Fields	Value	Sample Values
Entity ID	Unique identifier of the external IdP or Issuer	http://ussuhvin0032.egdemo.info/adfs/services/trust
Identity Provider Certificate	Public certificate used to verify assertion/response signature, which is obtained from customer IDP.
Identity Provider Login URL	URL where users are redirected for authentication on external IDP (SingleSignOnService URL)	https://ussuhvin0032.egdemo.info/adfs/ls/
Identity Provider Logout URL	URL where logout requests are sent to clear session on external IDP (SingleLogoutService URL)	https://ussuhvin0032.egdemo.info/adfs/ls/

Step 2: Configure SSO in eGain

Follow the steps described in Configuring Single Sign-On for Agents to complete the SSO configuration in the eGain application.

Step 3: Retrieve eGain Metadata

After completing the configuration in eGain, obtain the metadata URL from the eGain Admin Console. Use this metadata in the IdP to create the relying party.

You can provide either the metadata URL, or the metadata XML file during relying party creation in ADFS.

Step 4: Create the Relying Party in ADFS

Import the metadata when creating the relying party in ADFS. During the import process, the required configuration values are automatically populated. Review the configuration and proceed to the Claims (Claim Rules) configuration.

Step 5: Configure Claims

Configure the required claims supported by eGain.

Step 6: Test the SSO Login

Once configuration is complete, test the user SSO login.

Certificate Handling

In this scenario, the eGain-managed certificates are automatically retrieved through metadata and used in the IdP configuration. Users can also use their own certificates.

Case 2: IdP URIs Are Not Predefined and Metadata Import Is Not Supported

Some IdPs, such as Okta, do not support relying party creation using metadata. In such cases, configuration must be performed manually on both the IdP and eGain sides.

Step 1: Configure the External IdP

To ensure proper communication between eGain and your external Identity Provider (IdP), you must configure your SAML-based client application (e.g., in Okta or another SAML-compliant provider) with the specific settings outlined below. In your external IdP, create or update your SAML client application with the following required parameters and claims.

Field	Also Knowns As	Description	Value
Assertion Consumer Service (ACS) URL	ACS Endpoint, SSO URL	Endpoint where the IdP sends the SAML Response after successful authentication	https://<DOMAIN>/system/auth/<TenantID>-U/saml2/SSO/user-saml-provider Replace the placeholders with the appropriate customer domain and tenant ID. ACS endpoint should be configured with HTTP-POST binding on external IDP.
Entity ID	Service Provider (SP) Entity ID, Relying Party Identifier, Audience URI	Unique identifier representing the eGain application (SP). Must match Audience in assertion	https://auth.egain.cloud/<TenantID>-U/user-saml-provider Replace the placeholders with the appropriate tenant ID.
NameID Format	Name ID Policy Format	Format of the user identifier in the assertion.	Unspecified, Email and persistent, these 3 formats are supported by eGain.
Signed Response		Indicates whether the full SAML Response is digitally signed	Enabled
Signature / Hash Algorithm	Signing Algorithm or Digest	Algorithm used to sign SAML messages	SHA-256
Signed Request Validation	AuthnRequest Signature Validation	Determines whether IdP validates signed SAML requests	Enabled (Recommended)
Signature Certificate	Request Signing Certificate	Certificate used to validate signed requests (X509Certificate)	Required only if signature validation is enabled or if IDP has made it mandatory, will be part of metadata. Customers can either use their own or eGain preconfigured certificates for signature.
Assertion Encryption Certificate	Encryption Certificate	Certificate used by IdP to encrypt SAML assertions (X509Certificate)	Required only if encryption is enabled, will be part of metadata. Customers can either use their own or eGain preconfigured certificates for encryption.
Single Logout (SLO) URL	Logout Endpoint, SingleLogoutService URL	Endpoint where logout responses are sent	https://<DOMAIN>/system/auth/<TenantID>-U/logout/saml2/slo/user-saml-provider Replace the placeholders with the appropriate customer domain and tenant ID. SLO endpoint should be configured with HTTP-POST binding on external IDP.

Step 2: Configure Certificates

For the Signature Certificate and Assertion Encryption Certificate, you can choose one of the available options depending on customer requirements.

Step 3: Configure Claims

Configure the required claims supported by eGain.

Step 4: Assign Users or Groups

In some IdPs, such as Okta, users or groups must be explicitly assigned to the SAML application (relying party) to allow SSO login. Ensure the required users or groups are assigned.

Step 5: Configure SSO in eGain

Follow the steps described in Configuring Single Sign-On for Agents to complete the SSO configuration in the eGain application.

Step 6: Test the SSO Login

Once configuration is complete, test the user SSO login.

Certificate Management

In the SSO configuration, the request signing certificate and assertion decryption certificate are managed by eGain if they are not provided by the customer. Customers can upload their own request signing certificate and assertion decryption certificate if required. The certificates must be in JKS format to be uploaded in the SSO configuration.

Select the option that best suits the customer’s requirements. We recommend User SSO - SAML configurations | Option 2: Certificate provided by eGain.

Option 1: Certificate Provided by Customer

Customers can upload their own request signing certificate and/or assertion decryption certificate.

Upload JKS Certificate

In the Request Signing Certificate or Assertion Decryption Certificate field, click the button and provide the following details in the certificate window, then click Done.

Java keystore file

Provide the file path of the Java Keystore file, for example: C:\keystore\SSO\certificate.jks
This file is in .jks format and contains the decryption key required by the system to access files secured by SAML.

Alias name

The unique identifier for the decryption key.

Keystore password

The password required to access the Java Keystore file.

Key password

The password required to access the alias decryption key.

Option 2: Certificate Provided by eGain

If the customer wants to use the eGain preconfigured signing and encryption certificates in their external IdP configuration, follow the steps below after completing the eGain SSO configuration and obtaining the metadata URL.

Note: Customers can skip uploading certificates during the external IdP configuration and upload them later after completing the eGain SSO configuration, since the certificates can only be retrieved from the eGain metadata URL.

A. Signing Certificate

Obtain the metadata URL from the eGain Admin Console.
Open the metadata URL in a browser and save the metadata content as an .xml file.
Locate the tag <md:KeyDescriptor use="signing">.
Under this tag, find the certificate enclosed within <ds:X509Certificate>.
Copy the certificate value and add the following headers and footers:
-----BEGIN CERTIFICATE-----
MIIExTCCA62…
-----END CERTIFICATE-----
Save the file with the .cer extension.

B. Encryption Certificate

Obtain the metadata URL from the eGain Admin Console.
Open the metadata URL in a browser and save the metadata content as an .xml file.
Locate the tag <md:KeyDescriptor use="encryption">.
Under this tag, find the certificate enclosed within <ds:X509Certificate>.
Copy the certificate value and add the following headers and footers:
-----BEGIN CERTIFICATE-----
MIIEuzCCA6OgAwIBA…
-----END CERTIFICATE-----
Save the file with the .cer extension.

You can now upload this public certificate in the external IdP by selecting the .cer file during the upload process.

Supported Claims:

Please refer to the mandatory and optional attributes for configuring SSO:

Supported claims in external IdP JWT Tokens	Description	*Mandatory () for user creation in Access token**
applicationType	Type of application the user is accessing
custom.<custom attribute name> e.g. custom.priority	Any custom user attribute defined by the organization
department	Department the user belongs to	*
email.address	User's email address	*
firstName	User's first or given name	*
lastName	User's last name or surname	*
middleName	User's middle name
screenName	User's screen/display name within the application	*
user.groups	Groups assigned to the user

Attribute Limits for Auto-Provisioning

The following table lists the attribute requirements and character limits applicable during user auto-provisioning through SSO. It includes both mandatory and optional attributes for Create User and Modify User operations. These limits ensure consistent data validation when users are automatically created or updated based on identity information received from the external IdP.

Attribute Name

Create User

Modify User

department

Mandatory : Yes