Graph application access
Microsoft's edit ·
Microsoft's commit message in microsoftgraph/microsoft-graph-docs-contrib · commit 816b213 · +32 −48 lines · also on GitHub
⋯ 3 unchanged lines
44
author: FaithOmbongi
55
ms.author: ombongifaith
66
ms.reviewer: jackson.woods
7
−ms.topic: tutorial
7
+ms.topic: how-to
88
ms.localizationpriority: high
99
ms.subservice: entra-applications
1010
ms.custom: graphiamtop20
11
−ms.date: 09/08/2023
11
+ms.date: 08/26/2024
1212
#customer intent: As a developer, I want to understand how my app can call Microsoft Graph on behalf of a signed-in user to access resources in a tenant.
1313
---
1414
⋯ 1 unchanged line
1616
1717
To call Microsoft Graph, an app must obtain an access token from the Microsoft identity platform. This access token includes information about whether the app is authorized to access Microsoft Graph on behalf of a signed-in user or with its own identity. This article provides guidance on how an app can [access Microsoft Graph with its own identity](./auth/auth-concepts.md#access-scenarios), also called *app-only access*.
1818
19
−This article details the raw HTTP requests involved for an app to call Microsoft Graph with its own identity using a popular flow called the [OAuth 2.0 client credentials grant flow](/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow). Alternatively, you can avoid writing raw HTTP requests and use a Microsoft-built or supported authentication library that handles many of these details for you and helps you to get access tokens and call Microsoft Graph. For more information, see [Use the Microsoft Authentication Library (MSAL)](#use-the-microsoft-authentication-library-msal).
19
+This article details the raw HTTP requests involved for an app to call Microsoft Graph with its own identity using a popular flow called the [OAuth 2.0 client credentials grant flow](/entra/identity-platform/v2-oauth2-client-creds-grant-flow). Alternatively, you can avoid writing raw HTTP requests and use a Microsoft-built or supported authentication library that helps you to get access tokens and call Microsoft Graph. For more information, see [Use the Microsoft Authentication Library (MSAL)](#use-the-microsoft-authentication-library-msal).
2020
21
+In this article, you complete the following steps in using the client credentials flow:
22
+
23
+1. Configure Microsoft Graph application permissions on the app.
24
+2. Request administrator consent.
25
+3. Request an access token.
26
+4. Call Microsoft Graph using the access token.
27
+
2128
## Prerequisites
2229
2330
Before proceeding with the steps in this article:
2431
2532
1. Understand the authentication and authorization concepts in the Microsoft identity platform. For more information, see [Authentication and authorization basics](auth/auth-concepts.md).
26
−2. Register the app with Microsoft Entra ID. For more information, see [Register an application with the Microsoft identity platform](auth-register-app-v2.md).
27
−
28
−## Authentication and authorization steps
29
−
30
−For an app to get authorization and access to Microsoft Graph using the client credentials flow, you must follow these five steps:
31
−
32
−1. Register the app with Microsoft Entra ID.
33
−2. Configure Microsoft Graph application permissions on the app.
34
−3. Request administrator consent.
35
−4. Request an access token.
36
−5. Call Microsoft Graph using the access token.
37
−
38
−<!--
39
−> [!TIP]
40
−> [](https://app.getpostman.com/run-collection/f77994d794bab767596d)<br/>
41
−> Try steps 2-5 in Postman. Don't forget to replace tokens and IDs!
42
−-->
43
−
44
−## 1. Register the app
45
−
46
−Before the app can use the Microsoft identity platform endpoint or call Microsoft Graph, it must be properly registered. [Follow the steps to register your app](./auth-register-app-v2.md) on the Microsoft Entra admin center.
47
−
48
−From the app registration, save the following values:
49
−
50
−- The application ID (referred to as Object ID on the Microsoft Entra admin center) assigned by the app registration portal.
51
−- A client secret (application password), a certificate, or a federated identity credential.
52
−- A redirect URI for the app to receive token responses from Microsoft Entra ID.
53
−- A redirect URI for the service to receive admin consent responses if the app implements functionality to request administrator consent.
33
+2. Register the app with Microsoft Entra ID. For more information, see [Register an application with the Microsoft identity platform](auth-register-app-v2.md). Save the following values from the app registration:
34
+ - The application ID (referred to as Object ID on the Microsoft Entra admin center).
35
+ - A client secret (application password), a certificate, or a federated identity credential.
36
+ - A redirect URI for the app to receive token responses from Microsoft Entra ID.
37
+ - A redirect URI for the service to receive admin consent responses *if* the app implements functionality to request administrator consent.
5438
55
−## 2. Configure permissions for Microsoft Graph
39
+## Configure permissions for Microsoft Graph
5640
57
−Microsoft Graph exposes [application permissions](./permissions-overview.md#application-permissions) for apps that call Microsoft Graph under their own identity. These permissions always require administrator consent.
41
+Microsoft Graph exposes [application permissions](./permissions-overview.md#application-permissions) for apps that call Microsoft Graph with their own identity. These permissions always require administrator consent.
5842
5943
You preconfigure the application permissions the app needs when you register the app. An administrator can consent to these permissions either using the [Microsoft Entra admin center](https://entra.microsoft.com) when they install the app in their organization, or you can provide a sign-up experience in the app through which administrators can consent to the permissions you configured. Once Microsoft Entra ID records the administrator consent, the app can request tokens without having to request consent again.
6044
6145
To configure application permissions for the app in the app registrations experience on the Microsoft Entra admin center, follow these steps:
6246
63
−- Under the application's **API permissions** page, choose **Add a permission**.
47
+- On the application's **API permissions** page, choose **Add a permission**.
6448
- Select **Microsoft Graph** > select **Application permissions**.
6549
- In the **Select Permissions** dialog, choose the permissions to configure to the app.
6650
⋯ 5 unchanged lines
7256
>
7357
> Always configure the least privileged set of permissions required by the app. For more information, see [Best practices for using Microsoft Graph permissions](./permissions-overview.md#best-practices-for-using-microsoft-graph-permissions).
7458
75
−## 3. Request administrator consent
59
+## Step 2: Request administrator consent
7660
7761
Administrators can grant the permissions your app needs at the [Microsoft Entra admin center](https://entra.microsoft.com). However, when you don't have access to the Microsoft Entra admin center, you can provide a sign-up experience for administrators by using the Microsoft identity platform `/adminconsent` endpoint.
7862
⋯ 22 unchanged lines
10185
10286
| Parameter | Condition | Description
10387
|:--------------|:------------|:------------
104
−| tenant | Required | The directory tenant that you want to request permission from. The value can be in GUID or a friendly name format. If you don't know which tenant the user belongs to and you want to let them sign in with any tenant, use `common`.
88
+| tenant | Required | The tenant that you want to request permission from. The value can be in GUID or a friendly name format. If you don't know which tenant the user belongs to and you want to let them sign in with any tenant, use `common`.
10589
| client_id | Required | The application ID that the [Azure app registration portal](https://go.microsoft.com/fwlink/?linkid=2083908) assigned to your app.
10690
| redirect_uri | Required | The redirect URI where you want the response to be sent for your app to handle. It must match one of the redirect URIs that you registered in the portal. It must be URL encoded and it can have additional path segments.
10791
| state | Recommended | A value that is included in the request that also is returned in the token response. It can be a string of any content that you want. The state is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
⋯ 4 unchanged lines
11296
11397
The following screenshot is an example of the consent dialog that Microsoft Entra ID presents to the administrator:
11498
115
−:::image type="content" source="./images/auth-v2/admin-consent.png" alt-text="Administrator consent dialog." border="true":::
99
+:::image type="content" source="./images/auth-v2/admin-consent.png" alt-text="The admin consent dialog indicates the permissions to consent to and what actions the permissions allow." border="true":::
116100
117101
### Response
118102
⋯ 7 unchanged lines
126110
127111
| Parameter | Description
128112
|:--------------|:------------
129
−| tenant | The directory tenant that granted your application the permissions that it requested, in GUID format.
113
+| tenant | The tenant that granted your application the permissions that it requested, in GUID format.
130114
| state | A value that is included in the request that also is returned in the token response. It can be a string of any content that you want. The state is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
131115
| admin_consent | Set to **True**.
132116
133
−## 4. Request an access token
117
+## Step 3: Request an access token
134118
135119
In the OAuth 2.0 client credentials grant flow, you use the application ID and client secret values that you saved when you registered your app to request an access token directly from the Microsoft identity platform `/token` endpoint.
136120
⋯ 31 unchanged lines
168152
169153
| Parameter | Condition | Description
170154
|:--------------|:----------|:------------
171
−| tenant | Required | The directory tenant that you want to request permission from. The value can be in GUID or a friendly name format.
155
+| tenant | Required | The tenant that you want to request permission from. The value can be in GUID or a friendly name format.
172156
| client_id | Required | The application ID that the [Azure app registration portal](https://go.microsoft.com/fwlink/?linkid=2083908) assigned when you registered your app.
173157
| scope | Required | The value passed for the **scope** parameter in this request should be the identifier (app ID URI) of the resource you want, affixed with the `.default` suffix. For example, the Microsoft Graph resource app ID URI is `https://graph.microsoft.com/`. For Microsoft Graph, the value of **scope** is therefore `https://graph.microsoft.com/.default`. This value informs the Microsoft identity platform endpoint to include in the access token all the app-level permissions the admin has consented to.
174158
| client_secret | Required | The client secret that you generated for your app in the app registration portal. Ensure that it's URL encoded.
⋯ 19 unchanged lines
194178
| ext_expires_in | Used to indicate an extended lifetime for the access token and to support resiliency when the token issuance service isn't responding. |
195179
| token_type | Indicates the token type value. The only type that Microsoft Entra ID supports is `Bearer`. |
196180
197
−## 5. Use the access token to call Microsoft Graph
181
+## Step 4: Use the access token to call Microsoft Graph
198182
199183
After you have an access token, the app uses it to call Microsoft Graph by attaching the access token as a **Bearer** token to the **Authorization** header in an HTTP request. The following request gets all users in the tenant. The app must have the _User.Read.All_ permission to call this API.
200184
⋯ 61 unchanged lines
262246
263247
## Supported app scenarios and resources
264248
265
−Apps that call Microsoft Graph under their own identity fall into one of two categories:
249
+Apps that call Microsoft Graph with their own identity fall into one of two categories:
266250
267
−- [Background services (daemons)](/azure/active-directory/develop/scenario-daemon-overview) that run on a server without a signed-in user.
251
+- [Background services (daemons)](/entra/identity-platform/scenario-daemon-app-registration) that run on a server without a signed-in user.
268252
- Apps that have a signed-in user but also call Microsoft Graph with their own identity. For example, to use functionality that requires more elevated privileges than the user has.
269253
270254
In this article, the app used a client secret as the credential. You can optionally configure a certificate or a federated identity credential.
271255
272
−For more information about apps that call Microsoft Graph under their own identity and use the client credentials flow, see [Authentication flows and application scenarios: Daemon app that calls a web API in the daemon's name](/azure/active-directory/develop/authentication-flows-app-scenarios#daemon-app-that-calls-a-web-api-in-the-daemons-name).
256
+For more information about apps that call Microsoft Graph with their own identity and use the client credentials flow, see [Authentication flows and application scenarios: Daemon app that calls a web API in the daemon's name](/entra/identity-platform/authentication-flows-app-scenarios#daemon-app-that-calls-a-web-api-in-the-daemons-name).
273257
274258
## Use the Microsoft Authentication Library (MSAL)
275259
276
−In this article, you walked through the low-level protocol details required only when manually crafting and issuing raw HTTP requests to execute the client credentials flow. In production apps, use a [Microsoft-built or supported authentication library](/azure/active-directory/develop/msal-overview), such as the Microsoft Authentication Library (MSAL), to get security tokens and call protected web APIs such as Microsoft Graph.
260
+In this article, you walked through the low-level protocol details required only when manually crafting and issuing raw HTTP requests to execute the client credentials flow. In production apps, use a [Microsoft-built or supported authentication library](/entra/identity-platform/msal-overview), such as the Microsoft Authentication Library (MSAL), to get security tokens and call protected web APIs such as Microsoft Graph.
277261
278
−MSAL and other supported authentication libraries simplify the process for you by handling details such as validation, cookie handling, token caching, and secure connections, allowing you to focus on the functionality of your application.
262
+MSAL and other supported authentication libraries simplify the process for you by handling details such as validation, cookie handling, token caching, and secure connections; allowing you to focus on the functionality of your application.
279263
280
−Microsoft has built and maintains a wide selection of code samples that demonstrate usage of supported authentication libraries with the Microsoft identity platform. To access these code samples, see the [Microsoft identity platform code samples](/entra/identity-platform/sample-v2-code?tabs=apptype#service--daemon).
264
+Access the [Microsoft identity platform code samples](/entra/identity-platform/sample-v2-code?tabs=apptype#service--daemon) to see how to use MSAL to get access tokens and call Microsoft Graph.
281265
282266
## Related content
283267
284
−- Choose from code samples that are built and maintained by Microsoft to run custom apps that use supported authentication libraries, sign-in users, and call Microsoft Graph. See [Microsoft Graph tutorials](/graph/tutorials).
268
+- Explore [Microsoft Graph tutorials](/graph/tutorials) to create basic applications that access data in app-only scenarios.
Microsoft's Markdown source from microsoftgraph/microsoft-graph-docs-contrib, © Microsoft Corporation, under CC BY 4.0. Changed lines with up to 3 unchanged lines around each; ChangeIntel kept this copy 10 Oct 09:24 UTC. The commit date is when the source changed, which can be hours or days before Learn published it.