Skip to content

Commit 2162c6c

Browse files
AarDavMaxAarDavMax
committed
New article for AI AAD auth
1 parent e99d7d6 commit 2162c6c

File tree

2 files changed

+316
-0
lines changed

2 files changed

+316
-0
lines changed

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

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