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

In this article, you'll learn how to:

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

Prerequisites

• Complete the Create an Azure API Management instance quickstart.

• Import and publish an API in the Azure API Management instance.

You can use the local Azure CLI.

• If you prefer, install the Azure CLI to run CLI reference commands.

• Local Azure CLI, see how to install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

  • Sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.

  • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.

  • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

Go to your API Management instance

1. In the Azure portal, search for and select API Management services.

   

2. On the API Management services page, select your API Management instance.

   

Enable user sign-in using Microsoft Entra ID - portal

To simplify the configuration, API Management can automatically enable a Microsoft Entra application and identity provider for users of the developer portal. Alternatively, you can manually enable the Microsoft Entra application and identity provider.

Automatically enable Microsoft Entra application and identity provider

1. In the left menu of your API Management instance, under Developer portal, select Portal overview.

2. On the Portal overview page, scroll down to Enable user sign-in with Microsoft Entra ID.

3. Select Enable Microsoft Entra ID.

4. On the Enable Microsoft Entra ID page, select Enable Microsoft Entra ID.

5. Select Close.

   

After the Microsoft Entra provider is enabled:

• Users in the specified Microsoft Entra instance can sign into the developer portal by using a Microsoft Entra account.
• You can manage the Microsoft Entra configuration on the Developer portal > Identities page in the portal.
• Optionally configure other sign-in settings by selecting Identities > Settings. For example, you might want to redirect anonymous users to the sign-in page.
• Republish the developer portal after any configuration change.

Manually enable Microsoft Entra application and identity provider

1. In the left menu of your API Management instance, under Developer portal, select Identities.

2. Select +Add from the top to open the Add identity provider pane to the right.

3. Under Type, select Microsoft Entra ID from the drop-down menu. Once selected, you'll be able to enter other necessary information.

   • In the Client library dropdown, select MSAL.
   • To add Client ID and Client secret, see steps later in the article.

4. Save the Redirect URL for later.

   

   Note

   There are two redirect URLs:
   

   • Redirect URL points to the latest developer portal of the API Management.
   • Redirect URL (deprecated portal) points to the deprecated developer portal of API Management.

   We recommended you use the latest developer portal Redirect URL.

5. In your browser, open the Azure portal in a new tab.

6. Navigate to App registrations to register an app in Active Directory.

7. Select New registration. On the Register an application page, set the values as follows:

   • Set Name to a meaningful name such as developer-portal
   • Set Supported account types to Accounts in any organizational directory.
   • In Redirect URI, select Single-page application (SPA) and paste the redirect URL you saved from a previous step.
   • Select Register.

8. After you've registered the application, copy the Application (client) ID from the Overview page.

9. Switch to the browser tab with your API Management instance.

10. In the Add identity provider window, paste the Application (client) ID value into the Client ID box.

11. Switch to the browser tab with the App registration.

12. Select the appropriate app registration.

13. Under the Manage section of the side menu, select Certificates & secrets.

14. From the Certificates & secrets page, select the New client secret button under Client secrets.

    • Enter a Description.
    • Select any option for Expires.
    • Choose Add.

15. Copy the client Secret value before leaving the page. You will need it later.

16. Under Manage in the side menu, select Authentication.

    1. Under the Implicit grant and hybrid flows section, select the ID tokens checkbox.
    2. Select Save.

17. Under Manage in the side menu, select Token configuration > + Add optional claim.

    1. In Token type, select ID.
    2. Select (check) the following claims: email, family_name, given_name.
    3. Select Add. If prompted, select Turn on the Microsoft Graph email, profile permission.

18. Switch to the browser tab with your API Management instance.

19. Paste the secret into the Client secret field in the Add identity provider pane.

    Important

    Update the Client secret before the key expires.

20. In the Add identity provider pane's Allowed tenants field, specify the Microsoft Entra instance's domains to which you want to grant access to the API Management service instance APIs.

    • You can separate multiple domains with newlines, spaces, or commas.

    Note

    You can specify multiple domains in the Allowed Tenants section. A global administration must grant the application access to directory data before users can sign in from a different domain than the original app registration domain. To grant permission, the global administrator should:

    1. Go to https://<URL of your developer portal>/aadadminconsent (for example, https://contoso.portal.azure-api.cn/aadadminconsent).
    2. Enter the domain name of the Microsoft Entra tenant to which they want to grant access.
    3. Select Submit.

21. After you specify the desired configuration, select Add.

22. Republish the developer portal for the Microsoft Entra configuration to take effect. In the left menu, under Developer portal, select Portal overview > Publish.

After the Microsoft Entra provider is enabled:

• Users in the specified Microsoft Entra instance can sign into the developer portal by using a Microsoft Entra account.
• You can manage the Microsoft Entra configuration on the Developer portal > Identities page in the portal.
• Optionally configure other sign-in settings by selecting Identities > Settings. For example, you might want to redirect anonymous users to the sign-in page.
• Republish the developer portal after any configuration change.

Migrate to MSAL

If you previously configured a Microsoft Entra app for user sign-in using the 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.

Add an external Microsoft Entra group

Now that you've enabled access for users in a Microsoft Entra tenant, you can:

• Add Microsoft Entra groups into API Management.
• Control product visibility using Microsoft Entra groups.

1. Navigate 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 at the time the user logs 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 using the Groups blade in the portal.
4. Select Grant admin consent for {tenantname} so that you 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.

   

3. Select the Tenant from the drop-down.

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

5. Press the Select button.

Once 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 into the developer portal.
• View and subscribe to any groups for which they have visibility.

Synchronize Microsoft Entra groups with API Management

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

• Sign out and sign in to Microsoft Entra ID. This activity usually triggers synchronization of groups.
• Ensure that the Microsoft Entra sign-in tenant is specified the same way (using one of 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 sign in with Microsoft Entra ID using the Sign-in button: OAuth widget included on the sign-in page of the default developer portal content.

Although a new account will automatically be created when a new user signs in with 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 with OAuth.

Related content

• Learn more about Microsoft Entra ID and OAuth2.0.
• Learn more about MSAL and migrating to MSAL.
• Troubleshoot network connectivity to Microsoft Graph from inside a VNet.