You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Protect API in API Management using OAuth 2.0 and Microsoft Entra ID
2
+
title: Protect API in API Management - OAuth 2.0 and Microsoft Entra ID
3
3
titleSuffix: Azure API Management
4
4
description: Learn how to secure user access to an API in Azure API Management with OAuth 2.0 user authorization and Microsoft Entra ID.
5
5
services: api-management
6
6
author: dlepow
7
7
ms.service: azure-api-management
8
-
ms.topic: article
9
-
ms.date: 04/27/2022
8
+
ms.topic: how-to
9
+
ms.date: 02/20/2025
10
10
ms.author: danlep
11
11
---
12
12
@@ -16,85 +16,93 @@ ms.author: danlep
16
16
17
17
In this article, you'll learn high level steps to configure your [Azure API Management](api-management-key-concepts.md) instance to protect an API, by using the [OAuth 2.0 protocol with Microsoft Entra ID](../active-directory/develop/active-directory-v2-protocols.md).
18
18
19
-
For a conceptual overview of API authorization, see [Authentication and authorization to APIs in API Management](authentication-authorization-overview.md).
19
+
For a conceptual overview of API authorization options in API Management, see [Authentication and authorization to APIs in API Management](authentication-authorization-overview.md).
20
20
21
21
## Prerequisites
22
22
23
23
Prior to following the steps in this article, you must have:
24
24
25
25
- An API Management instance
26
26
- A published API using the API Management instance
27
-
- A Microsoft Entra tenant
27
+
- A Microsoft Entra tenant where you have permissions to create an app regisgtration
28
28
29
29
## Overview
30
30
31
31
Follow these steps to protect an API in API Management, using OAuth 2.0 authorization with Microsoft Entra ID.
32
32
33
-
1. Register an application (called *backend-app* in this article) in Microsoft Entra ID to protect access to the API.
34
-
35
-
To access the API, users or applications will acquire and present a valid OAuth token granting access to this app with each API request.
36
-
37
-
1. Configure the [validate-jwt](validate-jwt-policy.md) policy in API Management to validate the OAuth token presented in each incoming API request. Valid requests can be passed to the API.
38
-
39
-
Details about OAuth authorization flows and how to generate the required OAuth tokens are beyond the scope of this article. Typically, a separate client app is used to acquire tokens from Microsoft Entra ID that authorize access to the API. For links to more information, see the [Next steps](#next-steps).
1. Register an application (called *backend-app* in this article) in Microsoft Entra ID to represent the API.
34
+
1. Register an application to represent the client app that calls the API and that obtains tokens from Microsoft Entra ID. This step is not covered in this article because the configuration is dependent on the
35
+
1. Configure the [validate-azure-ad-token](validate-azure-ad-token-policy.md) policy in API Management to validate the OAuth token presented in each incoming API request. Requests with valid tokens are passed to the backend API. Depending on your scenario, your backend API could independently validate the token.
42
36
43
37
## Register an application in Microsoft Entra ID to represent the API
44
38
45
-
Using the Azure portal, protect an API with Microsoft Entra ID by first registering an application that represents the API.
39
+
Using the Azure portal, first register an application that represents the API.
46
40
47
-
For details about app registration, see [Quickstart: Configure an application to expose a web API](../active-directory/develop/quickstart-configure-app-expose-web-apis.md).
41
+
For details about app registration, see [Quickstart: Configure an application to expose a web API](/entra/identity-platform/quickstart-configure-app-expose-web-apis).
48
42
49
43
1. In the [Azure portal](https://portal.azure.com), search for and select **App registrations**.
50
44
51
-
1. Select **New registration**.
45
+
1. Select **+ New registration**.
52
46
53
-
1.When the **Register an application page**appears, enter your application's registration information:
47
+
1.On the **Register an application**page, enter your application's registration information:
54
48
55
-
- In the **Name** section, enter a meaningful application name that will be displayed to users of the app, such as *backend-app*.
49
+
- In the **Name** section, enter a meaningful application name that is displayed to users of the app, such as *backend-app*.
56
50
- In the **Supported account types** section, select an option that suits your scenario.
57
51
58
-
1. Leave the [**Redirect URI**](../active-directory/develop/reply-url.md) section empty.
52
+
1. Leave the [**Redirect URI**](/entra/identity-platform/reply-url) section empty.
59
53
60
54
1. Select **Register** to create the application.
61
55
62
56
1. On the app **Overview** page, find the **Application (client) ID** value and record it for later.
63
57
64
-
1. Under the **Manage** section of the side menu, select **Expose an API** and set the **Application ID URI** with the default value. If you're developing a separate client app to obtain OAuth 2.0 tokens for access to the backend-app, record this value for later.
58
+
1. Under the **Manage** section of the side menu, select **Expose an API**. **Add**the **Application ID URI** with the default value. Record this value for later.
65
59
66
-
1. Select the **Add a scope** button to display the **Add a scope** page:
67
-
1. Enter a new **Scope name**, **Admin consent display name**, and **Admin consent description**.
60
+
1. On the **Expose an API** page, select **+ Add a scope** to display the **Add a scope** page.
61
+
1. Enter a new **Scope name** for a scope that's supported by the API (for example, **Files.Read**).
62
+
1. In **Who can consent?**, make a selection for your scenario, such as **Admins and users**. Select **Admins only** for higher privileged environments.
63
+
1. Enter **Admin consent display name** and **Admin consent description**.
68
64
1. Make sure the **Enabled** scope state is selected.
65
+
1. Select **Add scope** to create the scope.
69
66
70
-
1. Select the **Add scope** button to create the scope.
71
-
72
-
1. Repeat the previous two steps to add all scopes supported by your API.
67
+
1. Repeat the previous step to add all scopes supported by your API.
73
68
74
69
1. Once the scopes are created, make a note of them for use later.
75
70
76
-
## Configure a JWT validation policy to pre-authorize requests
71
+
72
+
## Register an application in Microsoft Entra ID to represent the client app
73
+
74
+
While not shown in this article, in most scenarios you would register a second application in Microsoft Entra ID (*client-app*) to represent a client application that calls the API. The app registration must have permissions to call the backend app. Details about app registration are specific to your scenario.
75
+
76
+
Configure the client application to use Microsoft Entra ID to request valid OAuth tokens granting access to the API. Present the token in the request to API Management (for example, in an Authorization header).
77
+
78
+
Development of a client application that uses Microsoft Entra ID to request valid OAuth tokens is beyond the scope of this article and specific to your scenario. For examples and guidance, see [Microsoft identity platform code samples](entra/identity-platform/sample-v2-code).
79
+
80
+
81
+
## Configure a token validation policy to preauthorize requests
1. A user or application acquires a token from Microsoft Entra ID with permissions that grant access to the backend-app. If you use the v2 endpoint, ensure that the accessTokenAcceptedVersion property is set to 2 in the application manifest of the back end app and any client app that you configure.
88
+
THe following steps make up a typical authorization workflow for an API in API Management that uses OAuth 2.0 authorization with Microsoft Entra ID.
89
+
90
+
1. A user or application acquires a token from Microsoft Entra ID with permissions that grant access to the backend-app. If you use the v2 endpoint, ensure that the accessTokenAcceptedVersion property is set to 2 in the application manifest of the backend-app and any client app that you configure.
83
91
84
92
1. The token is added in the Authorization header of API requests to API Management.
85
93
86
-
1. API Management validates the token by using the `validate-jwt` policy.
94
+
1. API Management validates the token by using the `validate-azure-ad-token` policy.
87
95
88
96
* If a request doesn't have a valid token, API Management blocks it.
89
97
90
98
* If a request is accompanied by a valid token, the gateway can forward the request to the API.
91
99
92
-
## Next steps
100
+
## Related content
93
101
94
102
* To learn more about how to build an application and implement OAuth 2.0, see [Microsoft Entra code samples](../active-directory/develop/sample-v2-code.md).
95
103
96
104
* For an end-to-end example of configuring OAuth 2.0 user authorization in the API Management developer portal, see [How to authorize test console of developer portal by configuring OAuth 2.0 user authorization](api-management-howto-oauth2.md).
97
105
98
106
- Learn more about [Microsoft Entra ID and OAuth2.0](../active-directory/develop/authentication-vs-authorization.md).
99
107
100
-
-For other ways to secure your back-end service, see [Mutual certificate authentication](./api-management-howto-mutual-certificates.md).
108
+
-Learn more about [authentication and authorization options](authentication-authorization-overview.md) in API Management.
0 commit comments