How to authorize developer accounts using OAuth 2.0 in Azure API Management

Many APIs support OAuth 2.0 to secure the API and ensure that only valid users have access, and they can only access resources to which they're entitled. In order to use Azure API Management's interactive Developer Console with such APIs, the service allows you to configure your service instance to work with your OAuth 2.0 enabled API.

Prerequisites

This guide shows you how to configure your API Management service instance to use OAuth 2.0 authorization for developer accounts, but does not show you how to configure an OAuth 2.0 provider. The configuration for each OAuth 2.0 provider is different, although the steps are similar, and the required pieces of information used in configuring OAuth 2.0 in your API Management service instance are the same. This topic shows examples using Azure Active Directory as an OAuth 2.0 provider.

Note

For more information on configuring OAuth 2.0 using Azure Active Directory, see the WebApp-GraphAPI-DotNet sample.

Configure an OAuth 2.0 authorization server in API Management

To get started, click Publisher portal in the Azure Portal for your API Management service.

Publisher portal

Note

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, click OAuth 2.0, and then click Add authorization server.

OAuth 2.0

After clicking Add authorization server, the new authorization server form is displayed.

New server

Enter a name and an optional description in the Name and Description fields.

Note

These fields are used to identify the OAuth 2.0 authorization server within the current API Management service instance and their values do not come from the OAuth 2.0 server.

Enter the Client registration page URL. This page is where users can create and manage their accounts, and varies depending on the OAuth 2.0 provider used. The Client registration page URL points to the page that users can use to create and configure their own accounts for OAuth 2.0 providers that support user management of accounts. Some organizations do not configure or use this functionality even if the OAuth 2.0 provider supports it. If your OAuth 2.0 provider does not have user management of accounts configured, enter a placeholder URL here such as the URL of your company, or a URL such as https://placeholder.contoso.com.

The next section of the form contains the Authorization code grant types, Authorization endpoint URL, and Authorization request method settings.

New server

Specify the Authorization code grant types by checking the desired types. Authorization code is specified by default.

Enter the Authorization endpoint URL. For Azure Active Directory, this URL will be similar to the following URL, where <client_id> is replaced with the client id that identifies your application to the OAuth 2.0 server.

https://login.windows.net/<client_id>/oauth2/authorize

The Authorization request method specifies how the authorization request is sent to the OAuth 2.0 server. By default GET is selected.

The next section is where the Token endpoint URL, Client authentication methods, Access token sending method, and Default scope are specified.

New server

For an Azure Active Directory OAuth 2.0 server, the Token endpoint URL will have the following format, where <APPID> has the format of yourapp.onmicrosoft.com.

https://login.windows.net/<APPID>/oauth2/token

The default setting for Client authentication methods is Basic, and Access token sending method is Authorization header. These values are configured on this section of the form, along with the Default scope.

The Client credentials section contains the Client ID and Client secret, which are obtained during the creation and configuration process of your OAuth 2.0 server. Once the Client ID and Client secret are specified, the redirect_uri for the authorization code is generated. This URI is used to configure the reply URL in your OAuth 2.0 server configuration.

New server

If Authorization code grant types is set to Resource owner password, the Resource owner password credentials section is used to specify those credentials; otherwise you can leave it blank.

New server

Once the form is complete, click Save to save the API Management OAuth 2.0 authorization server configuration. Once the server configuration is saved, you can configure APIs to use this configuration, as shown in the next section.

Configure an API to use OAuth 2.0 user authorization

Click APIs from the API Management menu on the left, click the name of the desired API, click Security, and then check the box for OAuth 2.0.

User authorization

Select the desired Authorization server from the drop-down list, and click Save.

User authorization

Test the OAuth 2.0 user authorization in the Developer Portal

Once you have configured your OAuth 2.0 authorization server and configured your API to use that server, you can test it by going to the Developer Portal and calling an API. Click Developer portal in the top right menu.

Developer portal

Click APIs in the top menu and select Echo API.

Echo API

Note

If you have only one API configured or visible to your account, then clicking APIs takes you directly to the operations for that API.

Select the GET Resource operation, click Open Console, and then select Authorization code from the drop-down.

Open console

When Authorization code is selected, a pop-up window is displayed with the sign-in form of the OAuth 2.0 provider. In this example the sign-in form is provided by Azure Active Directory.

Note

If you have pop-ups disabled you will be prompted to enable them by the browser. After you enable them, select Authorization code again and the sign-in form will be displayed.

Sign in

Once you have signed in, the Request headers are populated with an Authorization : Bearer header that authorizes the request.

Request header token

At this point you can configure the desired values for the remaining parameters, and submit the request.

Next steps

For more information about using OAuth 2.0 and API Management, see the following video and accompanying article.