Federation Configuration Setup for OIDC

Using the OpenID Connect (OIDC) protocol, users can sign in to the eGain application using their existing company credentials.

Prerequisites for Configuration

Before you begin configuring OIDC-based Single Sign-On (SSO) in eGain, ensure the following prerequisites are met:

Administrative access to your Identity Provider: You must have administrator-level access to your external Identity Provider to register the OIDC client application and configure necessary settings.
Administrative access to the eGain Administration Console: Access to the eGain Administration Console is required to configure SSO settings and manage user access.
At least one department user created: For end-to-end SSO testing, you must have at least one department user created in eGain using the eGain Administration Console.
Once the initial department user is set up, additional users can be added using one of the following methods:
1. Create users manually in the Administration Console. Ensure that the login name exactly matches the user’s identity as defined in your external IdP.
2. Configure eGain to automatically create or update users at login, using identity attributes passed in the JWT security token after a successful authentication.
3. Integrate with the eGain User APIs to programmatically manage users. This is typically done if your organization uses a centralized identity system.
4. Integrate user provisioning through your organization's Access Management (IAM) platform, if applicable.

Configuration Overview

The configuration involves a three-step process:

Step 1: Create the OIDC Client Application in your IdP: Create a new OIDC Client Application in your Identity Provider. Make sure to create a separate client application for each of your eGain instances, such as Production and Development environments.
Step 2: Configure eGain SSO and Generate Redirect URI: Next, use the eGain Administration console to enter the details of your new Identity Provider. When you enable OIDC Federation during this step, eGain will automatically generate the required redirect and post logout URLs using the configuration details from your client application set up in Step 1.
Step 3: Finalize IDP Configuration:
- Finally, copy the generated eGain redirect and post logout URLs and paste it into the Sign-in Redirect URI (or Redirect URI) and Logout URI fields of your OIDC Client Application settings within your Identity Provider.
- Save the changes to complete the configuration.

Step 1: External Identity Provider (IDP) Configuration

Configure your OIDC-based client application (e.g., in Okta or any other OIDC-compliant IDP) as follows:

Register your client application in the external IdP.
Gather Client App details to use while configuring SSO in the Administration Console

Client App Registration

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

Field	Value
Grant Type	Authorization Code
Token Endpoint Auth Method	client_secret_basic
Redirect URI (Sign in)	Below is the redirect URI format: https://<DEPLOYMENT_DOMAIN>/system/auth/<EGAIN_TENANT_ID>-U/login/oauth2/code/<UUID> sample: https://khub.egain.cloud/system/auth/TMPROD95766022-U/login/oauth2/code/d62408f8-9550-4d46-aecd-1fcb04b9b59b
Post-Logout Redirect URI (Sign-out)	https://<domain>/system/auth/<EGAIN_TENANT_ID>-U/idp/postlogout For example, https://eg8942ain.ezdev.net/system/auth/TMPROD18912909-U/idp/postlogout
Required scopes	openid, email, profile , <any other scope, mandatory for accessing their client app endpoints>

Supported claims:

In addition to the user name extracted from the ID token attribute based on input provided in the User Name Attribute Name(*) field in the eGain Administration Console, the following attributes are also supported.

The user name in the ID token is mandatory.

Claims in the external IDP-issued access token and ID token are copied to the corresponding access and ID tokens issued by eGain IDP. Only access token claims are used for provisioning.

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

The table below lists the OIDC claims valid for configuring Single Sign-On for agents. For more information on how to configure SSO for agent, see Configuring Single Sign-On for Agents.

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	*
managerId	ID of the user's reporting manager
middleName	User's middle name
peripheralName (only required for integrated user)	Name of user’s associated peripheral (For example, device, location).	*
screenName	User's screen/display name within the application	*
user.groups	Groups assigned to the user

The table below lists the OIDC claims valid for configuring Single Sign-On for customers. For more information on how to configure SSO for customers, see Configuring Customer Single Sign-On.

Supported claims in external IdP JWT Tokens	Description	*Mandatory () for user creation in Access token**
appleOpaqueId.ID	Apple Opaque ID of the contact. Must not exceed 255 characters.
custom.<name>	Custom attributes of the contact: "<name>" is the internal name of the custom attribute. The name must match one of the custom attributes configured in application. If the custom attribute is configured as an enumeration, the value must be one of the predefined values.
dateOfBirth	Must be a date in the past and in XML date format (yyyy-mm-dd).
department	The name of the department where the customer exists. This must be provided only if the customer departmentalization setting is enabled in the application.
email.address	Email address of the contact.	*
externalId	A unique external ID for the contact person. If customer departmentalization is enabled in the application, this must be unique in the department of the customer. If customer departmentalization is not enabled, this must be unique in the application. Must be at least 1 character, and must not exceed 255 characters.
facebook.ID	Facebook ID of the contact. Must not exceed 255 characters.
firstName	First name of the contact. Must not exceed 124 characters.	*
home.phone.countryCode	Country code of the home phone number of the contact. Must be a number not exceeding 9 digits.
home.phone.number	Home phone number of the contact. This accepts any string representation. It is the customer's responsibility to share the correct number. Must not exceed 25 characters.
instagram.ID	Instagram ID of the contact. Must not exceed 255 characters.
lastName	Contact's last name or surname.
mergeOnAttribute	Attribute on which existing customer records are merged. Supported values are: email.address home.phone.number mobile.phone.number office.phone.number externalId custom.<name>
middleName	Middle name of the contact. Must not exceed 124 characters
mobile.phone.countryCode	Country code of the mobile phone number of the contact. Must be a number not exceeding 9 digits.
mobile.phone.number	Mobile phone number of the contact. This accepts any string representation. It is the client's responsibility to send in the correct number. Must not exceed 25 characters.
office.phone.countryCode	Country code of the office phone number of the contact. Must be a number not exceeding 9 digits.
office.phone.number	Office phone number of the contact. This accepts any string representation. It is the client's responsibility to send in the correct number. Must not exceed 25 characters.
twitter.ID	Twitter ID of the contact. Must not exceed 255 characters.

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