API-Based Integration with Entra ID

This feature is currently available only to customers participating in a private preview. If you'd like to participate to be among the first to try this feature, ask our support or account team for details.

This documentation provides a detailed guide for integrating Entra ID with the Delinea Platform. The integration enables the Delinea Platform to use Microsoft APIs directly to access your Entra ID users and groups.

Instead of using Entra ID as a Registered App (native integration) as described in this topic, you can use an Entra ID federation configuration. But you cannot use both features simultaneously with the same domains. If your Delinea Platform has an existing Entra ID federation configuration, adding a new native Entra ID-registered app with the same domains will not succeed.

The integration supports the following:

  • Log-in and authentication using Entra ID credentials.

  • Browsing and searching for Entra ID users and security groups. Distribution lists (groups) are not supported.

  • Direct use of Entra ID groups on the platform without mapping them to platform groups.

  • Pre-assignment of Entra ID users to groups, roles, identity policies, and sharing secrets.

  • Inviting/adding Entra ID users directly to the platform.

This topic walks you through the following steps to set up Entra ID on the Delinea Platform:

  1. Registering an App in Azure:

    1. Generating a Client Secret: Create a client secret, copy its value, and note the expiration date.

    2. Configuring Token Claims: Add the required claims for the Platform.

    3. Setting API Permissions: Assign the necessary Microsoft Graph permissions and grant admin consent.

  2. Registering an App on the Delinea Platform: Enter the app credentials, permissions and domains.

  3. Testing Integration: Verify the integration by logging into the Platform with an Entra ID user.

The following procedures require copying and pasting information between Azure Portal and the Delinea Platform. We recommend opening both applications before you begin and keeping both open until you are finished.

Prerequisites

  • On the Delinea Platform, you must be a Platform Admin.

  • In Azure, you must be able to create an app registration and manage API permissions. Roles that satisfy these requirements are:

    • Global Administrator

    • Privileged Role Administrator

Create an Azure Application Registration

  1. Go to the Azure portal and log in.

  2. Select (or search for) App registrations.

  3. Click New registration.

  4. In the Name field, enter a name for your application registration. (Under Supported account types, only Single tenant is supported).

  5. Click Register. The application registration's overview page opens.

  6. From the left navigation menu, under Manage, click Certificate & secrets.

  7. Click New client secret to create a secret for authenticating to this Entra ID tenant with this application registration.

  8. (Optional): Complete the Description field for the new client secret.

  9. Update the Expires field to set the credentials expiration date.

  10. Click Add.

  11. Copy and save the Client secret's Value and its Expiration date because you will need them later when configuring the Delinea Platform. If you leave this page without saving the information, you may lose access the client secret Value and you will need to generate a new secret.

  12. From the left navigation menu, click Token configuration.

  13. Click Add optional claim.

  14. In the Add optional claim dialog, select ID under Token type.

  15. Select the following claims:

    • email

    • upn

  16. Click Add.

  17. In the dialog box that opens, select Turn on the Microsoft Graph email, profile permission (required for claims to appear in token).

  18. Click Add. This will add the optional claims to the app registration token.

  19. From the left navigation menu, click API Permissions. API Permissions include all permissions required for the platform.

  20. These three permissions will be on the Configured permissions list:

    • email

    • profile

    • User.Read

  21. Click Add a permission.

  22. Click Microsoft Graph.

  23. Click Application permissions and select the following:

    • AuditLog.Read.All

    • Group.Read.All

    • GroupMember.Read.All

    • Member.Read.Hidden

    • User.Read.All

  24. Click Add permissions.

  25. Click Grant admin consent for <azure directory name> for the API permissions you just added.

  26. In the Grant admin consent confirmation dialog, click Yes.

You are now ready to create a registered app on the Delinea Platform in the next section.

Create a Registered App on the Delinea Platform

  1. On the Delinea Platform, navigate to Settings > Registered apps.

  2. Click Add. The Add registered app page opens.

  3. Complete the following fields:

Delinea Platform field name Description Location in Azure App
Name A unique identifier for the registered app in the Delinea Platform. User-defined; choose a descriptive name when configuring in Delinea Platform.
Description Optional field to add details or context about the registered app. User-defined; optional entry in Delinea Platform.
Directory (tenant) ID The unique identifier for your Azure AD tenant. Found on the Azure App Registration → Overview page under "Directory (tenant) ID".
Application (client) ID The unique identifier for the Azure app being registered. Found on the Azure App Registration → Overview page under "Application (client) ID".
Client Secret Value The value of the client secret generated for the app, used for authentication. Generated in Azure App Registration → Certificates & Secrets. Copy the value immediately when creating the client secret.
Credential Expiration Date The expiration date of the client secret used for authentication. Found in Azure App Registration → Certificates & Secrets under "Expires". Match this value in Delinea Platform.

4. Select all of the following settings:

Delinea Platform field name Description
State Indicates whether the integration is active. Ensure this is set to Enabled to allow seamless operation
Entra ID - Read Grants the platform the ability to query Entra ID users and groups. This permission is Azure tenant-wide and can only be granted once per platform tenant.
Log-in to Entra ID Allows the creation of a Federation Provider within the Delinea Platform. This enables users to log in to the Delinea Platform using their Entra ID credentials. If needed, you can create multiple registered apps with Log-in permissions, each associated with a unique domain. When this option is selected, specifying the domains becomes mandatory.
Provision Directory Services This setting is required when creating the registered app to ensure that the directory service and federation provider settings are created. Note: This setting will be deprecated in future releases.

5. Domain Names: Add at least one domain, including the primary domain for your Microsoft Entra organization and any custom domains your users will use to log in.

6. Click Save.

Once the registered app is saved, the platform generates an OIDC federation configuration that can be viewed under Settings > Federation Providers, which gives Directory Services access to the Entra ID directory. To enable user login with Entra ID credentials, add the Platform Callback URL to the Azure app registration as described in the next section.

Update the Azure App Registration with the Platform Callback URL

Add the Platform Callback URL from the generated Federation configuration to the Azure app registration. The URL will be generated after you save the registered app.

  1. On the Delinea Platform, navigate to Settings > Registered apps.

  2. Select the registered app.

  3. Copy the Platform Callback URL.

  4. Navigate to the Azure portal.

  5. From the app registration Overview page, select Redirect URIs and click Add a Redirect URL.

  6. In the Platform configurations section, click Add a platform.

  7. Select Web.

  8. In the Redirect URIs field, enter the Platform callback URL that you copied and saved.

  9. Click Configure.

The Delinea Platform is now fully integrated with Entra ID, enabling a seamless, streamlined user management experience. You can now browse Entra ID users and groups directly on the platform, pre-assign permissions, add users instantly, and allow users to log in with their Entra ID credentials.

Automating Entra ID Integration Setup

You may streamline the Entra ID provisioning process by leveraging the automation script available in the Delinea XPM GitHub repository. This script provides a simple and repeatable setup experience by automating the creation of the necessary Azure and Delinea Platform application objects. For more details and usage instructions, refer to the Entra ID App Registration Automation Script repository.

Test the API-based Entra ID Integration

Create a test user in the Azure Portal and use the account to verify user login to the Delinea Platform.

  1. Go to the Azure portal and log in.

  2. Select or search for Users.

  3. Click New user > Create new user.

  4. Add the following:

    • User principal name

    • Display name

  5. Copy the generated Password because you will need it to log on to the Delinea Platform.

  6. Click Next > Properties.

  7. Add Email.

  8. Click Review + create.

  9. Click Create.

Test User Log-on to the Delinea Platform

  1. On the Delinea Platform, navigate to Settings > Federation providers.

  2. Select the generated OIDC federation configuration.

  3. Select Federation console.

  4. Click Start Debug Log.

  5. From a private browser window, navigate to your tenant and log on with the test user credentials.

The test user should be able to log on to the platform. If the user cannot log on, the Debug Log can help diagnose and resolve issues by capturing detailed information about the communication between the Platform and the Identity Provider (IdP). It provides insights into federation messages, claims, and potential misconfigurations, making it easier to pinpoint errors or inconsistencies in the authentication process.