Authorize developer accounts by using Azure Active Directory in Azure API Management

In this article, you'll learn how to:

• Enable access to the developer portal for users from Azure Active Directory (Azure AD).
• Manage groups of Azure AD 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 an Azure AD app using the Microsoft Authentication Library (MSAL).
• If you previously configured an Azure AD 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.

Availability

Important

This feature is available in the Premium, Standard and Developer tiers of API Management.

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 Azure AD - portal

To simplify the configuration, API Management can automatically enable an Azure AD application and identity provider for users of the developer portal. Alternatively, you can manually enable the Azure AD application and identity provider.

Automatically enable Azure AD 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 Azure Active Directory.

3. Select Enable Azure AD.

4. On the Enable Azure AD page, select Enable Azure AD.

5. Select Close.

   

After the Azure AD provider is enabled:

• Users in the specified Azure AD instance can sign into the developer portal by using an Azure AD account.
• You can manage the Azure AD 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 Azure AD 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 Azure Active Directory 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 Azure AD 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.net/aadadminconsent).
    2. Enter the domain name of the Azure AD 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 Azure AD configuration to take effect. In the left menu, under Developer portal, select Portal overview > Publish.

After the Azure AD provider is enabled:

• Users in the specified Azure AD instance can sign into the developer portal by using an Azure AD account.
• You can manage the Azure AD 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 an Azure AD 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 Azure AD 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 Azure Active Directory from the list.
3. In the Client library dropdown, select MSAL.
4. Select Update.
5. Republish your developer portal.

Add an external Azure AD group

Now that you've enabled access for users in an Azure AD tenant, you can:

• Add Azure AD groups into API Management.
• Control product visibility using Azure AD 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 Azure AD 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 Azure AD groups from the Groups tab of your API Management instance.

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

2. Select the Add Azure AD 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 Azure AD 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 Azure AD 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.

Developer portal: Add Azure AD account authentication

In the developer portal, you can sign in with Azure AD 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 Azure AD, 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 Azure AD changes to take effect.

Legacy developer portal: How to sign in with Azure AD

Note

The following documentation content is about the deprecated developer portal. You can continue to use it, as per usual, until its retirement in October 2023, when it will be removed from all API Management services. The deprecated portal will only receive critical security updates. Refer to the following articles for more details:

• Learn how to migrate to the new developer portal
• Azure API Management new developer portal overview
• Access and customize the new developer portal

To sign into the developer portal by using an Azure AD account that you configured in the previous sections:

1. Open a new browser window using the sign-in URL from the Active Directory application configuration.

2. Select Azure Active Directory.

   

3. Enter the credentials of one of the users in Azure AD.

4. Select Sign in.

   

5. If prompted with a registration form, complete with any additional information required.

6. Select Sign up.

   

Your user is now signed in to the developer portal for your API Management service instance.

Next Steps

• Learn more about Azure Active Directory and OAuth2.0.
• Learn more about MSAL and migrating to MSAL.
• Create an API Management service instance.
• Manage your first API.