Skip to content

Commit 130693e

Browse files
v-ccolinv-ccolin
authored
Merge pull request #281191 from MicrosoftDocs/main
Merge main to live, 4 AM
2 parents 89c1d81 + f877f26 commit 130693e

File tree

86 files changed

+6504
-5405
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

86 files changed

+6504
-5405
lines changed

‎articles/api-center/TOC.yml

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,11 +47,15 @@
4747
- name: Analyze APIs using linting rules
4848
href: enable-api-analysis-linting.md
4949
- name: Discover shadow APIs with Dev Proxy
50-
href: discover-shadow-apis-dev-proxy.md
50+
href: discover-shadow-apis-dev-proxy.md
51+
- name: Find nonproduction API requests with Dev Proxy
52+
href: find-nonproduction-api-requests-dev-proxy.md
5153
- name: API discovery and consumption
5254
items:
5355
- name: Self-host Azure API Center portal
5456
href: enable-api-center-portal.md
57+
- name: Check if app calls APIs using minimal permissions with Dev Proxy
58+
href: check-minimal-api-permissions-dev-proxy.md
5559
- name: API center management and operations
5660
items:
5761
- name: Reliability

‎articles/api-center/check-minimal-api-permissions-dev-proxy.md

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
---
2+
title: Check app's API calls for minimal permissions with Dev Proxy
3+
description: Learn how to use Dev Proxy to check if your app is calling APIs using minimal permissions defined in Azure API Center.
4+
author: waldekmastykarz
5+
ms.service: api-center
6+
ms.topic: how-to
7+
ms.date: 07/17/2024
8+
ms.author: wmastyka
9+
---
10+
11+
# Check if your app is calling APIs using minimal permissions with Dev Proxy
12+
13+
When building your app, you likely integrate with several APIs and operations. To ensure that your app is secure and follows the principle of least privilege, you should check if your app is calling APIs with minimal permissions. By using minimal permissions, you reduce the risk of unauthorized access to your data and resources.
14+
15+
What's hard about checking if your app is calling APIs with minimal permissions is that each time you integrate a new operation, you need to evaluate the set of permissions you use in your app. Manually tracking all operations and permissions is time-consuming and error-prone. Using Dev Proxy and Azure API Center you can automate checking if your app is calling APIs with minimal permissions.
16+
17+
To check if your app is calling APIs using minimal permissions, you can use Dev Proxy. Dev Proxy is an API simulator that intercepts and analyzes API requests from applications. One feature of Dev Proxy is comparing the permissions that your app uses with the permissions defined in Azure API Center and reporting on any excessive permissions. Dev Proxy also recommends the minimal set of permissions that you should use.
18+
19+
:::image type="content" source="./media/check-minimal-api-permissions-dev-proxy/api-center-minimal-permissions-plugin.png" alt-text="Screenshot of a command prompt showing Dev Proxy checking if the recorded API requests use tokens with minimal API permissions." lightbox="./media/check-minimal-api-permissions-dev-proxy/api-center-minimal-permissions-plugin.png":::
20+
21+
> [!VIDEO https://www.youtube.com/embed/fFr3tFBp1Z8]
22+
23+
## Before you start
24+
25+
To check if your app is calling APIs using minimal permissions, you need to have an Azure API Center instance with information about the APIs that you use in your organization. If you haven't created one already, see [Quickstart: Create your API center](set-up-api-center.md). Additionally, you need to install [Dev Proxy](https://aka.ms/devproxy).
26+
27+
> [!TIP]
28+
> Download the preset for this how to article by running in the command prompt `devproxy preset get demo-apicenter-minimalpermissions`.
29+
30+
### Register APIs in your Azure API Center instance
31+
32+
Register APIs that you use in your organization. For each API, upload the OpenAPI specification file that describes the API operations and permissions.
33+
34+
:::image type="content" source="./media/check-minimal-api-permissions-dev-proxy/api-center-minimal-permissions-openapi-spec-security.png" alt-text="Screenshot of Azure API Center with an API and its OpenAPI spec with security information." lightbox="./media/check-minimal-api-permissions-dev-proxy/api-center-minimal-permissions-openapi-spec-security.png":::
35+
36+
The Dev Proxy `ApiCenterMinimalPermissionsPlugin` uses this information to check if your app is calling APIs using minimal permissions.
37+
38+
### Copy API Center information
39+
40+
From the Azure API Center instance Overview page, copy the **name** of the API Center instance, the name of the **resource group** and the **subscription ID**. You need this information to configure the `ApiCenterMinimalPermissionsPlugin` so that it can connect to your Azure API Center instance.
41+
42+
:::image type="content" source="./media/check-minimal-api-permissions-dev-proxy/api-center-overview.png" alt-text="Screenshot of Azure API Center overview page with several properties highlighted." lightbox="./media/check-minimal-api-permissions-dev-proxy/api-center-overview.png":::
43+
44+
## Configure Dev Proxy
45+
46+
To check if your app is calling APIs using minimal permissions, you need to enable the `ApiCenterMinimalPermissionsPlugin` in the Dev Proxy configuration file. To create a report of permissions that your app uses, add a reporter.
47+
48+
### Enable the `ApiCenterMinimalPermissionsPlugin`
49+
50+
In the `devproxyrc.json` file, add the following configuration:
51+
52+
```json
53+
{
54+
"$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
55+
"plugins": [
56+
{
57+
"name": "ApiCenterMinimalPermissionsPlugin",
58+
"enabled": true,
59+
"pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
60+
"configSection": "apiCenterMinimalPermissionsPlugin"
61+
}
62+
],
63+
"urlsToWatch": [
64+
"https://api.northwind.com/*"
65+
],
66+
"apiCenterMinimalPermissionsPlugin": {
67+
"subscriptionId": "00000000-0000-0000-0000-000000000000",
68+
"resourceGroupName": "demo",
69+
"serviceName": "contoso-api-center",
70+
"workspaceName": "default"
71+
}
72+
}
73+
```
74+
75+
In the `subscriptionId`, `resourceGroupName`, and `serviceName` properties, provide the information about your Azure API Center instance.
76+
77+
In the `urlsToWatch` property, specify the URLs that your app uses.
78+
79+
> [!TIP]
80+
> Use the [Dev Proxy Toolkit](https://aka.ms/devproxy/toolkit) Visual Studio Code extension to easily manage Dev Proxy configuration.
81+
82+
### Add a reporter
83+
84+
The `ApiCenterMinimalPermissionsPlugin` produces a report of APIs that your app is using, and the minimal permissions required to call them. To view this report, add a reporter to your Dev Proxy configuration file. Dev Proxy offers several [reporters](/microsoft-cloud/dev/dev-proxy/technical-reference/overview#reporters). In this example, you use the [plain-text reporter](/microsoft-cloud/dev/dev-proxy/technical-reference/plaintextreporter).
85+
86+
Update your `devproxyrc.json` file with a reference to the plain-text reporter:
87+
88+
```json
89+
{
90+
"$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
91+
"plugins": [
92+
{
93+
"name": "ApiCenterMinimalPermissionsPlugin",
94+
"enabled": true,
95+
"pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
96+
"configSection": "apiCenterMinimalPermissionsPlugin"
97+
},
98+
{
99+
"name": "PlainTextReporter",
100+
"enabled": true,
101+
"pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
102+
}
103+
],
104+
"urlsToWatch": [
105+
"https://api.northwind.com/*"
106+
],
107+
"apiCenterMinimalPermissionsPlugin": {
108+
"subscriptionId": "00000000-0000-0000-0000-000000000000",
109+
"resourceGroupName": "demo",
110+
"serviceName": "contoso-api-center",
111+
"workspaceName": "default"
112+
}
113+
}
114+
```
115+
116+
## Check if your app is calling APIs using minimal permissions
117+
118+
To check if your app is calling APIs using minimal permissions, you need to connect to your Azure subscription, run Dev Proxy, and let it intercept API requests from your app. Dev Proxy then compares the information about the API requests with the information from Azure API Center and reports on the minimal permissions.
119+
120+
### Connect to your Azure subscription
121+
122+
Dev Proxy uses information from Azure API Center to determine if your app is calling APIs using minimal permissions. To get this information, it needs a connection to your Azure subscription. You can connect to your Azure subscription in [several ways](/microsoft-cloud/dev/dev-proxy/technical-reference/apicenterproductionversionplugin#remarks).
123+
124+
### Run Dev Proxy
125+
126+
After connecting to your Azure subscription, start Dev Proxy. If you start Dev Proxy from the same folder where your `devproxyrc.json` file is located, it automatically loads the configuration. Otherwise, specify the path to the configuration file using the `--config-file` option.
127+
128+
When Dev Proxy starts, it checks that it can connect to your Azure subscription. When the connection is successful, you see a message similar to:
129+
130+
```text
131+
info Plugin ApiCenterMinimalPermissionsPlugin connecting to Azure...
132+
info Listening on 127.0.0.1:8000...
133+
134+
Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
135+
Press CTRL+C to stop Dev Proxy
136+
```
137+
138+
Press <kbd>r</kbd> to start recording API requests from your app.
139+
140+
### Use your app
141+
142+
Use your app as you would normally do. In this tutorial, you can use the following request with a simulated access token with `customer.readwrite` permission:
143+
144+
```http
145+
@readwriteToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJzY3AiOlsiY3VzdG9tZXIucmVhZHdyaXRlIl19.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
146+
147+
GET https://api.northwind.com/customers/ALFKI
148+
Authorization: Bearer {{readwriteToken}}
149+
```
150+
151+
Dev Proxy intercepts the API requests and stores information about them in memory. In the command line where Dev Proxy runs, you should see information about API requests that your app makes.
152+
153+
```text
154+
info Plugin ApiCenterMinimalPermissionsPlugin connecting to Azure...
155+
info Listening on 127.0.0.1:8000...
156+
157+
Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
158+
Press CTRL+C to stop Dev Proxy
159+
160+
◉ Recording...
161+
162+
req ╭ GET https://api.northwind.com/customers/ALFKI
163+
mock ╰ 200 /{customer-id}
164+
```
165+
166+
### Check permissions
167+
168+
Stop the recording by pressing <kbd>s</kbd>. Dev Proxy connects to the API Center instance and compares the information about requests with the information from API Center.
169+
170+
```text
171+
info Plugin ApiCenterMinimalPermissionsPlugin connecting to Azure...
172+
info Listening on 127.0.0.1:8000...
173+
174+
Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
175+
Press CTRL+C to stop Dev Proxy
176+
177+
◉ Recording...
178+
179+
req ╭ GET https://api.northwind.com/customers/ALFKI
180+
mock ╰ 200 /{customer-id}
181+
○ Stopped recording
182+
info Checking if recorded API requests use minimal permissions as defined in API Center...
183+
info Loading APIs from API Center...
184+
info Loading API definitions from API Center...
185+
info Checking minimal permissions for API https://api.northwind.com...
186+
info Analyzing recorded requests...
187+
warn Calling API Northwind with excessive permissions: customer.readwrite. Minimal permissions are: customer.read
188+
info DONE
189+
```
190+
191+
When Dev Proxy finishes its analysis, it creates a report in a file named `ApiCenterMinimalPermissionsPlugin_PlainTextReporter.txt` with the following contents:
192+
193+
```text
194+
Azure API Center minimal permissions report
195+
196+
APIS
197+
198+
Northwind
199+
200+
x Called using excessive permissions
201+
202+
Permissions
203+
204+
- Minimal permissions: customer.read
205+
- Permissions on the token: customer.readwrite
206+
- Excessive permissions: customer.readwrite
207+
208+
Requests
209+
210+
- GET https://api.northwind.com/customers/ALFKI
211+
212+
UNMATCHED REQUESTS
213+
214+
No unmatched requests found.
215+
216+
ERRORS
217+
218+
No errors occurred.
219+
```
220+
221+
## Summary
222+
223+
Using the `ApiCenterMinimalPermissionsPlugin`, you can check if your app is calling APIs using minimal permissions. The plugin compares the information about API requests from your app with information from Azure API Center and reports on excessive permissions. It also recommends the minimal permissions needed to call the APIs that you're using in your app. Verifying that your app is calling APIs using minimal permissions, helps you make your app more secure. You can run this check manually or integrate with your CI/CD pipeline to ensure that your app is calling APIs using minimal permissions before releasing it to production.
224+
225+
## Related content
226+
227+
- [Learn more about Dev Proxy](/microsoft-cloud/dev/dev-proxy/overview)
228+
- [Learn more about Azure API Center](./key-concepts.md)

0 commit comments

Comments
 (0)