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
|thumbprint|The thumbprint for the client certificate.|Either `thumbprint` or `certificate-id` must be present.|N/A|
96
+
|certificate-id|The certificate resource name.|Either `thumbprint` or `certificate-id` must be present.|N/A|
97
+
98
+
### Usage
99
+
This policy can be used in the following policy [sections](https://azure.microsoft.com/documentation/articles/api-management-howto-policies/#sections) and [scopes](https://azure.microsoft.com/documentation/articles/api-management-howto-policies/#scopes).
100
+
101
+
-**Policy sections:** inbound
102
+
103
+
-**Policy scopes:** all scopes
104
+
105
+
## <aname="ManagedIdentity"></a> Authenticate with managed identity
106
+
Use the `authentication-managed-identity` policy to authenticate with a backend service using the managed identity of the API Management service. This policy essentially uses the managed identity to obtain an access token from Azure Active Directory for accessing the specified resource. After successfully obtaining the token, the policy will set the value of the token in the `Authorization` header using the `Bearer` scheme.
|thumbprint|The thumbprint for the client certificate.|Either `thumbprint` or `certificate-id` must be present.|N/A|
96
-
|certificate-id|The certificate resource name.|Either `thumbprint` or `certificate-id` must be present.|N/A|
97
-
98
-
### Usage
99
-
This policy can be used in the following policy [sections](https://azure.microsoft.com/documentation/articles/api-management-howto-policies/#sections) and [scopes](https://azure.microsoft.com/documentation/articles/api-management-howto-policies/#scopes).
100
-
101
-
-**Policy sections:** inbound
102
-
103
-
-**Policy scopes:** all scopes
104
-
105
-
## <aname="ManagedIdentity"></a> Authenticate with managed identity
106
-
Use the `authentication-managed-identity` policy to authenticate with a backend service using the managed identity of the API Management service. This policy effectively uses the managed identity to obtain an access token from Azure Active Directory for accessing the specified resource.
|resource|String. The App ID URI of the target web API (secured resource) in Azure Active Directory.|Yes|N/A|
131
-
|output-token-variable-name|String. Name of the context variable that will receive token value as an object type `string`.|No|N/A|
132
-
|ignore-error|Boolean. If set to `true`, the policy pipeline will continue to execute even if an access token is not obtained.|No|false|
133
-
134
-
### Usage
135
-
This policy can be used in the following policy [sections](https://azure.microsoft.com/documentation/articles/api-management-howto-policies/#sections) and [scopes](https://azure.microsoft.com/documentation/articles/api-management-howto-policies/#scopes).
|resource|String. The App ID URI of the target web API (secured resource) in Azure Active Directory.|Yes|N/A|
140
+
|output-token-variable-name|String. Name of the context variable that will receive token value as an object type `string`.|No|N/A|
141
+
|ignore-error|Boolean. If set to `true`, the policy pipeline will continue to execute even if an access token is not obtained.|No|false|
142
+
143
+
### Usage
144
+
This policy can be used in the following policy [sections](https://azure.microsoft.com/documentation/articles/api-management-howto-policies/#sections) and [scopes](https://azure.microsoft.com/documentation/articles/api-management-howto-policies/#scopes).
Copy file name to clipboardExpand all lines: articles/api-management/api-management-features.md
+3Lines changed: 3 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,6 +18,9 @@ ms.author: apimpm
18
18
19
19
# Feature-based comparison of the Azure API Management tiers
20
20
21
+
>[!IMPORTANT]
22
+
> Please note the Developer tier is for non-production use cases and evaluations. It does not offer SLA.
23
+
21
24
Each API Management [pricing tier](https://aka.ms/apimpricing) offers a distinct set of features and per unit [capacity](api-management-capacity.md). The following table summarizes the key features available in each of the tiers. Some features might work differently or have different capabilities depending on the tier. In such cases the differences are called out in the documentation articles describing these individual features.
Copy file name to clipboardExpand all lines: articles/api-management/api-management-howto-protect-backend-with-aad.md
+49-34Lines changed: 49 additions & 34 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -33,7 +33,7 @@ Here is a quick overview of the steps:
33
33
1. Register an application (backend-app) in Azure AD to represent the API.
34
34
2. Register another application (client-app) in Azure AD to represent a client application that needs to call the API.
35
35
3. In Azure AD, grant permissions to allow the client-app to call the backend-app.
36
-
4. Configure the Developer Console to use OAuth 2.0 user authorization.
36
+
4. Configure the Developer Console to call the API using OAuth 2.0 user authorization.
37
37
5. Add the **validate-jwt** policy to validate the OAuth token for every incoming request.
38
38
39
39
## Register an application in Azure AD to represent the API
@@ -42,23 +42,29 @@ To protect an API with Azure AD, the first step is to register an application in
42
42
43
43
1. Navigate to the [Azure portal - App registrations](https://go.microsoft.com/fwlink/?linkid=2083908) page.
44
44
45
-
2. Select **New registration**.
45
+
1. Select **New registration**.
46
46
47
47
1. When the **Register an application page** appears, enter your application's registration information:
48
48
- In the **Name** section, enter a meaningful application name that will be displayed to users of the app, for example `backend-app`.
49
-
- In the **Supported account types** section, select **Accounts in any organizational directory**.
49
+
- In the **Supported account types** section, select an option that suits your scenario.
50
50
51
-
1. Leave the **Redirect URI** section empty for now.
51
+
1. Leave the **Redirect URI** section empty.
52
52
53
53
1. Select **Register** to create the application.
54
54
55
55
1. On the app **Overview** page, find the **Application (client) ID** value and record it for later.
56
56
57
57
When the application is created, make a note of the **Application ID**, for use in a subsequent step.
58
58
59
+
1. Select **Expose an API** and click on **Save and continue** to create an Application ID URI.
60
+
61
+
1. In the **Add a scope** page, create a new scope supported by the API. (e.g., Read) then click on *Add scope* to create the scope. Repeat this step to add all scopes supported by your API.
62
+
63
+
1. When the scope is created, make a note of it, for use in a subsequent step.
64
+
59
65
## Register another application in Azure AD to represent a client application
60
66
61
-
Every client application that calls the API needs to be registered as an application in Azure AD as well. For this example, the sample client application is the Developer Console in the API Management developer portal. Here's how to register another application in Azure AD to represent the Developer Console.
67
+
Every client application that calls the API needs to be registered as an application in Azure AD as well. In this example, the client application is the Developer Console in the API Management developer portal. Here's how to register another application in Azure AD to represent the Developer Console.
62
68
63
69
1. Navigate to the [Azure portal - App registrations](https://go.microsoft.com/fwlink/?linkid=2083908) page.
64
70
@@ -78,28 +84,25 @@ Now, create a client secret for this application, for use in a subsequent step.
78
84
79
85
1. From the list of pages for your client app, select **Certificates & secrets**, and select **New client secret**.
80
86
81
-
2. Under **Add a client secret**, provide a **Description**. Choose when the key should expire, and select **Add**.
87
+
1. Under **Add a client secret**, provide a **Description**. Choose when the key should expire, and select **Add**.
82
88
83
-
Make a note of the key value.
89
+
When the secret is created, make a note of the key value, for use in a subsequent step.
84
90
85
91
## Grant permissions in Azure AD
86
92
87
93
Now that you have registered two applications to represent the API and the Developer Console, you need to grant permissions to allow the client-app to call the backend-app.
88
94
89
95
1. Navigate to **App registrations**.
90
96
91
-
2. Select `client-app`, and in the list of pages for the app go to **API permissions**.
92
-
93
-
3. Select **Add a Permission**.
97
+
1. Select `client-app`, and in the list of pages for the app go to **API permissions**.
94
98
95
-
4. Under**Select an API**, find and select `backend-app`.
99
+
1. Select**Add a Permission**.
96
100
97
-
5. Under **Delegated Permissions**, select the appropriate permissions to`backend-app`.
101
+
1. Under **Select an API**, find and select`backend-app`.
98
102
99
-
6. Select**Add permissions**
103
+
1. Under**Delegated Permissions**, select the appropriate permissions to `backend-app` then click on **Add permissions**.
100
104
101
-
> [!NOTE]
102
-
> If **Azure Active Directory** is not listed under permissions to other applications, select **Add** to add it from the list.
105
+
1. Optionally, on the **API permissions** page, click on **Grant admin consent for <your-tenant-name>** in the bottom of the page to grant consent on behalf of all users in this directory.
103
106
104
107
## Enable OAuth 2.0 user authorization in the Developer Console
105
108
@@ -109,41 +112,53 @@ In this example, the Developer Console is the client-app. The following steps de
109
112
110
113
1. In Azure portal, browse to your API Management instance.
111
114
112
-
2. Select **OAuth 2.0** > **Add**.
115
+
1. Select **OAuth 2.0** > **Add**.
116
+
117
+
1. Provide a **Display name** and **Description**.
118
+
119
+
1. For the **Client registration page URL**, enter a placeholder value, such as `http://localhost`. The **Client registration page URL** points to a page that users can use to create and configure their own accounts for OAuth 2.0 providers that support this. In this example, users do not create and configure their own accounts, so you use a placeholder instead.
120
+
121
+
1. For **Authorization grant types**, select **Authorization code**.
122
+
123
+
1. Specify the **Authorization endpoint URL** and **Token endpoint URL**. Retrieve these values from the **Endpoints** page in your Azure AD tenant. Browse to the **App registrations** page again, and select **Endpoints**.
113
124
114
-
3. Provide a **Display name** and **Description**.
115
125
116
-
4. For the **Client registration page URL**, enter a placeholder value, such as `http://localhost`. 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 this. In this example, users do not create and configure their own accounts, so you use a placeholder instead.
126
+
1. Copy the **OAuth 2.0 Authorization Endpoint**, and paste it into the **Authorization endpoint URL**text box. Select **POST** under Authorization request method.
117
127
118
-
5. For **Authorization grant types**, select **Authorization code**.
128
+
1. Copy the **OAuth 2.0 Token Endpoint**, and paste it into the **Token endpoint URL** text box.
119
129
120
-
6. Specify the **Authorization endpoint URL** and **Token endpoint URL**. Retrieve these values from the **Endpoints** page in your Azure AD tenant. Browse to the **App registrations** page again, and select **Endpoints**.
130
+
<<<<<<< HEAD
131
+
>[!IMPORTANT]
132
+
> You can use either **v1** or **v2** endpoints. However, depending on which version you choose, the below step will be different. We recommend using v2 endpoints.
121
133
134
+
1. If you use **v1** endpoints, add a body parameter named **resource**. For the value of this parameter, use **Application ID** of the back-end app.
135
+
=======
122
136
7. Copy the **OAuth 2.0 Authorization Endpoint**, and paste it into the **Authorization endpoint URL** text box.
137
+
>>>>>>> 427b8702cffca2ee2c9bdaa462b15d654242232d
123
138
124
-
8. Copy the **OAuth 2.0 Token Endpoint**, and paste it into the **Token endpoint URL** text box. In addition to pasting in the token endpoint, add a body parameter named **resource**. For the value of this parameter, use the **Application ID**for the back-end app.
139
+
1. If you use **v2** endpoints, use the scope you created for the backend-app in the **Default scope**field.
125
140
126
-
9. Next, specify the client credentials. These are the credentials for the client-app.
141
+
1. Next, specify the client credentials. These are the credentials for the client-app.
127
142
128
-
10. For **Client ID**, use the **Application ID**for the client-app.
143
+
1. For **Client ID**, use the **Application ID**of the client-app.
129
144
130
-
11. For **Client secret**, use the key you created for the client-app earlier.
145
+
1. For **Client secret**, use the key you created for the client-app earlier.
131
146
132
-
12. Immediately following the client secret is the **redirect_url** for the authorization code grant type. Make a note of this URL.
147
+
1. Immediately following the client secret is the **redirect_url** for the authorization code grant type. Make a note of this URL.
133
148
134
-
13. Select **Create**.
149
+
1. Select **Create**.
135
150
136
-
14. Go back to the **Settings** page of your client-app.
151
+
1. Go back to the **Settings** page of your client-app.
137
152
138
-
15. Select **Reply URLs**, and paste the **redirect_url** in the first row. In this example, you replaced `https://localhost` with the URL in the first row.
153
+
1. Select **Reply URLs**, and paste the **redirect_url** in the first row. In this example, you replaced `https://localhost` with the URL in the first row.
139
154
140
155
Now that you have configured an OAuth 2.0 authorization server, the Developer Console can obtain access tokens from Azure AD.
141
156
142
157
The next step is to enable OAuth 2.0 user authorization for your API. This enables the Developer Console to know that it needs to obtain an access token on behalf of the user, before making calls to your API.
143
158
144
159
1. Browse to your API Management instance, and go to **APIs**.
145
160
146
-
2. Select the API you want to protect. In this example, you use the `Echo API`.
161
+
2. Select the API you want to protect. For example, you can use the `Echo API`.
147
162
148
163
3. Go to **Settings**.
149
164
@@ -156,9 +171,9 @@ The next step is to enable OAuth 2.0 user authorization for your API. This enabl
156
171
> [!NOTE]
157
172
> This section does not apply to the **Consumption** tier, which does not support the developer portal.
158
173
159
-
Now that the OAuth 2.0 user authorization is enabled on the `Echo API`, the Developer Console obtains an access token on behalf of the user, before calling the API.
174
+
Now that the OAuth 2.0 user authorization is enabled on your API, the Developer Console will obtain an access token on behalf of the user, before calling the API.
160
175
161
-
1. Browse to any operation under the `Echo API` in the developer portal, and select **Try it**. This brings you to the Developer Console.
176
+
1. Browse to any operation under the API in the developer portal, and select **Try it**. This brings you to the Developer Console.
162
177
163
178
2. Note a new item in the **Authorization** section, corresponding to the authorization server you just added.
164
179
@@ -175,11 +190,11 @@ Now that the OAuth 2.0 user authorization is enabled on the `Echo API`, the Deve
175
190
176
191
## Configure a JWT validation policy to pre-authorize requests
177
192
178
-
At this point, when a user tries to make a call from the Developer Console, the user is prompted to sign in. The Developer Console obtains an access token on behalf of the user.
193
+
At this point, when a user tries to make a call from the Developer Console, the user is prompted to sign in. The Developer Console obtains an access token on behalf of the user, and includes the token in the request made to the API.
179
194
180
-
But what if someone calls your API without a token or with an invalid token? For example, you can still call the API even if you delete the `Authorization` header. The reason is that API Management does not validate the access token at this point. It simply passes the `Authorization` header to the back-end API.
195
+
However, what if someone calls your API without a token or with an invalid token? For example, try to call the API without the `Authorization` header, the call will still go through. The reason is that API Management does not validate the access token at this point. It simply passes the `Authorization` header to the back-end API.
181
196
182
-
You can use the [Validate JWT](api-management-access-restriction-policies.md#ValidateJWT) policy to pre-authorize requests in API Management, by validating the access tokens of each incoming request. If a request does not have a valid token, API Management blocks it. For example, you can add the following policy to the `<inbound>` policy section of the `Echo API`. It checks the audience claim in an access token, and returns an error message if the token is not valid. For information on how to configure policies, see [Set or edit policies](set-edit-policies.md).
197
+
You can use the [Validate JWT](api-management-access-restriction-policies.md#ValidateJWT) policy to pre-authorize requests in API Management, by validating the access tokens of each incoming request. If a request does not have a valid token, API Management blocks it. For example, add the following policy to the `<inbound>` policy section of the `Echo API`. It checks the audience claim in an access token, and returns an error message if the token is not valid. For information on how to configure policies, see [Set or edit policies](set-edit-policies.md).
183
198
184
199
```xml
185
200
<validate-jwtheader-name="Authorization"failed-validation-httpcode="401"failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
0 commit comments