Integrating Entra ID

At the end of 2023, Microsoft completed the change of their product name from Microsoft Azure Active Directory (Azure AD or ADD) to Microsoft Entra ID (Entra or Entra ID).

This documentation is a detailed guide for setting up single sign-on (SSO) through Entra ID, leveraging SAML 2.0 or OIDC.

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

You do not need to configure both OIDC and SAML applications for your integration. Depending on your organization's infrastructure and preferences, you can choose either OIDC or SAML.

Instead of using Entra ID federation as described in this topic, you can use Entra ID as a Registered App (native integration). See API-Based Integration with Entra ID. But you cannot use both features simultaneously with the same domains.

Prerequisites

On the Delinea Platform, you need to be an Administrator with federation privileges.

Decide whether you will be using SAML or OIDC.

Build an Entra SAML Application

  1. Log into the Entra ID portal at https://entra.microsoft.com.

  2. Click Manage Entra ID.

    Alt

  3. From the left panel, click Enterprise Applications.

    Alt

  4. From the top row, click + New Application.

    Alt

  5. At the top of the Browse Microsoft Entra ID Gallery page, click Create your own application.

    Alt

  6. On the Create your own application page:

    Alt

    1. Enter a meaningful name (for example, Delinea Federation).

    2. Ensure this option is selected: Integrate any other application you don't find in the gallery (Non-gallery).

    3. Click Create.

  7. Once your application is created, click Single sign-on from the left panel.

  8. Click the SAML card.

    Alt

  9. On the SAML-based Sign-on page, click Edit at the top right of the Basic SAML Configuration block

    Alt

  10. In the Basic SAML Configuration panel that appears on the right side, click Add Identifier.

    Alt

  11. Add the following values:

    Alt

  12. Identifier (Entity ID) CN=Microsoft:Azure:Federated:SSO:Certificate

  13. Reply URL (Assertion Consumer Service URL)
    https://[HOST-NAME].delinea.app/identity-federation/saml/assertion-consumer

    Replace [HOST-NAME] with the host name you selected when you created your tenant.

  14. Logout URL (Optional)
    https://[HOST-NAME].delinea.app/identity-federation/saml/logout-consumer

    Replace [HOST-NAME] with the host name you selected when you created your tenant.

  15. Click Save at the top left.

Attributes and Claims Mappings

  1. Click Edit at the right side of the Attributes & Claims block.

    Alt

    There are four (4) claims the Delinea Platform requires:

    Source | Destination

    • EmailAddress | email

    • Name | displayname

    • nameidentifier | sub

    • upn | upn

  2. In the Attributes & Claims dialog, click the Name claim as shown below and change the Source attribute to user.displayname.


  3. Click Save.

  4. As needed, add the groups assigned to this application as a claim in the SAML token. For details, see Add group claims to tokens for SAML applications using SSO configuration.

  5. Click Add new claim.

  6. On the Manage Claim page, enter the following values:

    • Name: nameidentifier

    • Source Attribute: user.objectid

    Alt

  7. Click Save.

  8. Add a second claim for the for upn using the following values:

    • Name: upn

    • Source Attribute: user.userprincipalname

    Alt

  9. Click Save. Your final claims appear.

    Alt

  10. Click the SAML-based Sign-on link to go back to the SAML setup screen.

    Alt

  11. In the SAML Certificates block, click Download next to Federation Metadata XML and Certificate (Base64)

    Alt

    You will use these saved files in the next step to configure the Federation service in your Delinea tenant.

Add the SAML Provider to the Platform

  1. Log in to the Delinea Platform.

  2. Click Settings from the left navigation, then click Federation Providers.

  3. Click Add Provider.

  4. Select SAML from the drop-down menu. The Add Provider page opens.

Settings

In the Settings section, the first fields are automatically populated when you select the SAML provider configuration file and click Apply.

  1. SAML provider configuration: Click Select file.

  2. Navigate to and select the federation metadata XML file you downloaded. Apply appears above the right end of the SAML provider configuration field.

  3. Click Apply. The words Uploaded successfully will appear next to SAML provider configuration, and the empty fields below will be auto-populated:

    • Name: Auto-generated from metadata

    • Protocol: SAML (auto-filled)

    • Status: Disabled

    • Entity ID [example: https://sts.windows.net/808444af-4011-40d5-9b0a-a9a5c95f88e9/]

    • IDP Certificate: Click Select File, then navigate to and select the Signing Certificate file you downloaded, to populate the following fields:

      • Signature

      • Algorithm

      • Thumbprint

      • Not valid before

      • Not valid after

      • Issuer

  4. IDP Login URL: Paste in the Login URL copied from your application in Entra, Step 4.

  5. IDP Logout URL: Paste in the Logout URL copied from your application in Entra, Step 4.

  6. Platform Callback URL: https://[HOST-NAME].delinea.app/identity-federation/saml/assertion-consumer
    Copy the Platform Callback URL and paste into the appropriate field in your new Entra application.

  7. Platform Logout URL: https://[HOST-NAME].delinea.app/identity-federation/saml/logout-consumer

  8. Status: Select the box next to Enabled.

Advanced Settings

See Advanced Settings (SAML only) under Federation Management.

Attribute Mappings

  • EmailAddress | email

  • Name | displayname

  • nameidentifier | sub

  • upn | upn

Group Mappings

  1. Click Add Group Mapping.

  2. Under Attribute, enter 'groups' (all lowercase).

  3. Under Source Name, enter the Object ID copied from the appropriate group on the Microsoft Entra ID Groups page.



  4. From the Groups drop-down, select a group from the pull-down menu. (You can use the groups attribute to map more than one group.)

Also see Mapping Federated Groups under Federation Management.

User Mappings

See Mapping Federated Users.

Domains

  1. Click Add Domain and enter the domain from the email addresses of the users you are including in this federation.

  2. Optionally enable the Status of the provider.

  3. When all required fields are populated, click Add Provider.

Build an Entra OIDC Application

If you chose not to use SAML (described in the previous section, Build an Entra SAML Application), use the following technique to build an OIDC application.

  1. Log into the Entra ID portal.

  2. From the Entra ID Home page, click the Entra ID icon.

    Alt

  3. Once inside the Entra ID service, click App Registrations from the left navigation.

    Alt

  4. Along the top row, click + New Registration.

    Alt

    The Register an application page appears.

    Alt

  5. Fill out the fields as follows:

    • Name: Give the new application you are registering a name. Any descriptive name works. This name will be displayed to users by Microsoft during the first login but it does not matter to the Delinea Platform. For demonstration purposes, we will use the name `azure-oidc-testdemo'

    • Supported account types: Click the one with Single tenant in its name. To see the difference between the account types, click Help me choose….

    • Redirect URL: This can be added in a later step.

  6. Click Register at the bottom left.

  7. From the left navigation, click Token Configuration.

    Alt

  8. Click Add optional claim.

    Alt

    A panel opens on the right side.

    Alt

    • Under Token Type, click ID.

    • Under Claim, click preferred_username.

  9. Click Add at the bottom left.

Add the OIDC Provider to the Platform

  1. Log on to the platform.

  2. Click Settings from the left navigation, then click Federation Providers.

  3. Click Add Provider.

  4. Select OIDC from the drop-down menu. The Add Provider page opens.

Settings

  1. Name: Enter a unique name.

  2. Status: Select the box next to Enabled.

  3. Endpoint URL: This URL is based on your Entra ID tenant ID. To retrieve your Entra ID tenant ID:

    1. Return to your Entra ID app page and click Endpoints at the top of the page.

      Alt

    2. From the panel that opens to the right, select the URL below OpenID Connect metadata document

    3. Copy the entire URL only up to v2.0. The value will be https://login.microsoftonline.com/[TenantId]/v2.0. See the image below.

      Alt

  4. Paste the copied portion of the URL into the Endpoint URL field on the platform.

  5. Client ID: Copy this value from your new Entra application page next to Application (client) ID and paste it into the Client ID field on the platform +Add Federation Service page.

  6. Client Secret:

    1. Return to your new Entra application page.

    2. Click Certificates & Secrets from the left navigation.

    3. Click + New client secret.

    4. In the panel that opens to the right, fill in the fields for Description and Expires.

    5. Click Add at the bottom. A secret value is generated.

    6. Copy the Secret value from the Value field.

    7. Paste the value into the Client Secret field on the platform Add Provider page.

  7. Prompt: See Prompt for Re-authentication (OIDC only) under Federation Management.

  8. Platform Callback URL: Copy the platform callback URL and paste it into the Redirect URIs field in your new Microsoft Entra ID application.

Attribute Mappings

Some defaults are provided but can be overridden as needed. In this example we will replace the upn value with preferred_username.

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress | email

  • name | displayname

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier | sub

  • preferred_username | upn

Group Mappings

  1. Click Add Group Mapping.

  2. Under Attribute, enter 'groups' (all lowercase).

  3. Under Source Name, enter the Object ID copied from the appropriate groups on the Microsoft Entra ID Groups page.



  4. Under the Group drop-down, select a group from the pull-down menu. (You can use the group attribute to map more than one group.)

Also see Mapping Federated Groups under Federation Management.

User Mappings

See Mapping Federated Users under Federation Management.

Domains

  1. Click Add Domain and enter the domain from the email addresses of the users you are including in this federation. If you specify the Entra ID guest domain, then Entra guest users can also access the platform.

When all required fields are populated, click Add Provider.

Add the Platform

  1. On the Entra App Registration page, click Authentication and then Add a platform.

    Alt

  2. In the panel that opens on the right, click Web.

    Alt

  3. Under Redirect URIs, enter your Platform Callback URL from your provider page.

  4. Click Configure at the bottom of the panel.

From Your Entra Application

  1. Log in to your Microsoft Entra ID application and open to the Home page.

  2. From the left navigation menu, click App Registrations.

  3. Click the All applications tab.

  4. Click the appropriate SAML or OIDC federation application created by your organization, for example:

    Alt

  5. From the left menu navigation, click Token Configuration.

    Alt

  6. Click + Add group claim.

  7. From the panel that pops up named Edit group claims, select the group types to include. We strongly recommend selecting Groups assigned to the application to ensure that only the needed groups are sent to the platform.

    Alt

  8. Click Add at the bottom.

  9. From the breadcrumb path at the top of the page, select the name of the Entra ID directory you're configuring, for example:

    Alt

  10. Click Groups from the left navigation menu.

    Alt

  11. Select the group you are working with and copy the group's Object ID.

    Alt

From the Platform

  1. Log out of the Platform.

  2. Log back into the platform as a user who belongs to a platform group mapped to an Microsoft Entra ID group.

  3. Click Access from the left navigation menu, then click Groups from the secondary menu.

  4. Click a platform group that you've mapped to an Microsoft Entra ID group, where your user should appear.

  5. Click the Members tab.

  6. Verify that the user you logged in as, is a member of the platform group that you mapped to an Microsoft Entra ID group.