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

APPLIES TO: Developer | Basic v2 | Standard | Standard v2 | Premium

In this article, you'll learn how to:

• Enable access to the developer portal for users from Microsoft Entra ID.
• 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 has been updated with steps to configure a Microsoft Entra app using the Microsoft Authentication Library (MSAL).
• If you previously configured a Microsoft Entra app for user sign-in using the Azure AD Authentication Library (ADAL), we recommend that you migrate to MSAL.

Prerequisites

• Complete the Create an Azure API Management instance quickstart.

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

• Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.

  

• If you prefer to run CLI reference commands locally, 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.

  • If you're using a local installation, 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.

   

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

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

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

    Important

    Update the Client secret before the key expires.

19. In Signin tenant, specify a tenant name or ID to use for sign-in to Microsoft Entra. If no value is specified, the Common endpoint is used.

20. In Allowed tenants, add specific Microsoft Entra tenant names or IDs for sign-in to Microsoft Entra.

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 tenant(s) 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. Groups added must be in the tenant where your API Management instance is deployed.
• 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.

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

Important

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

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.