Skip to content

api-management-howto-aad.md

Latest commit

 

History

History
226 lines (146 loc) · 13.5 KB

api-management-howto-aad.md

File metadata and controls

226 lines (146 loc) · 13.5 KB
title Authorize access to API Management developer portal by using Microsoft Entra ID
titleSuffix Azure API Management
description Learn how to enable user sign-in to the API Management developer portal by using Microsoft Entra ID.
author dlepow
ms.service azure-api-management
ms.topic how-to
ms.date 03/12/2026
ms.author danlep
ms.custom
engagement-fy23
devx-track-azurecli
sfi-image-nochange

Authorize developer accounts by using Microsoft Entra ID in Azure API Management

[!INCLUDE premium-dev-standard-premiumv2-standardv2-basicv2.md]

In this article, you learn how to:

[!div class="checklist"]

  • Enable access to the developer portal for users in your organization's Microsoft Entra ID tenant or other Microsoft Entra ID workforce tenants.
  • Optionally, add external identity providers, such as Google or Facebook, to your Microsoft Entra ID workforce tenant to allow users to sign in with those accounts.
  • Manage groups of Microsoft Entra users by adding external groups that contain the users.

For an overview of options to secure the developer portal, see Secure access to the API Management developer portal.

Important

  • This article is updated with steps to configure a Microsoft Entra app by using the Microsoft Authentication Library (MSAL).
  • If you previously configured a Microsoft Entra app for user sign-in by using the Azure AD Authentication Library (ADAL), migrate to MSAL.

[!INCLUDE api-management-developer-portal-entra-tenants.md]

Prerequisites

[!INCLUDE api-management-navigate-to-instance.md]

[!INCLUDE api-management-developer-portal-entra-app.md]

Migrate to MSAL

If you previously configured a Microsoft Entra app for user sign-in by using ADAL, you can use the portal to migrate the app to MSAL and update the identity provider in API Management.

Update Microsoft Entra app for MSAL compatibility

For steps, see Switch redirect URIs to the single-page application type.

Update identity provider configuration

  1. In the left menu of your API Management instance, under Developer portal, select Identities.
  2. Select Microsoft Entra ID from the list.
  3. In the Client library dropdown, select MSAL.
  4. Select Update.
  5. Republish your developer portal.

Enable access by external users in your Microsoft Entra ID tenant (optional)

API Management supports external identity providers when you configure them in a Microsoft Entra ID workforce tenant. For example, if you're enabling access to the developer portal by users in your workforce tenant, such as the Contoso organization, you might want to configure Google or Facebook as an external identity provider so that these external users can also sign in by using their accounts.

To optionally enable access to the developer portal by external users in your Microsoft Entra ID tenant, complete the following steps:

  1. Add an external identity provider to your Microsoft Entra ID tenant.
  2. Enable self-service sign-up.

1. Add an external identity provider to your Microsoft Entra ID tenant

For this scenario, you must enable an external identity provider in your workforce tenant. Configuring the external identity provider depends on the specific provider and is outside the scope of this article. For example, for Google you must create a project in the Google Developers Console, then configure the project credentials in Microsoft Entra.

For options and links to steps, see Identity providers for External ID in workforce tenants.

2. Enable self-service sign-up

To allow external users to register for access to the developer portal, complete the following steps:

a. Enable self-service sign-up for your tenant.

b. Add your app to the self-service sign-up user flow.

For more information and detailed steps, see Add self-service sign-up user flows for B2B collaboration.

Enable access by users in more than one Microsoft Entra ID tenant (optional)

Note

Support for access to the developer portal by users from multiple Microsoft Entra ID tenants is currently available in the API Management Developer, Standard, and Premium tiers.

To optionally enable access to the developer portal by users from more than one Microsoft Entra ID tenant, complete the following steps:

  1. Configure app registration for multiple tenants.
  2. Update the Microsoft Entra ID identity provider configuration for the developer portal to add another tenant.

1. Configure app registration for multiple tenants

The app registration must support multiple tenants. You can configure this support in either of the following ways:

  • When creating the app registration, set Supported account types to Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant).
  • If you previously configured an app registration for a single tenant, update the Supported account types setting on the Manage > Authentication page of the app registration.

2. Update Microsoft Entra ID identity provider configuration for multiple tenants

Update the identity provider configuration to add another tenant:

  1. In the Azure portal, go to your API Management instance.
  2. Under Developer portal, select Identities.
  3. Select Microsoft Entra ID from the list.
  4. In the Tenant ID field, add the extra tenant IDs separated by commas.
  5. Update the value of Signin tenant to one of the configured tenants.
  6. Select Update.
  7. Republish your developer portal.

Add an external Microsoft Entra group

After you enable access for users in a Microsoft Entra tenant, you can:

  • Add Microsoft Entra groups into API Management. You must add groups in the tenant where you deployed your API Management instance.
  • Control product visibility by using Microsoft Entra groups.
  1. Go to the App Registration page for the application you registered in the previous section.
  2. Select API Permissions.
  3. Add the following minimum application permissions for Microsoft Graph API:
    • User.Read.All application permission – so API Management can read the user’s group membership to perform group synchronization when the user signs in.
    • Group.Read.All application permission – so API Management can read the Microsoft Entra groups when an administrator tries to add the group to API Management by using the Groups blade in the portal.
  4. Select Grant admin consent for {tenantname} to grant access for all users in this directory.

Now you can add external Microsoft Entra groups from the Groups tab of your API Management instance.

  1. Under Developer portal in the side menu, select Groups.

  2. Select the Add Microsoft Entra group button.

    :::image type="content" source="media/api-management-howto-aad/api-management-with-aad008.png" alt-text="Screenshot showing Add Microsoft Entra group button in the portal.":::

  3. Select the Tenant from the drop-down.

  4. Search for and select the group that you want to add.

  5. Select Select.

After you add an external Microsoft Entra group, you can review and configure its properties:

  1. Select the name of the group from the Groups tab.
  2. Edit Name and Description information for the group.

Users from the configured Microsoft Entra instance can now:

  • Sign in to the developer portal.
  • View and subscribe to any groups for which they have visibility.

Note

Learn more about the difference between Delegated and Application permissions types in Permissions and consent in the Microsoft identity platform article.

Synchronize Microsoft Entra groups with API Management

Groups you configure in Microsoft Entra must synchronize with API Management so that you can add them to your instance. If the groups don't synchronize automatically, use one of the following steps to manually synchronize group information:

  • Sign out and sign in to Microsoft Entra ID. This activity usually triggers synchronization of groups.
  • Ensure that you specify the Microsoft Entra sign-in tenant the same way (by using either the tenant ID or domain name) in your configuration settings in API Management. You specify the sign-in tenant in the Microsoft Entra ID identity provider for the developer portal and when you add a Microsoft Entra group to API Management.

Developer portal: Add Microsoft Entra account authentication

In the developer portal, you can enable sign in with Microsoft Entra ID by using the Sign-in button: OAuth widget included on the sign-in page of the default developer portal content.

A user can then sign in by using Microsoft Entra ID as follows:

  1. Go to the developer portal. Select Sign in.

  2. On the Sign in page, select Microsoft Entra ID. Selecting this button opens the Microsoft Entra ID sign-in page.

    :::image type="content" source="media/api-management-howto-aad/developer-portal-azure-ad-signin.png" alt-text="Screenshot showing OAuth widget in developer portal.":::

    [!TIP] If you configure more than one tenant for access, more than one Microsoft Entra ID button appears on the sign-in page. Each button is labeled with the tenant name.

  3. In the sign-in window for the Microsoft Entra tenant, respond to the prompts.

    [!NOTE] If you enabled an external identity provider in your Microsoft Entra tenant and configured self-service sign-up, select the external identity provider in the sign-in window to sign in with those credentials. For example, if you configured Google as an identity provider, select Sign in with Google.

After sign-in is complete, the user is redirected back to the developer portal. The user is now signed in to the developer portal and added as a new API Management user identity in Users.

Although a new account is automatically created when a new user signs in by using Microsoft Entra ID, consider adding the same widget to the sign-up page. The Sign-up form: OAuth widget represents a form used for signing up by using OAuth.

Important

You need to republish the portal for the Microsoft Entra ID changes to take effect.

Related content