Enabling SSO in DAI with Entra ID and OIDC

This page describes the steps necessary to configure Single Sign-On (SSO) between DAI and Microsoft Entra ID (formerly "Azure AD") using the OpenID Connect (OIDC) protocol. It describes how Entra ID and DAI's embedded identity and access management provider (Keycloak) can be configured to integrate with one another. You can see a summary of the steps involved in this process in the page menu on the right side of this page.

Intended Audience: This topic is intended for DAI Administrators considering an SSO integration.

For more information about the benefits of integrating SSO with DAI, see How Does Single Sign-On (SSO) Work with DAI?. For information about integrating with Entra ID and the SAML v2 protocol, see Enabling SSO in DAI with Entra ID and SAML v2.

warning

This page provides specific instructions for configuring Keycloak and an example of how Entra ID might be configured. Every organization's identity management configuration is different and mis-configuration can have significant consequences, so your final designs and roll-out plans must be to your own specifications. If your Entra ID configuration is incompatible with the example provided here, please contact our Customer Support to see how we can help.

Prerequisites

To integrate DAI with Entra ID, your environment must meet the following prerequisites for Entra ID, DAI, and Networking.

Component	Requirement
Entra ID	Components: * Your organization must have a Microsoft Azure Account that you can use to configure Microsoft Entra ID. Users and Groups in Entra ID: - The users that need to access DAI must already exist in Entra ID. - You can optionally create groups in Entra ID to represent the DAI Administrator, User, and Viewer roles. Or, you can map users directly to Entra ID application roles when you create your application as described in 3. Create Application Roles below.
DAI	- If you have an existing DAI installation with local users in Keycloak, you can still enable SSO. Keycloak can join and convert these local accounts into SSO-integrated user accounts on the users' first SSO login. Linking your accounts this way is beneficial because your users will not lose access to any of their models. If your local usernames do not align to the usernames in Entra ID, you can change them by configuring Keycloak to temporarily allow this. See Editing Usernames for SSO for instructions. If you are using Eggplant Cloud, please contact our Customer Support for assistance. - You need at least one user account (preferably a DAI Administrator account) in Entra ID that you can use to verify your SSO integration. Successfully logging into DAI with this user verifies your SSO integration succeeded. If your DAI installation is on-premises ("on-prem"), rather than hosted in Eggplant Cloud, you need to verify the following: - If you are configuring an existing system, please back up your DAI system in the same way you would if you were upgrading DAI to a newer version. See Install or Upgrade Eggplant DAI on Windows for information about backing up DAI. This helps to ensure that users do not lose access to their data if something unexpected occurs during the integration. - DAI 7.1 or above must be installed. Enabling SSO is a separate process that can be performed after DAI is installed. - DAI must be set up to use Transport Layer Security (TLS). See Run an Advanced Install for information about setting up DAI to use TLS. Active Directory will not integrate with a DAI installation that uses plain HTTP.
Network	- If you are not using Eggplant Cloud, you need to verify that Keycloak can make HTTPS calls to Entra ID on the ports that Entra ID is configured to use (typically 443). - End-user’s workstations must have access to Entra ID login screens and SAML endpoints. * Entra ID must be able to make HTTPS calls to Keycloak so that when users log out of one system, they are logged out of any others.

Setting up an Application Integration in Entra ID

The following steps summarize the process for setting up an application integration for DAI in Entra ID.

1. Create an Application in Entra ID

The following steps describe how to create an application in Entra ID. For more information about creating an application in Entra ID, see Quickstart: Register an app in the Microsoft identity platform - Microsoft identity platform.

1. In Entra ID, select Enterprise Applications and then click Create your own application from the top menu.

2. Fill in the information about your application (your DAI instance) as follows:

   Field Name	Value
   What is the name of your app?	An arbitrary name you want to assign to this Enterprise Application. These examples use the name Eggplant Test for the application. (See the note below).
   What are you looking to do with your application?	Select the option: Integrate any other application you don't find in the gallery (non-gallery).

   note

   If you have a complex setup with multiple instances of Eggplant Test, you need to be able to distinguish the instances. For example, name one of your instances Eggplant Test (production) to distinguish it from the other instances.

3. Click Create. A details page for this new application opens.

2. Configure the App Registration

1. Navigate back to the Entra ID landing page and select App Registrations from the left navigation menu.

2. Select All applications and search for the application you just created for DAI (for example, Eggplant Test).

3. When you find your application, click it to bring up the details.

4. Amend the manifest by selecting Manifest from the left navigation menu and ensuring the following attributes are added or updated in the JSON:

    "accessTokenAcceptedVersion": 2
   
        "tags": [
           "WindowsAzureActiveDirectoryIntegratedApp"
     ]

5. Click Save.

3. Create Application Roles

The steps below describe how to create the DAI Viewer, User, and Administrator application roles in Entra ID. For more information about creating Application Roles in Entra ID, see Add app roles and get them from a token - Microsoft identity platform.

1. Select App Roles from the left navigation and then select Create app role.

2. Fill in information about the DAI Viewer role as follows:

   Field Name	Value
   Display name	Eggplant Test - DAI Viewer (see note below)
   Allowed member types	User/Groups
   Value	dai_viewer
   Description	DAI Viewers can perform read only operations in DAI.
   Do you want to enable this app role?	Yes (checked)

   note

   The recommended format for role names is to fully-qualify the role name with the application name as the prefix as shown above (Eggplant Test - DAI Viewer).

3. Click Apply.

4. Repeat the process to create the DAI User role by selecting App Roles and then Create app role and providing the following information:

   Field Name	Value
   Display name	Eggplant Test - DAI User.
   Allowed member types	User/Groups
   Value	dai_user
   Description	DAI Users can perform all but administrative functions in DAI.
   Do you want to enable this app role?	Yes (checked)

5. Click Apply.

6. Repeat the process for the DAI Administrator role by selecting App Roles and then Create app role and providing the following information:

   Field Name	Value
   Display name	Eggplant Test - DAI Administrator.
   Allowed member types	User/Groups
   Value	dai_admin
   Description	DAI Administrators have full access to DAI including administrative functions.
   Do you want to enable this app role?	Yes (checked)

7. Click Apply.

4. Expose the Application in Entra ID using OIDC

To expose the application in Entra ID with the OpenID Connect (OIDC) protocol:

1. Select Expose an API from the left navigation menu and select Edit for the Application ID.

2. Fill out the form as follows:

   Field Name	Value
   Application ID URI	Any unique URI, for example: api://eggplant-test (see note below)

3. Click Save.

   note

   We recommend using the api:// scheme. It is possible to use https://, but this can cause issues if the application’s redirect URIs and the application ID are not on the same domain.

4. Still in the Expose an API section, select Add a Scope and define a scope as follows:

   Field Name	Value
   Scope name	eggplant-test
   Who can consent?	You can select either option depending on whether you want to allow users to consent to accessing this application or not.
   Admin consent display name	Allow access to Eggplant Test
   Admin consent description	Allow the signed-in user to access to the Eggplant Test application
   User consent display name	Access Eggplant Test
   User consent description	Allow access to the Eggplant Test application
   State	Enabled

5. Click Add Scope.

Configure Claims

Follow the steps below to configure claims:

1. Select Token Configuration from the left navigation menu and select Add optional claim.

2. Select the token type ID.

3. Select upn and click Add.

5. Create a Client Secret

1. Select Certificates and Secrets from the left navigation menu and then select New client secret.

   Field Name	Value
   Description	Enter any description you like for the secret.
   Expires	Give the secret an expiry based on your organization’s policies. Be sure to generate a new secret before this one expires so that DAI integration continues to work.

2. Click Add.

warning

Be sure to make a note of the new secret’s value; this is the one and only time it will be visible.

6. Configure How Authentication Works for this Application

1. From the left navigation, select Authentication.

2. You should see the Redirect URI already pre-populated, but you still need to set the following:

   Field Name	Value
   Front-channel logout URL	Set this to https://<dai_domain>/logout where <dai_domain> is the name of the domain where DAI is installed.
   Implicit grant and hybrid flows - Access tokens	unchecked
   Implicit grant and hybrid flows - ID tokens	unchecked
   Supported account types	Select the one that’s most appropriate to your environment.
   Allow public client flows	No
   App instance property lock	Configure as per your organization’s policy requirements

3. Click Save.

7. Configure Permissions

1. Select API Permissions from the left navigation menu.

2. Click Add a permission.

3. Select Microsoft Graph as the API you are requesting permissions for.

4. Select Delegated permissions.

5. Under Openid Permissions select: email, offline_access, openid, and profile.

6. Select Add permissions.

note

These permissions will require consent. If you are logged in as an Administrator and are happy to consent on behalf of all users in the default directory then you can select Grant admin consent for Default Directory, if not then your users will need to consent to your application Eggplant Test (DAI) being granted these permissions on first use.

Setting up an Application Integration in Keycloak

Now that you configured your DAI instance (or instances) as an application in Entra, you need to set up the application integration in Keycloak (DAI's embedded identity and access management provider).

1. Input Data

To configure Keycloak you will require the following:

• The Keycloak URL - this needs to be in the format https://<host>:<port>/auth/ (note the trailing slash), where the host and port are the DAI server hostname and port defined during DAI installation.

• The System Administrator username and password (also known as the Keycloak admin username and password) defined during DAI installation.

• The following settings that we generated when configuring Entra ID are also required:

  • client ID (for example Eggplant Test)

  • client secret

  • an OIDC Metadata JSON payload (see below)

note

The terminology can be confusing here. When you generate a client secret, you might be tempted to take the ID for that secret as the Client ID. But we only need the secret value, the client ID (also referred to as the "Application ID") is the ID of the application and not the secret ID.

2. Export the OIDC Metadata Document from Entra ID

You can download the metadata from a link as defined here OpenID Connect (OIDC) on the Microsoft identity platform - Microsoft identity platform. You will need to save this to file.

3. Configuring Keycloak

note

If you are using Eggplant Cloud, please contact our Customer Support for assistance as we will need to perform the following steps on your behalf.

To enable SSO on Keycloak, we run a migration procedure named identity_provider, which enables (or disables) SSO integration on a Keycloak realm.

This procedure does the following:

• Creates and configures an Identity Provider in Keycloak based on the manifest file that you provide.
• Sets that Identity Provider as the default for login flows, which means users are always directed to that provider.
• Configures the Themes for the Realm to use eggplant_readonly instead of eggplant, which removes features such as password management that are now provided by your identity provider.

Step 1 - Set up environment variables

set KC_ADMIN_USER=<keycloak_admin_user>
set KC_ADMIN_PASSWORD=<keycloak_admin_pwd>
set KEYCLOAK_URL=https://<dai_address>/auth/
set USE_LEGACY_INSTALLER=true
set IDP_CLIENT_ID=<idp_client_id>
set IDP_CLIENT_SECRET=<idp_client_secret>

Replace the values enclosed in <...> in the script above with the values for your identity provider as follows:

Variable	Description
<keycloak_admin_user>	The username of the Keycloak system administrator you configured when you installed DAI. This is also known as the Keycloak username.
<keycloak_admin_pwd>	The password of the system administrator you configured when you installed DAI.
<dai_address>	The hostname : port of the DAI server, for example, example.com:8080.
<idp_client_id>	The ID that you created for the DAI application when you configured it in Entra ID.
<idp_client_secret>	The secret that you created for the DAI application when you configured it in Entra ID.

warning

It is not secure to configure passwords and secrets on the command line in this way. We recommend you initialize sensitive environment variables using your organization’s preferred secrets manager instead.

Step 2 - Running the Script

The following instructions assume you installed DAI into the default location (C:\Program Files\Digital Automation Intelligence). If you installed DAI in a different location, please replace the default path in the script below with the location of your DAI installation.

The script below is written for the Windows command shell (cmd.exe). To run it from Powershell, you need to replace the caret (^) characters with backtick (`) characters.

"C:\Program Files\Digital Automation Intelligence\python\tools\python.exe" ^
-m eggplant.iam.realm_mgmt ^
--init-file "C:\ProgramData\Eggplant\Digital Automation Intelligence\logs\keycloak\.keycloak_migration_config" ^
run ^
--procedure identity_provider ^
--realm <realm> ^
--vars IDP_ALIAS=<idp_alias> ^
--vars IDP_DISPLAY_NAME=<idp_display_name> ^
--vars IDP_METADATA_FILE=<idp_metadata_file>

Replace the values enclosed in <...> in the script above with the values for your identity provider as follows:

Term	Value
<realm>	Typically eggplant
<idp_alias>	The alias name for this provider. This is the alias that was used to configure Entra ID earlier in the process.
<idp_display_name>	The friendly name for this Entra ID integration for display in the Keycloak admin console.
<idp_metadata_file>	The OIDC JSON metadata file exported to file from Entra ID. We recommend using the absolute file path to the metadata file.

The procedure logs messages in JSON format.

• If the procedure fails, you will see an ERROR, typically with one or more stack traces.
• If it succeeds, the last log entries will indicate that the procedure completed successfully.

If you encounter any errors, please review the message and any resulting stack traces. If you have any questions, please contact our Customer Support.

At this point, your DAI SSO integration should be complete. See Verifying SSO in DAI for some scenarios you can use to verify your integration is working properly.

If you want to disable SSO in your DAI installation, see Removing SSO Authentication from DAI.