Skip to content

Commit 4ddb11b

Browse files
GitHubber17GitHubber17
authored
Merge pull request #84087 from miaojiang/2019-08-01-minor
Changes based on supportability items
2 parents 802f84b + b620aa8 commit 4ddb11b

File tree

4 files changed

+117
-90
lines changed

4 files changed

+117
-90
lines changed

‎articles/api-management/api-management-authentication-policies.md

Lines changed: 64 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -78,64 +78,73 @@ In this example client certificate is identified by its thumbprint.
7878
<authentication-certificate thumbprint="CA06F56B258B7A0D4F2B05470939478651151984" />
7979
```
8080
In this example client certificate is identified by resource name.
81-
```xml
82-
<authentication-certificate certificate-id="544fe9ddf3b8f30fb490d90f" />
81+
```xml
82+
<authentication-certificate certificate-id="544fe9ddf3b8f30fb490d90f" />
83+
```
84+
85+
### Elements
86+
87+
|Name|Description|Required|
88+
|----------|-----------------|--------------|
89+
|authentication-certificate|Root element.|Yes|
90+
91+
### Attributes
92+
93+
|Name|Description|Required|Default|
94+
|----------|-----------------|--------------|-------------|
95+
|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+
## <a name="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.
107+
108+
### Policy statement
109+
110+
```xml
111+
<authentication-managed-identity resource="resource" output-token-variable-name="token-variable" ignore-error="true|false"/>
112+
```
113+
114+
### Example
115+
#### Use managed identity to authenticate with a backend service
116+
```xml
117+
<authentication-managed-identity resource="https://graph.windows.net"/>
83118
```
84-
85-
### Elements
86-
87-
|Name|Description|Required|
88-
|----------|-----------------|--------------|
89-
|authentication-certificate|Root element.|Yes|
90-
91-
### Attributes
92-
93-
|Name|Description|Required|Default|
94-
|----------|-----------------|--------------|-------------|
95-
|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-
## <a name="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.
107-
108-
### Policy statement
109-
110-
```xml
111-
<authentication-managed-identity resource="resource" output-token-variable-name="token-variable" ignore-error="true|false"/>
112-
```
113-
114-
### Example
115-
116-
```xml
117-
<authentication-managed-identity resource="https://graph.windows.net" output-token-variable-name="test-access-token" ignore-error="true" />
119+
120+
#### Use managed identity in send-request policy
121+
```xml
122+
<send-request mode="new" timeout="20" ignore-error="false">
123+
<set-url>https://example.com/</set-url>
124+
<set-method>GET</set-method>
125+
<authentication-managed-identity resource="ResourceID"/>
126+
</send-request>
118127
```
119128

120-
### Elements
121-
122-
|Name|Description|Required|
123-
|----------|-----------------|--------------|
124-
|authentication-managed-identity |Root element.|Yes|
125-
126-
### Attributes
127-
128-
|Name|Description|Required|Default|
129-
|----------|-----------------|--------------|-------------|
130-
|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).
136-
137-
- **Policy sections:** inbound
138-
129+
### Elements
130+
131+
|Name|Description|Required|
132+
|----------|-----------------|--------------|
133+
|authentication-managed-identity |Root element.|Yes|
134+
135+
### Attributes
136+
137+
|Name|Description|Required|Default|
138+
|----------|-----------------|--------------|-------------|
139+
|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).
145+
146+
- **Policy sections:** inbound
147+
139148
- **Policy scopes:** all scopes
140149

141150
## Next steps

‎articles/api-management/api-management-features.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,9 @@ ms.author: apimpm
1818

1919
# Feature-based comparison of the Azure API Management tiers
2020

21+
>[!IMPORTANT]
22+
> Please note the Developer tier is for non-production use cases and evaluations. It does not offer SLA.
23+
2124
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.
2225

2326
| Feature | Consumption | Developer | Basic | Standard | Premium |

‎articles/api-management/api-management-howto-protect-backend-with-aad.md

Lines changed: 46 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ Here is a quick overview of the steps:
3333
1. Register an application (backend-app) in Azure AD to represent the API.
3434
2. Register another application (client-app) in Azure AD to represent a client application that needs to call the API.
3535
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.
3737
5. Add the **validate-jwt** policy to validate the OAuth token for every incoming request.
3838

3939
## 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
4242

4343
1. Navigate to the [Azure portal - App registrations](https://go.microsoft.com/fwlink/?linkid=2083908) page.
4444

45-
2. Select **New registration**.
45+
1. Select **New registration**.
4646

4747
1. When the **Register an application page** appears, enter your application's registration information:
4848
- 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.
5050

51-
1. Leave the **Redirect URI** section empty for now.
51+
1. Leave the **Redirect URI** section empty.
5252

5353
1. Select **Register** to create the application.
5454

5555
1. On the app **Overview** page, find the **Application (client) ID** value and record it for later.
5656

5757
When the application is created, make a note of the **Application ID**, for use in a subsequent step.
5858

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+
5965
## Register another application in Azure AD to represent a client application
6066

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.
6268

6369
1. Navigate to the [Azure portal - App registrations](https://go.microsoft.com/fwlink/?linkid=2083908) page.
6470

@@ -78,28 +84,25 @@ Now, create a client secret for this application, for use in a subsequent step.
7884

7985
1. From the list of pages for your client app, select **Certificates & secrets**, and select **New client secret**.
8086

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**.
8288

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.
8490

8591
## Grant permissions in Azure AD
8692

8793
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.
8894

8995
1. Navigate to **App registrations**.
9096

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**.
9498

95-
4. Under **Select an API**, find and select `backend-app`.
99+
1. Select **Add a Permission**.
96100

97-
5. Under **Delegated Permissions**, select the appropriate permissions to `backend-app`.
101+
1. Under **Select an API**, find and select `backend-app`.
98102

99-
6. Select **Add permissions**
103+
1. Under **Delegated Permissions**, select the appropriate permissions to `backend-app` then click on **Add permissions**.
100104

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.
103106

104107
## Enable OAuth 2.0 user authorization in the Developer Console
105108

@@ -109,41 +112,49 @@ In this example, the Developer Console is the client-app. The following steps de
109112

110113
1. In Azure portal, browse to your API Management instance.
111114

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**.
113124

114-
3. Provide a **Display name** and **Description**.
115125

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.
117127

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.
119129

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+
>[!IMPORTANT]
131+
> 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.
121132
122-
7. Copy the **OAuth 2.0 Authorization Endpoint**, and paste it into the **Authorization endpoint URL** text box.
133+
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.
123134

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.
135+
1. If you use **v2** endpoints, use the scope you created for the backend-app in the **Default scope** field.
125136

126-
9. Next, specify the client credentials. These are the credentials for the client-app.
137+
1. Next, specify the client credentials. These are the credentials for the client-app.
127138

128-
10. For **Client ID**, use the **Application ID** for the client-app.
139+
1. For **Client ID**, use the **Application ID** of the client-app.
129140

130-
11. For **Client secret**, use the key you created for the client-app earlier.
141+
1. For **Client secret**, use the key you created for the client-app earlier.
131142

132-
12. Immediately following the client secret is the **redirect_url** for the authorization code grant type. Make a note of this URL.
143+
1. Immediately following the client secret is the **redirect_url** for the authorization code grant type. Make a note of this URL.
133144

134-
13. Select **Create**.
145+
1. Select **Create**.
135146

136-
14. Go back to the **Settings** page of your client-app.
147+
1. Go back to the **Settings** page of your client-app.
137148

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.
149+
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.
139150

140151
Now that you have configured an OAuth 2.0 authorization server, the Developer Console can obtain access tokens from Azure AD.
141152

142153
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.
143154

144155
1. Browse to your API Management instance, and go to **APIs**.
145156

146-
2. Select the API you want to protect. In this example, you use the `Echo API`.
157+
2. Select the API you want to protect. For example, you can use the `Echo API`.
147158

148159
3. Go to **Settings**.
149160

@@ -156,9 +167,9 @@ The next step is to enable OAuth 2.0 user authorization for your API. This enabl
156167
> [!NOTE]
157168
> This section does not apply to the **Consumption** tier, which does not support the developer portal.
158169
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.
170+
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.
160171

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.
172+
1. Browse to any operation under the API in the developer portal, and select **Try it**. This brings you to the Developer Console.
162173

163174
2. Note a new item in the **Authorization** section, corresponding to the authorization server you just added.
164175

@@ -175,11 +186,11 @@ Now that the OAuth 2.0 user authorization is enabled on the `Echo API`, the Deve
175186

176187
## Configure a JWT validation policy to pre-authorize requests
177188

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.
189+
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.
179190

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.
191+
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.
181192

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).
193+
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).
183194

184195
```xml
185196
<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">

‎articles/api-management/upgrade-and-scale.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,10 @@ You can upgrade and downgrade to and from any tier. Note that upgrading or downg
6464
If you choose the **Premium** tier, you first need to select a region.
6565
5. Press **Save**.
6666

67+
## Downtime during scaling up and down
68+
If you are scaling from or to the Developer tier, there will be downtime. Otherwise, there is no downtime.
69+
70+
6771
## Next steps
6872

6973
- [How to deploy an Azure API Management service instance to multiple Azure regions](api-management-howto-deploy-multi-region.md)

0 commit comments

Comments
 (0)