Configuring Microsoft Entra ID

This is a guide on how to define an integration between the PlainID Token Enrichment Service (aka the idp-hook) in the PAA, and your Microsoft Entra ID IDP tenant. You can use Microsoft Entra ID tokens with the PlainID IDP Token Enrichment Service within the PAA to gain greater flexibility and a more dynamic approach to enrich your users tokens with PBAC based dynamic claims.

Prerequisites

Before proceeding, ensure that the following prerequisites have been met:

Vendor - Microsoft Entra ID

• A Microsoft Entra ID custom extension. The basic steps to define a custom extension attribute for the PlainID Webhook in Microsoft Entra ID can be found in the Microsoft Entra ID Setup below.

PlainID

• A functioning PAA and a deployed IDP Token Enrichment Service.
• A defined PlainID Application:
  • An associated Asset Type that manages the relevant Claim with the Application, including:
    • Scope (Client ID and Client Secret)
    • claimKey and claimValue attributes
• A Policy associated with the Application.
• At least one User associated with the Application in the IDP.
• An Access Policy Rule.

Microsoft Entra ID Setup

Creating a Custom Extension

After creating a PlainID Application, create and define a custom extension in your Entra ID tenant to link them. You can also refer to the Microsoft Entra documentation for more information.

1. In the Microsoft Azure Portal, ensure that the user has a Global Administrator or Application Administrator and Authentication Extensibility Administrator role. Refer to the Microsoft's Permissions documentation for more information.
2. When creating a custom Extension, input the following in the relevant fields in the Endpoint Configuration:
   1. Name - A name for your custom extension. Example: Token issuance event.
   2. Target URL - IDP webhook Endpoint in this format: https://<idp-webhook-base-url>/idp-hook/1.0/entraid/extension
   3. Description - PlainID Webhook
3. In the API Authentication section, register an Application that represents the PlainID Token Enrichment Service.
4. In the Claims section, enter the attributes to parse from the PlainID IDP Webhook through your custom extension. Example:
   • plainidProvidedRoles
   • plainidProvidedAccess
5. Click Create to create your custom extension.

Enabling your Application for Claims Mapping Policy

A Claims Mapping Policy is required to select which Attributes returned from the custom extension are mapped into the token. It is required to enable the Application registration to accept mapped claims and allow tokens to be augmented. Refer to Microsoft's documentation on Enabling your App for a Claims Policy for a detailed guide.

Assigning a Custom Claims Provider

For tokens to be issued with claims coming from the custom extension, custom claims are required to be assigned to the Application provider. The custom claims provider relies on the custom extension configured with the token. You can opt whether a subset of or all claims from the custom claims provider are mapped into the token.

To assign the custom extension as a custom claims provider source, refer to the documentation on Assigning a custom claims provider to your app.

The custom claims provider should be issued into the token as claims. To assign the attributes from the custom claims provider:

1. Select Add new claim to add a new claim. Input a name for the claim you want to be issued, like "plainidProvidedRoles."
2. Under Source, select Attribute, and choose customClaimsProvider.plainidProvidedRoles from the Source Attribute drop-down list.

Entra ID Parameters for the IDP Token Enrichment Service (Helm)

The other side of the integration is done on the PlainID IDP Token Enrichment Service in your PAA. You will need to add some configuration to the service to connect the Entra ID requests to an enrichment flow and map claims to the response generated to Microsoft Entra ID.

To connect your Entra ID parameters, add the following properties from the idpWebhook code in the values.yaml to the values-custom.yaml.
See the IDP WebHook article for a full list of parameters.

Parameters

These parameters are specific to Entra ID. See the IDP Token Enrichment article for a full list of parameters.

Integrating Microsoft Entra ID with the PlainID Token Enrichment Service enhances your identity management by enabling dynamic policy-based access control within your tokens. By following this guide, you should have successfully set up the required custom extensions, configured your claims mapping, and connected your Entra ID parameters with the PlainID IDP Token Enrichment Service.

Additional Information

For more technical details on how to connect this vendor to your IDP Webhook, contact PlainID Support.