Configuring Single Sign-On for Agents

To configure SSO:

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

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

  3. From the Select Configuration dropdown, select Agent.

  4. On the General tab, set the following:

    • Name: This field is populated automatically and cannot be changed.

    • Description: This field is populated automatically and cannot be changed.

    • Enable Single Sign-On: Click the Toggle button_toggle_disabled button to enable SSO.

    • Allow local login for specific users: Select whether users should only be able to log in to the application through the SSO authentication methods, or if they can log in to the application locally as well. To enable local login, click the Toggle button_toggle_disabled button. The type of authentication required of each user can be controlled at the user level.See Creating Department Users for more details.

    • Single Sign On Type: Select OIDC or SAML 2.0.

    • Create or Update user account on login: This field is used for user auto-provisioning. If you are not configuring your system for auto-provisioning, do not enable the Toggle button_toggle_disabled button. To learn more about auto-provisioning users, see User Auto-Provisioning.

  5. Based on the Single Sign-On type that you select, the settings under the SSO Configuration tab are displayed. Male the necessary configurations for OIDC or SAML 2.0.  

  6. Click the Save button.

SSO Configuration settings for OIDC

On the SSO Configuration tab, provide the following details for your OIDC Provider:

  • Authorization Grant Type: This field is preconfigured to authorization_code and cannot be changed.

  • Authorization URI: Enter the URI of the /authorize endpoint provided by your Identity Provider (IdP).

  • Client Authentication Method: Choose one fo the following client authentication method supported by your IdP:

    • Use client_secret_basic when your environment supports setting HTTP Authorization headers. This method is generally preferred for its better security, as it transmits credentials in the Authorization header.

    • Use client_secret_post if header customization is restricted or unsupported in your environment. This method sends the credentials in the body of the POST request instead.

  • Client ID: Specify the Client ID assigned to your OIDC application in your IdP.

  • Client Secret: Enter the Client Secret associated with your OIDC application. If this secret has an expiration date, ensure it is updated in eGain before expiry to prevent service disruption.

  • Scope: Enter the scopes configured in your IdP. Required scopes include openid, email, and profile that are added by default. Modify this field as required by your External IdP configuration, separated by commas. 

  • Token URI: Provide the URI of the /token endpoint used to obtain access tokens from your IdP. 

  • User Info URI: Provide the URI of the /userinfo endpoint used to retrieve user profile information. This field is optional; provide this value only when required by your IdP.

  • User Name Attribute Name: Enter the name of the attribute in the ID token that uniquely identifies the user (e.g., sub, email, or preferred_username).

  • JWK Set URI: Provide the URI of the JSON Web Key (JWK) Set used to validate token signatures.

  • Logout URI: Enter the URI of the logout endpoint used to terminate the user session with the IdP. This field is optional.

  • After saving the configuration, the Redirect URL and Post logout URLs are generated and displayed. These URLs are used to finalize the OIDC client application configuration in the customer’s Identity Provider (IdP) by adding them as the Sign-in Redirect URI and Logout URI to enable successful federated login.

SSO Configuration Settings for SAML 2.0

On the SSO Configuration tab, the Service Provider can be allowed to initiate the authentication for SAML. 

  • Under the Identity Provider section, provide the following:

    • Entity ID: Entity ID or the Issuer

    • Identity provider certificate: The public key certificate. The certificate must start with “-----BEGIN CERTIFICATE-----” and end with “-----END CERTIFICATE-----”

    • User Identity location: This is to set the identity location in the certificate to the default SAML subject identifier. The value for this field is set as SAML Subject Identifier by default

    • Enable encrypted assertion: Click the Toggle button_toggle_disabled button to enable SAML encrypted assertion for console login.

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

      • Java keystore file: Provide the file path of your Java Keystore File. This file will be 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:  The method used by a Service Provider (SP) to initiate authentication and authorization requests with an Identity Provider (IdP) in the SAML protocol. From the dropdown, select either of the following options:  GET or POST.

    • Name ID Policy Format: This setting specifies the format of the user identifier issued by the Identity Provider in a SAML assertion to ensure consistent identification across systems. Select one of the available options: Unspecified, Email Address, or Persistent. You should update this field only according to the customer's IdP requirements to include NameIDPolicy format in the SAML request.

    • Datetime attribute format:  Click the Add button to select the custom attribute for which the date-time format must be specified. This setting captures the date-time format for all such custom attributes configured on the external IdP that are used in federated SSO claims during the authentication process.Use the following symbols to define a valid date-time format:

      • Date: d
      • Month: M
      • Year: y
      • Hours: H
      • Minutes: m
      • Seconds: s
      • Milliseconds: S

      For example, dd/MM/yyyy HH:mm:ss.SSS represents a date such as 31/03/2024 23:30:45.456.

  • If you wish to allow the application to initiate the authentication for SAML, provide the following under the Service Provider section:

    • Request signing certificate: Click the Add Add Buttonbutton and provide the following in the Request Signing Certificate window and click Done.

      • Java keystore file: Provide the file path of your Java Keystore File eg: C:\keystore\v15\SSO\keystore.jks. This file is in .jks format and contains the decryption key the system needs to access files secured by SAML. On distributed installations, this should be stored on the application server.

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

    • Signing Algorithm: The value is set to SHA-256 by default.

    • Identity Provider Login URL: The URL for SAML authentication.

    • Identity Provider Logout URL: The URL to which users will be redirected upon logging out.

    • Metadata URL: This URL is generated only after saving the configuration. Displays the Service Provider metadata URL, which contains the SAML configuration details required by the Identity Provider to establish the SSO integration. This URL can be shared with the Identity Provider to retrieve the metadata and configure the SAML connection.