Skip to content

Commit 5f559c5

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #233947 from AaronMaxwell/aaronmax-app-insights-aad-api-2
New article for AI AAD auth
2 parents 37cdb92 + 2222e7b commit 5f559c5

File tree

2 files changed

+317
-0
lines changed

2 files changed

+317
-0
lines changed

‎articles/azure-monitor/logs/api/app-insights-azure-ad-api.md

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,315 @@
1+
---
2+
title: Application Insights API Access with Microsoft Azure Active Directory (Azure AD) Authentication
3+
description: Learn how to authenticate and access the Azure Monitor Application Insights APIs using Azure AD
4+
ms.date: 04/11/2023
5+
author: CourtGoodson
6+
ms.author: cogoodson
7+
ms.topic: article
8+
---
9+
# Application Insights API Access with Microsoft Azure Active Directory (Azure AD) Authentication
10+
11+
You can submit a query request to a workspace by using the Azure Monitor Log Analytics endpoint `https://api.loganalytics.azure.com`. To access the endpoint, you must authenticate through Azure Active Directory (Azure AD).
12+
13+
>[!Note]
14+
> The `api.loganalytics.io` endpoint is being replaced by `api.loganalytics.azure.com`. The `api.loganalytics.io` endpoint will continue to be supported for the forseeable future.
15+
16+
## Authenticate with a demo API key
17+
18+
To quickly explore the API without Azure AD authentication, use the demonstration workspace with sample data, which supports API key authentication.
19+
20+
To authenticate and run queries against the sample workspace, use `DEMO_WORKSPACE` as the {workspace-id} and pass in the API key `DEMO_KEY`.
21+
22+
If either the Application ID or the API key is incorrect, the API service returns a [403](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error) (Forbidden) error.
23+
24+
The API key `DEMO_KEY` can be passed in three different ways, depending on whether you want to use a header, the URL, or basic authentication:
25+
26+
- **Custom header**: Provide the API key in the custom header `X-Api-Key`.
27+
- **Query parameter**: Provide the API key in the URL parameter `api_key`.
28+
- **Basic authentication**: Provide the API key as either username or password. If you provide both, the API key must be in the username.
29+
30+
This example uses the workspace ID and API key in the header:
31+
32+
```
33+
POST https://api.loganalytics.azure.com/v1/workspaces/DEMO_WORKSPACE/query
34+
X-Api-Key: DEMO_KEY
35+
Content-Type: application/json
36+
37+
{
38+
"query": "AzureActivity | summarize count() by Category"
39+
}
40+
```
41+
42+
## Public API endpoint
43+
44+
The public API endpoint is:
45+
46+
```
47+
https://api.loganalytics.azure.com/{api-version}/workspaces/{workspaceId}
48+
```
49+
where:
50+
- **api-version**: The API version. The current version is "v1."
51+
- **workspaceId**: Your workspace ID.
52+
53+
The query is passed in the request body.
54+
55+
For example:
56+
```
57+
https://api.loganalytics.azure.com/v1/workspaces/1234abcd-def89-765a-9abc-def1234abcde
58+
59+
Body:
60+
{
61+
"query": "Usage"
62+
}
63+
```
64+
65+
## Set up authentication
66+
67+
To access the API, you register a client app with Azure AD and request a token.
68+
69+
1. [Register an app in Azure AD](./register-app-for-token.md).
70+
71+
1. On the app's overview page, select **API permissions**.
72+
1. Select **Add a permission**.
73+
1. On the **APIs my organization uses** tab, search for **Log Analytics** and select **Log Analytics API** from the list.
74+
75+
:::image type="content" source="../media/api-register-app/request-api-permissions.png" alt-text="A screenshot that shows the Request API permissions page.":::
76+
77+
1. Select **Delegated permissions**.
78+
1. Select the **Data.Read** checkbox.
79+
1. Select **Add permissions**.
80+
81+
:::image type="content" source="../media/api-register-app/add-requested-permissions.png" alt-text="A screenshot that shows the continuation of the Request API permissions page.":::
82+
83+
Now that your app is registered and has permissions to use the API, grant your app access to your Log Analytics workspace.
84+
85+
1. From your **Log Analytics workspace** overview page, select **Access control (IAM)**.
86+
1. Select **Add role assignment**.
87+
88+
:::image type="content" source="../media/api-register-app/workspace-access-control.png" alt-text="A screenshot that shows the Access control page for a Log Analytics workspace.":::
89+
90+
1. Select the **Reader** role and then select **Members**.
91+
92+
:::image type="content" source="../media/api-register-app/add-role-assignment.png" alt-text="A screenshot that shows the Add role assignment page for a Log Analytics workspace.":::
93+
94+
1. On the **Members** tab, choose **Select members**.
95+
1. Enter the name of your app in the **Select** box.
96+
1. Select your app and choose **Select**.
97+
1. Select **Review + assign**.
98+
99+
:::image type="content" source="../media/api-register-app/select-members.png" alt-text="A screenshot that shows the Select members pane on the Add role assignment page for a Log Analytics workspace.":::
100+
101+
1. After you finish the Active Directory setup and workspace permissions, request an authorization token.
102+
103+
>[!Note]
104+
> For this example, we applied the Reader role. This role is one of many built-in roles and might include more permissions than you require. More granular roles and permissions can be created. For more information, see [Manage access to Log Analytics workspaces](../../logs/manage-access.md).
105+
106+
## Request an authorization token
107+
108+
Before you begin, make sure you have all the values required to make the request successfully. All requests require:
109+
- Your Azure AD tenant ID.
110+
- Your workspace ID.
111+
- Your Azure AD client ID for the app.
112+
- An Azure AD client secret for the app.
113+
114+
The Log Analytics API supports Azure AD authentication with three different [Azure AD OAuth2](/azure/active-directory/develop/active-directory-protocols-oauth-code) flows:
115+
- Client credentials
116+
- Authorization code
117+
- Implicit
118+
119+
### Client credentials flow
120+
121+
In the client credentials flow, the token is used with the Log Analytics endpoint. A single request is made to receive a token by using the credentials provided for your app in the previous step when you [register an app in Azure AD](./register-app-for-token.md).
122+
123+
Use the `https://api.loganalytics.azure.com` endpoint.
124+
125+
#### Client credentials token URL (POST request)
126+
127+
```http
128+
POST /<your-tenant-id>/oauth2/token
129+
Host: https://login.microsoftonline.com
130+
Content-Type: application/x-www-form-urlencoded
131+
132+
grant_type=client_credentials
133+
&client_id=<app-client-id>
134+
&resource=https://api.loganalytics.io
135+
&client_secret=<app-client-secret>
136+
```
137+
138+
A successful request receives an access token in the response:
139+
140+
```http
141+
{
142+
token_type": "Bearer",
143+
"expires_in": "86399",
144+
"ext_expires_in": "86399",
145+
"access_token": ""eyJ0eXAiOiJKV1QiLCJ.....Ax"
146+
}
147+
```
148+
149+
Use the token in requests to the Log Analytics endpoint:
150+
151+
```http
152+
POST /v1/workspaces/your workspace id/query?timespan=P1D
153+
Host: https://api.loganalytics.azure.com
154+
Content-Type: application/json
155+
Authorization: bearer <your access token>
156+
157+
Body:
158+
{
159+
"query": "AzureActivity |summarize count() by Category"
160+
}
161+
```
162+
163+
Example response:
164+
165+
```http
166+
{
167+
"tables": [
168+
{
169+
"name": "PrimaryResult",
170+
"columns": [
171+
{
172+
"name": "OperationName",
173+
"type": "string"
174+
},
175+
{
176+
"name": "Level",
177+
"type": "string"
178+
},
179+
{
180+
"name": "ActivityStatus",
181+
"type": "string"
182+
}
183+
],
184+
"rows": [
185+
[
186+
"Metric Alert",
187+
"Informational",
188+
"Resolved",
189+
...
190+
],
191+
...
192+
]
193+
},
194+
...
195+
]
196+
}
197+
```
198+
199+
### Authorization code flow
200+
201+
The main OAuth2 flow supported is through [authorization codes](/azure/active-directory/develop/active-directory-protocols-oauth-code). This method requires two HTTP requests to acquire a token with which to call the Azure Monitor Log Analytics API. There are two URLs, with one endpoint per request. Their formats are described in the following sections.
202+
203+
#### Authorization code URL (GET request)
204+
205+
```http
206+
GET https://login.microsoftonline.com/YOUR_Azure AD_TENANT/oauth2/authorize?
207+
client_id=<app-client-id>
208+
&response_type=code
209+
&redirect_uri=<app-redirect-uri>
210+
&resource=https://api.loganalytics.io
211+
```
212+
213+
When a request is made to the authorize URL, the client\_id is the application ID from your Azure AD app, copied from the app's properties menu. The redirect\_uri is the homepage/login URL from the same Azure AD app. When a request is successful, this endpoint redirects you to the sign-in page you provided at sign-up with the authorization code appended to the URL. See the following example:
214+
215+
```http
216+
http://<app-client-id>/?code=AUTHORIZATION_CODE&session_state=STATE_GUID
217+
```
218+
219+
At this point, you've obtained an authorization code, which you need now to request an access token.
220+
221+
#### Authorization code token URL (POST request)
222+
223+
```http
224+
POST /YOUR_Azure AD_TENANT/oauth2/token HTTP/1.1
225+
Host: https://login.microsoftonline.com
226+
Content-Type: application/x-www-form-urlencoded
227+
228+
grant_type=authorization_code
229+
&client_id=<app client id>
230+
&code=<auth code fom GET request>
231+
&redirect_uri=<app-client-id>
232+
&resource=https://api.loganalytics.io
233+
&client_secret=<app-client-secret>
234+
```
235+
236+
All values are the same as before, with some additions. The authorization code is the same code you received in the previous request after a successful redirect. The code is combined with the key obtained from the Azure AD app. If you didn't save the key, you can delete it and create a new one from the keys tab of the Azure AD app menu. The response is a JSON string that contains the token with the following schema. Types are indicated for the token values.
237+
238+
Response example:
239+
240+
```http
241+
{
242+
"access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
243+
"expires_in": "3600",
244+
"ext_expires_in": "1503641912",
245+
"id_token": "not_needed_for_log_analytics",
246+
"not_before": "1503638012",
247+
"refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az",
248+
"resource": "https://api.loganalytics.io",
249+
"scope": "Data.Read",
250+
"token_type": "bearer"
251+
}
252+
```
253+
254+
The access token portion of this response is what you present to the Log Analytics API in the `Authorization: Bearer` header. You can also use the refresh token in the future to acquire a new access\_token and refresh\_token when yours have gone stale. For this request, the format and endpoint are:
255+
256+
```http
257+
POST /YOUR_AAD_TENANT/oauth2/token HTTP/1.1
258+
Host: https://login.microsoftonline.com
259+
Content-Type: application/x-www-form-urlencoded
260+
261+
client_id=<app-client-id>
262+
&refresh_token=<refresh-token>
263+
&grant_type=refresh_token
264+
&resource=https://api.loganalytics.io
265+
&client_secret=<app-client-secret>
266+
```
267+
268+
Response example:
269+
270+
```http
271+
{
272+
"token_type": "Bearer",
273+
"expires_in": "3600",
274+
"expires_on": "1460404526",
275+
"resource": "https://api.loganalytics.io",
276+
"access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
277+
"refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az"
278+
}
279+
```
280+
281+
### Implicit code flow
282+
283+
The Log Analytics API supports the OAuth2 [implicit flow](/azure/active-directory/develop/active-directory-dev-understanding-oauth2-implicit-grant). For this flow, only a single request is required, but no refresh token can be acquired.
284+
285+
#### Implicit code authorize URL
286+
287+
```http
288+
GET https://login.microsoftonline.com/YOUR_AAD_TENANT/oauth2/authorize?
289+
client_id=<app-client-id>
290+
&response_type=token
291+
&redirect_uri=<app-redirect-uri>
292+
&resource=https://api.loganalytics.io
293+
```
294+
295+
A successful request produces a redirect to your redirect URI with the token in the URL:
296+
297+
```http
298+
http://YOUR_REDIRECT_URI/#access_token=YOUR_ACCESS_TOKEN&token_type=Bearer&expires_in=3600&session_state=STATE_GUID
299+
```
300+
301+
This access\_token can be used as the `Authorization: Bearer` header value when it's passed to the Log Analytics API to authorize requests.
302+
303+
## More information
304+
305+
You can find documentation about OAuth2 with Azure AD here:
306+
- [Azure AD authorization code flow](/azure/active-directory/develop/active-directory-protocols-oauth-code)
307+
- [Azure AD implicit grant flow](/azure/active-directory/develop/active-directory-dev-understanding-oauth2-implicit-grant)
308+
- [Azure AD S2S client credentials flow](/azure/active-directory/develop/active-directory-protocols-oauth-service-to-service)
309+
310+
## Next steps
311+
312+
- [Request format](./request-format.md)
313+
- [Response format](./response-format.md)
314+
- [Querying logs for Azure resources](./azure-resource-queries.md)
315+
- [Batch queries](./batch-queries.md)

‎articles/azure-monitor/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1252,6 +1252,8 @@ items:
12521252
items:
12531253
- name: API access, authentication and authorization
12541254
href: logs/api/access-api.md
1255+
- name: Application Insights API access with Azure Active Directory
1256+
href: logs/api/app-insights-azure-ad-api.md
12551257
- name: Register an app for API access
12561258
href: logs/api/register-app-for-token.md
12571259
- name: Request format

0 commit comments

Comments
 (0)