Creating Identity Providers

Since customer single sign-on can be utilized in multiple ways on a variety of different web domains, all types of customers with different identity providers may be trying to access those resources. When configuring your system for customer single sign-on, you have the option of configuring the system for multiple identity providers to accommodate for this.

For example, a single portal can provide entry into a chat through different areas of the portal. These can be owned by different vendors, such as a virtual assistance provided by a different vendor. Thus, the application must allow customers to login to chat SSO through multiple identity providers. For more information, see Creating identity providers for Legacy Portals

eGain's latest V3 APIs now support Federated Customer Tokens for SSO, enabling seamless customer sign-ins using third-party IdPs. Users can now create providers for non-legacy portals (using the V3 templates) by simply disabling the Legacy Portal toggle button. For more information, see Creating Identity Providers for Non-legacy Portals.

On the Providers page, you can view the following details:

  • Name: Name of the provider.
  • Description: The description for the provider.
  • Legacy Portal: It denotes whether the provider is created for a legacy or non-legacy portal. If the value is Enabled, then the provider is created for a legacy portal and if it is Disabled, then it is created for a non-legacy portal. 
  • Actions: You can click the Set as Default option to set the provider as default. Note that you can select one default provider each for legacy and non-legacy portal

SSO Providers

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

Before configuring customer single sign-on, identity providers must be created and configured in the application. All the identity providers added must use SAML 2.0.

  • 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 eGain Support to obtain the Java Keystore file.

  • 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, agent portals, chat and the Advisor Desktop should be provided separately.

  • 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.

  • To enable Single Logout (SLO) capabilities, the Identity Provider, such as ADFS, must have the necessary endpoints configured for the relying party trusts. When editing the endpoint for an IdP like ADFS, provide the logout post request URLs for the Trusted URL and Response URL. Consult your IT department and system administrator for more information about configuring the IdP.

Creating Identity Providers for Legacy Portals

To create identity providers for legacy portals:

  1. From the Partition and Departments dropdown menu, go to the partition space.

  2. From the Navigation menu, browse to Security > Single Sign-On > Providers.

  3. On the List page, click the New New Button button.

    You can create a maximum of 25 identity providers in a partition.

  4. In the Properties pane, under the General tab, provide the following:

    • Name: The name of the identity provider

    • Description: A description of the identity provider

    • ID: This field is automatically updated and cannot be changed.

    • Default: Click the Toggle button_toggle_disabled button to make this the default identity provider for customer single sign-on configurations.

    • Legacy Portal: Click the Toggle button_toggle_disabled button to enable this option to create a provider for legacy portals. 

      This option is non-editable once the provider is saved.

    • Start Page (Absolute URL): Provide the URL for the page on which web-based customers should land when successfully logging in with single sign-on.

    • RelayState URL Whitelisting: A RelayState URL is an absolute URL of the web page where the user is redirected to after successfully logging in through SSO. RelayState URLs can serve the same purpose as the Start Page URL, however, RelayState URLs take precedence when configured. Use this optional field to whitelist any RelayState URLs used by the service provider (the eGain application). Select one of the following options from the pop-up window:

        • Allow all RelayState URLs: Whitelists all RelayState URLs of the service provider.

        • Allow RelayState(s) that start with the following URL(s): Select this option, click the Add URL button, provide the URL domain names in the field below the option and press Done.

    SSO Identity Providers General Tab

  5. On the SSO Configuration tab, the service provider can be allowed to initiate the authentication for SAML in addition to identity provider. For service provider initiated authentication, ensure that the External URL of Application setting is correctly configured. For more information, see General Partition Settings.

    • Under the Identity Provider section, provide the following:

      • SAML Version: This is set to SAML 2.0 and cannot be changed.

      • Entity ID: Entity ID or the issuer.

      • Identity provider certificate: Click the Add Add Button button. In the window that appears, provide the public key certificate. The certificate must start with “-----BEGIN CERTIFICATE-----” and end with “-----END CERTIFICATE-----”

      • Enable encrypted assertion: Click the Toggle button_toggle_disabled button to enable assertion encryption or disable encryption.

      • Assertion decryption certificate: If Enable Encrypted Assertion is enabled, click the Add Add Button button and provide the following in the Assertion Decryption Certificate window and click Done:

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

        • 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.

      • Clock Skew (in seconds): Provide the skew time in seconds which is used to validate the SAMLResponse assertion. The value must be between 0 and 60.

    Customer SSO Identity Provider Config

    • Under the Service Provider option, provide the following:

      • Enable identity provider initiated logout service: Click the Toggle button_toggle_disabled button to allow the application to accept logout requests from the IdP for one or more sessions of a customer. With this setting enabled, when the customer logs out of the IdP, the IdP notifies the application, which then terminates the user’s session in the application. Only requested user sessions are logged out.

      • Enable service provider initiated logout service: Click the Toggle button_toggle_disabled button to allow the IdP to accept logout requests from the application. With this setting enabled, when the user logs out of a channel in the application, a logout request is sent from the application to the IdP. Upon processing this logout request and also logging this user out, the IdP sends a logout response to the application, which then redirects the user to a logout page. Note: In default portal and secure message center templates, the logout request is sent to the default provider configured in the application. If a different provider is necessary, the templates should be reconfigured to use the new provider.

      • Identity provider logout URL: The IdP endpoint URL where the application submits its logout requests and logout responses. This must be provided if the Enable identity provider initiated logout service field or Enable service provider initiate logout service field is set to Yes.

      • Request signing certificate: Click the Add Add Button button and provide the following information in the next window and click Done.

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

        • 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.

      • Enable service provider initiated authentication: Click the Toggle button_toggle_disabled button to enable this setting. Setting this field to Yes enables the Identity provider login URL field and the Entity ID field.

      • Identity provider login URL: The URL for SAML authentication.

      • Entity ID: Provide the entity ID of the service provider.

      • Signing Algorithm: Signing Algorithm specifies the hash algorithm used to sign SAML requests or responses. SHA-256 is recommended for stronger security and broader support across modern systems. SHA-1 is available for compatibility with systems that require it. From the dropdown select SHA-1 or SHA-256 as per your security requirements. 

        For successful authentication, ensure that the signing algorithm selected in the provider matches the one configured in the IdP; mismatches may prevent authentication but do not block chat. For example, authentication succeeds when both are set to SHA-1 or SHA-256, but fails when the provider uses SHA-1 and the IdP uses SHA-256. In some cases, such as the provider set to SHA-256 and the IdP set to SHA-1, authentication may still succeed depending on the IdP’s behavior. 

         

      SP

  6. Click the Save button.

Creating Identity Providers for Non-legacy Portals

Similar to legacy providers, non-legacy providers must be added under Customer SSO > Providers as available providers. Once added, a non-legacy provider can be designated as the default. However, only one non-legacy provider can be set as default at any given time.

Please note that federation changes involving non-legacy providers may take 10–30 minutes to fully propagate.

To create identity providers for non-legacy portals:

  1. From the Partition and Departments dropdown menu, go to the partition space.

  2. From the Navigation menu, browse to Security > Single Sign-On > Providers.

  3. On the List page, click the New New Button button.

    You can create a maximum of 5 identity providers in a partition.

  4. In the Properties pane, under the General tab, provide the following:

    • Name: The name of the identity provider

    • Description: A description of the identity provider

    • ID: This field is automatically updated and cannot be changed.

    • Default: Click the Toggle button_toggle_disabled button to make this the default identity provider for customer single sign-on configurations.

    • Legacy Portal: Click the Toggle button_toggle_disabled button to disable this option to create a provider for non-legacy portals. 

      This option is non-editable once the provider is saved.

    SSO Identity Providers General Tab

  5. On the SSO Configuration tab, the service provider can be allowed to initiate the authentication for SAML in addition to identity provider. For service provider initiated authentication, ensure that the External URL of Application setting is correctly configured. For more information, see General Partition Settings.

    • Under the Identity Provider section, provide the following:

      • SAML Version: This is set to SAML 2.0 and cannot be changed.

      • Entity ID: Entity ID or the issuer.

      • Identity provider certificate: Click the Add Add Button button. In the window that appears, provide the public key certificate. The certificate must start with “-----BEGIN CERTIFICATE-----” and end with “-----END CERTIFICATE-----”

      • Enable encrypted assertion: Click the Toggle button_toggle_disabled button to enable assertion encryption or disable encryption.

      • Assertion decryption certificate: If Enable Encrypted Assertion is enabled, click the Add Add Button button and provide the following in the Assertion Decryption Certificate window and click Done:

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

        • 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.

      • SAML Request Method: SAML Request Method specifies how authentication requests are sent to the identity provider. From the dropdown, select either POST or GET depending on the size and sensitivity of the request, and compatibility with the identity provider.

    Customer SSO Identity Provider Config

    • Under the Service Provider option, provide the following:

      • Enable identity provider initiated logout service: This setting allows the application to accept logout requests from the IdP for one or more sessions of a customer. With this setting enabled, when the customer logs out of the IdP, the IdP notifies the application, which then terminates the user’s session in the application. Only requested user sessions are logged out.

        This setting is enabled by default and cannot be disabled.

      • Enable service provider initiated logout service: Click the Toggle button_toggle_disabled button to allow the IdP to accept logout requests from the application. With this setting enabled, when the user logs out of a channel in the application, a logout request is sent from the application to the IdP. Upon processing this logout request and also logging this user out, the IdP sends a logout response to the application, which then redirects the user to a logout page. Note: In default portal and secure message center templates, the logout request is sent to the default provider configured in the application. If a different provider is necessary, the templates should be reconfigured to use the new provider.

      • Identity provider logout URL: The IdP endpoint URL where the application submits its logout requests and logout responses. This must be provided if the Enable identity provider initiated logout service field or Enable service provider initiate logout service field is set to Yes.

      • Request signing certificate: Click the Add Add Button button and provide the following information in the next window and click Done.

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

        • 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.

      • Enable service provider initiated authentication: This setting allows users to access the application directly without first logging in through the identity provider. 

        This setting is enabled by default and cannot be disabled.

      • Identity provider login URL: The URL for SAML authentication.

      • Signing Algorithm: Signing Algorithm specifies the hash algorithm used to sign SAML requests or responses. SHA-256 is recommended for stronger security and broader support across modern systems. SHA-1 is available for compatibility with systems that require it. From the dropdown select SHA-1 or SHA-256 as per your security requirements. 

  6. Click the Save button.