Enabling SSO in DAI with Entra ID and SAML v2

This page describes the steps necessary to configure Single Sign-On (SSO) between DAI and Microsoft Entra ID (formerly "Azure AD") using the Security Assertion Markup Language (SAML) v2 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 OIDC.

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	- 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. Expose the Application in Entra ID using SAML

Now configure your application in Entra ID to expose it using the SAML v2 protocol as follows:

1. Select Single sign-on from the left navigation menu.

2. Select Change single sign-on mode > SAML.

3. Still in the Single sign-on section, select Basic SAML Configuration > Edit and provide the following information:

   Field Name	Value
   Identifier (Entity ID)	https://<dai_domain>/auth/realms/egglant/<idp_alias> where: <dai_domain> is the name of the domain where DAI (and Keycloak) are installed. <idp_alias> is the alias name assigned to the Entra ID identity provider configuration in DAI. You have not created this yet. So you need to remember what you choose here and use it when you configure DAI later in this process. This example shows the alias named ad.
   Reply URL (Assertion Consumer Service URL)	https://<dai_domain>/auth/realms/eggplant/broker/<idp_alias>/endpoint where: <dai_domain> and <idp_alias> are the same as defined for Entity ID above. - Because you only have one, you do not need to worry about the Default checkbox.
   Sign on URL	not needed
   Relay State	not needed
   Logout URL	not needed

Configure a SAML Certificate

note

By default Entra ID will create a SHA-256 certificate to Sign SAML Assertion when it creates the Enterprise Application so you should not have to make any changes.

Configure Claims

Follow the steps below to configure identity claims:

1. From the Single sign-on section, select Attributes & Claims and select Edit.

2. Select to Add new claim and provide the following information:

   Add new claim field	Value
   Name	nameidentifier
   Namespace	http://schemas.xmlsoap.org/ws/2005/05/identity/claims
   Name identifier format	Unspecified
   Source	Attribute
   Source Attribute	user.userprincipalname (Use the Source Attribute drop-down to select the source attributes. If you type them, AD treats them as quoted string literals.)
   Claim Conditions	No need to amend
   Advanced SAML claims options > Expose claim in JWT tokens	unchecked

3. Click Save.

4. Repeat the steps above to create more claims with the same Source and Namespace but with different Names and Source Attributes as per the table below:

Field Name	Source Attribute
emailaddress	user.mail
givenname	user.givenname
name	user.userprincipalname
surname	user.surname

3. 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",
           "WindowsAzureActiveDirectoryCustomSinglesSignOnApplication"
     ]

5. Click Save.

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

5. Configure How Authentication Works for this Application

Configure how authentication works for your DAI application.

1. From the left navigation, select Authentication.

2. You should see the Redirect URI already 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 domain name 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.

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:

  • A SAML Metadata XML payload (see below)

  • The Entity ID for our application

Export the SAML Metadata Document from Entra ID

1. Within Entra ID, navigate to the application under Enterprise Applications and select Single Sign-on from the left navigation. Under SAML Certificates, locate the setting for App Federation Metadata URL.

2. Copy that value and use this URL to download and save the XML metadata file. The URL typically has the following format:

   https://login.microsoftonline.com/{tenant_id}/federationmetadata/2007-06/federationmetadata.xml?appid={application_id}

3. Download and save this file.

   warning

   Do not be tempted to grab the metadata URL from the list of Endpoints in the App Registration. The metadata URL here doesn’t have the appid query parameter and may give you a metadata file that doesn’t work (contains the wrong certificates).

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

Replace the variable values enclosed in <...> in the script above with the values for your DAI installation as follows:

Variable	Description
<keycloak_admin_user>	The username of the 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.

warning

It is not secure to configure passwords 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> ^
--vars IDP_ROLE_SOURCE_CLAIM=http://schemas.microsoft.com/ws/2008/06/identity/claims/role ^
--vars IDP_PROTOCOL=saml ^
--vars IDP_PROVIDER_TYPE=saml ^
--vars IDP_ENTITY_ID=<entity_id>

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 SAML XML metadata file exported to file from Entra ID. We recommend using the absolute file path to the metadata file.
<entity_id>	The entity ID (also known as "the Relying Party Trust ID") from Entra ID.

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.