Warning

Azure Active Directory integration is available in the Developer and Premium tiers only.

How to authorize developer accounts using Azure Active Directory in Azure API Management

Overview

This guide shows you how to enable access to the developer portal for users from Azure Active Directory. This guide also shows you how to manage groups of Azure Active Directory users by adding external groups that contain the users of an Azure Active Directory.

To complete the steps in this guide you must first have an Azure Active Directory in which to create an application.

How to authorize developer accounts using Azure Active Directory

To get started, click Publisher portal in the Azure portal for your API Management service. This takes you to the API Management publisher portal.

Publisher portal

If you have not yet created an API Management service instance, see Create an API Management service instance in the Get started with Azure API Management tutorial.

Click Security from the API Management menu on the left and click External Identities.

External Identities

Click Azure Active Directory. Make a note of the Redirect URL and switch over to your Azure Active Directory in the Azure Classic Portal.

External Identities

Click the Add button to create a new Azure Active Directory application, and choose Add an application my organization is developing.

Add new Azure Active Directory application

Enter a name for the application, select Web application and/or Web API, and click the next button.

New Azure Active Directory application

For Sign-on URL, enter the sign-on URL of your developer portal. In this example, the Sign-on URL is https://aad03.portal.current.int-azure-api.net/signin.

For the App ID URL, enter either the default domain or a custom domain for the Azure Active Directory, and append a unique string to it. In this example, the default domain of https://contoso5api.onmicrosoft.com is used with the suffix of /api specified.

New Azure Active Directory application properties

Click the check button to save and create the application, and switch to the Configure tab to configure the new application.

New Azure Active Directory application created

If multiple Azure Active Directories are going to be used for this application, click Yes for Application is multi-tenant. The default is No.

Application is multi-tenant

Copy the Redirect URL from the Azure Active Directory section of the External Identities tab in the publisher portal and paste it into the Reply URL text box.

Reply URL

Scroll to the bottom of the configure tab, select the Application Permissions drop-down, and check Read directory data.

Application Permissions

Select the Delegate Permissions drop-down, and check Enable sign-on and read users' profiles.

Delegated Permissions

For more information about application and delegated permissions, see Accessing the Graph API.

Copy the Client Id to the clipboard.

Client Id

Switch back to the publisher portal and paste in the Client Id copied from the Azure Active Directory application configuration.

Client Id

Switch back to the Azure Active Directory configuration, and click the Select duration drop-down in the Keys section and specify an interval. In this example, 1 year is used.

Key

Click Save to save the configuration and display the key. Copy the key to the clipboard.

Make a note of this key. Once you close the Azure Active Directory configuration window, the key cannot be displayed again.

Key

Switch back to the publisher portal and paste the key into the Client Secret text box.

Client Secret

Allowed Tenants specifies which directories have access to the APIs of the API Management service instance. Specify the domains of the Azure Active Directory instances to which you want to grant access. You can separate multiple domains with newlines, spaces, or commas.

Allowed tenants

Once the desired configuration is specified, click Save.

Save

Once the changes are saved, the users in the specified Azure Active Directory can sign in to the Developer portal by following the steps in Log in to the Developer portal using an Azure Active Directory account.

Multiple domains can be specified in the Allowed Tenants section. Before any user can log in from a different domain than the original domain where the application was registered, a global administrator of the different domain must grant permission for the application to access directory data. To grant permission, the global administrator should go to https://<URL of your developer portal>/aadadminconsent (for example, https://contoso.portal.azure-api.net/aadadminconsent), type in the domain name of the Active Directory tenant they want to give access to and click Submit. In the following example, a global administrator from miaoaad.onmicrosoft.com is trying to give permission to this particular developer portal.

Permissions

In the next screen, the global administrator will be prompted to confirm giving the permission.

Permissions

If a non-global administrator tries to log in before permissions are granted by a global administrator, the login attempt fails and an error screen is displayed.

How to add an external Azure Active Directory Group

After enabling access for users in an Azure Active Directory, you can add Azure Active Directory groups into API Management to more easily manage the association of the developers in the group with the desired products.

To configure an external Azure Active Directory group, the Azure Active Directory must first be configured in the Identities tab by following the procedure in the previous section.

External Azure Active Directory groups are added from the Visibility tab of the product for which you wish to grant access to the group. Click Products, and then click the name of the desired product.

Configure product

Switch to the Visibility tab, and click Add Groups from Azure Active Directory.

Add groups

Select the Azure Active Directory Tenant from the drop-down list, and then type the name of the desired group in the Groups to be added text box.

Select group

This group name can be found in the Groups list for your Azure Active Directory, as shown in the following example.

Azure Active Directory Groups List

Click Add to validate the group name and add the group. In this example, the Contoso 5 Developers external group is added.

Group added

Click Save to save the new group selection.

Once an Azure Active Directory group has been configured from one product, it is available to be checked on the Visibility tab for the other products in the API Management service instance.

To review and configure the properties for external groups once they have been added, click the name of the group from the Groups tab.

Manage groups

From here you can edit the Name and the Description of the group.

Edit group

Users from the configured Azure Active Directory can sign in to the Developer portal and view and subscribe to any groups for which they have visibility by following the instructions in the following section.

How to log in to the Developer portal using an Azure Active Directory account

To log into the Developer portal using an Azure Active Directory account configured in the previous sections, open a new browser window using the Sign-on URL from the Active Directory application configuration, and click Azure Active Directory.

Developer Portal

Enter the credentials of one of the users in your Azure Active Directory, and click Sign in.

Sign in

You may be prompted with a registration form if any additional information is required. Complete the registration form and click Sign up.

Registration

Your user is now logged into the developer portal for your API Management service instance.

Registration Complete