Integrate with Azure API Management

Azure's API Management service allows you to create new APIs or import existing API definitions and publish them for use by the approved audiences. Auth0 makes authorizing users of your API (using OAuth 2.0 standards) easy.

In this tutorial, we'll show you how to use Auth0 to authenticate users trying to access an API managed by Azure API Management. More specifically, we will:

  1. Create an Auth0 API and Machine to Machine Application.

  2. Create a Connection to store your users.

  3. Create a user to test your integration when you've finished setting it up.

  4. Create an Azure API Management instance on the Azure Portal.

  5. Import a basic calculator API (this sample API is provided by Microsoft).

  6. Configure an OAuth 2.0 Server for the API Management instance.

  7. Set Auth0 as the OAuth 2.0 Server handling authentication requests to the API

  8. Test the Auth0-Azure API integration

Whenever a user attempts to make a call to the Basic Calculator API, they are asked to provide credentials to an Auth0-provided login screen. Only by providing valid credentials is the user allowed to make a call to the API.

Step 1: Create an API and Machine to Machine Application

An API is an entity that represents an external resource that's capable of accepting and responding to requests made by applications. You'll need to create an Auth0 API using the Management Dashboard to represent the API managed by Azure's API Management Service that you want secured by Auth0.

You'll also need a Machine to Machine Application, which represents your application and allows use of Auth0 for authentication. When you create an API, Auth0 automatically creates an associated Machine to Machine Application by default.

To learn more, read Read Machine to Machine Application.

To begin, you'll need to log in to the Auth0 Dashboard, navigate to Dashboard > Applications > APIs, and select Create API.

Dashboard - API - Create API

Set the following parameters to create your new API:

Parameter Description
Name A descriptive name for your API. In this example, we'll use Basic Calculator
Identifier A logical and unique identifier for your API. We recommend using a URL, but it doesn't have to be a publicly-available URL since Auth0 doesn't call your API. You cannot modify this value at a later point. We'll use basic-calculator.
Signing Algorithm The method used to sign the tokens issued by Auth0. Choose from HS256 and RS256 (we'll use the latter for this example). If you choose RS256, Auth0 signs your tokens with your private key. To learn more, see Signing Algorithms.

When complete, click Create.

Dashboard - Create API - Basic Calculator - Azure API Management Integration

When your API is ready, you'll be shown the Quick Start page for the API. Switch over to the Machine to Machine Applications view. You'll see that Auth0 has also created and enabled a Machine to Machine Application for use with your API.

Dashboard - Create API - View M2M Applications - Basic Calculator - Azure API Management Integration

Step 2: Create a Connection

If you already have a set of users, you may import them or create a custom database connection.

Navigate to Auth0 Dashboard > Authentication > Database, and click Create DB Connection.

Dashboard - Authentication - Database - Database Connections List

The only thing you'll need to provide at this time is a descriptive Name for your connection. We suggest choosing a name that reflects the source of users (such as Facebook for a Connection that contains users using their Facebook credentials or site-sign-ups for a database connection where users sign up on your site).

Dashboard - Authentication - Database - New DB Connection

Click Create to proceed.

Enable the Connection for Your Application

Once Auth0 has created your Connection, you'll be redirected to your Connection's Settings page. Switch over to the Applications view, where you'll see a full list of all the Applications you have with this account. You'll need to enable the Connection for use with the Machine to Machine Application that you're using with your API.

Step 3: Create a User

Finally, we'll create a user that we use later on to test the integration.

Go to Auth0 Dashboard > User Management > Users, and select Create User.

Dashboard - User Management - Users Page

Provide an email and password for your new user. Be sure to indicate that this user should use BasicCalculator in the Connection field.

Set Connection to the connection you created earlier (which, if you're following along with our example, is BasicCalculator).

Dashboard - Manage User - User - Create user for testing

Click Save to proceed.

At this point, you've set up Auth0 for use as an OAuth 2.0 authorization server. You will now configure the Azure API Management Service and import an API for use with the service.

Step 4: Create Your API Management Instance

You'll need an account with access to Microsoft's Azure Portal for the rest of this tutorial.

To create a new API management service, click Create a resource in the left-hand navigation bar. Once redirected, click Web > API Management.

You'll be asked to provide the following configuration variables:

Parameter Description
Name The name for your service (which will also be used to create the URL you need to access the service)
Subscription The Azure subscription plan with which you'll use with the service
Resource group The collection of resources sharing a lifecycle, permissions, and policies. You can use an existing resource group or you can create a new one (you'll need to provide a name for the group if you create a new one)
Location Choose the location that services your API instance
Organization name The name of your organization
Administrator email The email address of the person who will be administering this instance
Pricing tier The pricing tier you want, which determines the number of calls you can make to your API, as well as the maximum amount of data transfer allowed. You must opt for the Developer plan or higher; the Consumption plan does not offer sufficient functionality for this integration to work.

You can also choose to Enable Application Insights. If you do, select the Application Insights instance you would like to use.

Click Create to begin provisioning your service.

Step 5: Import Your API

For this tutorial, we will be importing and using the Calculator API provided by Microsoft. You can, however, create your own API instead of using the Calculator API.

For detailed instructions, see Import and Publish Your First API in Microsoft documentation.

When done, click Create to import your API. You'll be redirected to the summary page for your API when it's fully imported.

Step 6: Configure Your OAuth 2.0 Authorization Server

To use Auth0 to secure your API, you'll need to register Auth0 as an OAuth 2.0 Authorization Server. You can do so using the Azure Publisher Portal.

Find the Security area of your API Management service instance's near left navigation bar, and click OAuth 2.0.

Click on Add. You'll see the Add OAuth2 service configuration screen that lets you provide details about your Auth0 tenant.

For the purposes of this example, we'll use the Authorization Code grant type, but you're free to use whichever grant type is most appropriate for your use case. Azure currently supports the following grant types:

  • Authorization Code

  • Implicit

  • Resource Owner Password

  • Client Credentials

Set the following parameters:

Parameter Description
Display name A descriptive name for your authorization server, such as Auth0
Id The identifying name for this Azure resource -- this field should auto-populate based on the display name you provide
Description A description for your authorization server, such as Auth0 API Authentication
Client registration page URL The page where users can create or manage their accounts; for the purposes of this example, we'll use https://placeholder.contoso.com as the placeholder
Authorization code grant types The grant type used for authorization. Select authorization code
Authorization endpoint URL The URL Azure uses to make the authorization request, https://YOUR_DOMAIN/authorize
Authorization request method The HTTP method used by Azure to make the authorization request. By default, this is GET
Token endpoint URL The endpoint used to exchange authorization grants for Access Tokens; Auth0's can be reached at https://YOUR_DOMAIN/oauth/token
Client authentication methods Method used to authenticate the application; Auth0's is BASIC
Access Token sending method The location of the Access Token in the sending method (typically the Authorization header)
Default scope Specify a default scope (if necessary)

Because we're using the authorization code grant, we'll need to provide the client ID and client secret for the machine-to-machine application we previously registered. You can find both values in the Application Settings.

Once you've provided both the client ID and client secret, you'll see an auto-generated redirect URI. Copy this URL, you'll need it for your Auth0 Application Settings page in the Allowed Callback URLs section.

If you're using the resource owner password flow, you'll need to provide the resource owner username and resource owner password instead of the client ID and secret.

When complete, click Create to persist your changes.

Set the Allowed Callback URL

You'll need to provide the redirect URI that was auto-generated during the OAuth 2.0 authorization server setup process to Auth0. Navigate to Auth0 Dashboard > Applications > Applications. Select your Application, and select the Settings view. Paste the URL into the Allowed Callback URLs field.

Click Save.

Dashboard - Applications - Set callback URL - Basic Calculator - Integrations Azure API Management

Step 7: Authorize Auth0 for Use with Your API

Before you can use Auth0 to secure your API, you'll need to set your API to use Auth0.

In the near-left navigation column, click APIs. Select the Basic Calculator API; this redirects you to the Design tab.

Click over to the Settings tab.

Scroll to the Security section, and under User Authorization, select OAuth 2.0. In the Authorization Server field that appears, select the server you configured in the previous step.

Click Save.

Step 8: Test Your Integration

While logged in to the Azure Portal, open up your instance of the API Management Service. Click Developer Console to launch the developer-facing side of your APIs.

Go to APIs > Basic Calculator (or the API you've created for this tutorial). This opens up to the page where you can make a GET call that allows you to add two integers.

Click Try It. This will bring up the page where you can provide the parameters for your call.

Scroll down to the Authorization section. Next to the Auth0 field, select Authorization Code.

At this point, you'll see the Auth0 login widget in a popup window (if you don't, disable your popup blocker). Provide the credentials for the Auth0 user you created earlier in the tutorial, and sign in.

If you were able to successfully sign in, you'll see a message appear with the expiration date of the Access Token you need to call the API.

Scroll to the bottom, and click Send to send your request. If successful, you'll see a message containing the HTTP 200 response at the bottom of the page.

Configure a JWT validation policy for Access Tokens

In the previous step, the user is prompted to sign in when they try to make a call from the Developer Console. The Developer Console attempts to obtain an Access Token on behalf of the user to be included in the API request. All Access Tokens will be passed to the API via the Authorization header.

If you want to validate the Access Token included with each request, you can do so by using the Validate JWT policy. Please refer to Microsoft's documentation on setting an API Management policy.