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.

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

You can use the local Azure CLI.

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.

    Select API Management services

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

    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.

    Screenshot of enabling Azure AD in the developer portal overview page.

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.

    Screenshot of adding identity provider in Azure portal.

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

Follow these steps to grant:

  • User.Read delegated permission for Microsoft Graph API.
  • Directory.ReadAll application permission for Microsoft Graph API.
  1. Update the first 3 lines of the following Azure CLI script to match your environment and run it.

    $subId = "Your Azure subscription ID" # Example: "1fb8fadf-03a3-4253-8993-65391f432d3a"
    $tenantId = "Your Azure AD Tenant or Organization ID" # Example: 0e054eb4-e5d0-43b8-ba1e-d7b5156f6da8"
    $appObjectID = "Application Object ID that has been registered in AAD" # Example: "2215b54a-df84-453f-b4db-ae079c0d2619"
    #Login and Set the Subscription
    az login
    az account set --subscription $subId
    #Assign the following permission: Microsoft Graph Delegated Permission: User.Read, Microsoft Graph Application Permission: Directory.ReadAll
    az rest --method PATCH --uri "https://microsoftgraph.chinacloudapi.cn/v1.0/$($tenantId)/applications/$($appObjectID)" --body "{'requiredResourceAccess':[{'resourceAccess': [{'id': 'e1fe6dd8-ba31-4d61-89e7-88639da4683d','type': 'Scope'},{'id': '7ab1d382-f21e-4acd-a863-ba3e13f7da61','type': 'Role'}],'resourceAppId': '00000003-0000-0000-c000-000000000000'}]}"
    
  2. Sign out and sign back in to the Azure portal.

  3. Navigate to the App Registration page for the application you registered in the previous section.

  4. Select API Permissions. You should see the permissions granted by the Azure CLI script in step 1.

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

    "Screenshot showing 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.

Screenshot showing OAuth widget in developer portal.

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:

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.

    Sign-in page

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

  4. Select Sign in.

    Signing in with username and password

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

  6. Select Sign up.

    "Sign up" button on registration form

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

Developer portal after registration is complete

Next Steps