Entra ID API Integration

This feature is currently available only to customers participating in our public preview. To access public preview features, see Public Preview Program.

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.

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

  • New Feature: User deactivation or deletion in Entra ID is reflected in the platform. This functionality was added with Public Preview.

  • New Feature: Easily manage which groups from Entra ID are visible and usable within the platform. This functionality was added with Public Preview. See External Directory Group Allowlist.

  • New Feature: Paginated results are returned when browsing Entra ID users and groups when managing role and identity policy member assignment and sharing secrets. This functionality was added with Public Preview.

This topic walks you through setting up an Entra ID API integration on the Delinea Platform. The platform provides two options for this integration. You only need to choose one of these methods:

  • Creating a Delinea-managed registered app. This approach is recommended if you prefer to configure the Entra ID integration entirely within the Delinea Platform and let Delinea handle the creation and management of the necessary Azure components. New Feature: This functionality was added with Public Preview.

  • Creating a customer-managed registered app. This approach is suitable if you prefer to maintain full control over the integration and manage the Azure resources yourself.

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

On the Delinea Platform, the Entra ID API Integration cannot run on the same Directory Tenant as Entra ID Federation or Active Directory (Connector), including implementations of Privilege Control for Servers. This misconfiguration would create potential collisions for an AD user sharing the same UPN (username or email address) as an Entra user, because each user has a unique Object ID (GUID).

Create a Delinea-Managed Registered App

This procedure walks you through setting up Entra ID on the Delinea Platform using a Delinea-managed registered app. To complete and test the integration you will need to do the following:

  • Add a Delinea-managed registered app.

  • Grant Delinea permission to create and manage application registrations in Azure.

Add a Delinea-Managed Registered App

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

  2. Click Add App.

  3. Select Delinea Managed Entra ID.

  4. On the Add Delinea managed Entra ID App page, complete the following fields:

    Delinea Platform Field  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".

  5. Select all settings in the table below:

    Delinea Platform Field  Description
    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.

  6. Click Save.

Grant Delinea Permission to Create and Manage App Registrations in Azure

  1. Grant Consent for the Delinea Entra ID Management App

    1. On the next screen in the Entra ID app management section, select Grant consent.

    2. In the Microsoft Pick an account dialog, log in with your Microsoft account credentials.

    3. In the Permissions requested dialog for Delinea Platform Azure Registered Apps:

      1. Review the required permissions.

      2. Select Accept.

  2. Grant Consent to Read the Entra ID Users and Groups

    1. In the Entra ID – Read section, select Grant consent.

    2. In the Microsoft Pick an account dialog, log in with your Microsoft account credentials.

    3. In the Permissions requested dialog for Delinea Managed azure-entra-read:

      1. Review the required permissions.

      2. Select Accept.

  3. Select Domains for User Login

    1. Click Edit.

    2. In the Log-in to Entra ID section, select the desired domains for user login.

    3. Click Save.

  4. Grant Consent to User Login

    1. In the Log-in to Entra ID section click Grant consent.

    2. In the Microsoft Pick an account dialog, log in with your Microsoft account credentials.

    3. In the Permissions requested dialog for Delinea Managed azure-entra-login:

      1. Review the required permissions.

      2. Select Consent on behalf of your organization.

      3. Click Accept.

After you have completed the steps above, the following three apps should be created in Azure and should reflect the state, Consent granted on the Delinea Platform:

  • Entra ID app management ( Delinea Platform Azure Registered Apps)

  • Entra ID – Read (Delinea Managed azure-entra-read)

  • Log-in to Entra ID (Delinea Managed azure-entra-login)

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.

Create a Customer-Managed Registered App

This procedure walks you through setting up and testing Entra ID on the Delinea Platform using a customer-managed registered app.

  1. Register an App in Azure:

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

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

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

  2. Register a customer-managed app on the Delinea Platform: Enter the app credentials, permissions and domains.

  3. Test the 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.

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 to 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 to 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:

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

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

Create a Customer-Managed Registered App on the Delinea Platform

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

  2. Click Add App. Select Customer Managed Entra ID.

  3. On the Add registered app page, complete the following fields:

    Delinea Platform Field

    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 settings in the table below:

    Delinea Platform Field

    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. 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). The log provides insights into federation messages, claims, and potential misconfigurations, making it easier to pinpoint errors or inconsistencies in the authentication process.