Microsoft
Microsoft Graph
Microsoft
Some apps run on a server without a user present. These kinds of apps are often referred to as background services or daemons. An example of such an app might be an email archival service that wakes up and runs overnight. Background services typically use the OAuth 2.0 Client Credentials Grant flow to get access tokens from Azure AD. In this topic, we will walk through the basic steps to configure a background service and use the OAuth Client Credentials Grant flow to get an access token from Azure AD to call Microsoft Graph.
The basic steps required to authenticate a background service and get a token from the Azure AD v2.0 endpoint to make calls to Microsoft Graph are:
To authenticate with the Azure v2.0 endpoint, you must first register your app at the Microsoft App Registration Portal. You can use either a Microsoft account or a work or school account to register your app.
The following screenshot shows a web app registration that has been configured for a background service.
For a background service, you need to register your app for the Web platform and copy the following values:
For steps on how to configure an app using the Microsoft App Registration Portal, see Register your app.
With the OAuth 2.0 Client Credentials Grant flow, your app authenticates directly at the Azure AD v2.0 /token endpoint using the Application Id assigned by Azure AD and the Application Secret that you create using the portal.
For apps that run without a user, Microsoft Graph exposes Application permissions. You pre-configure these permissions when you register your app. Application permissions always require administrator consent. An administrator can either consent to these permissions using the Azure portal when your app is installed in their organization, or you can provide a sign-up experience in your app through which administrators can consent to the permissions you configured. Once administrator consent is recorded by Azure AD, your app can request tokens without having to request consent again. For more detailed information about the permissions available with Microsoft Graph, see the Permissions reference
To configure Application permissions for your app in the Microsoft App Registration Portal: under Microsoft Graph, choose Add next to Application Permissions and then select the permissions your app requires in the Select Permissions dialog.
The following screenshot shows the Select Permissions dialog for Microsoft Graph Application permissions.
Important: We recommend configuring the least privileged set of permissions required by your app. This provides a much more comfortable experience for administrators than having to consent to a long list of permissions.
You can rely on an administrator to grant the permissions your app needs at the Azure portal; however, often, a better option is to provide a sign-up experience for administrators by using the Azure AD v2.0 /adminconsent endpoint.
// Line breaks are for legibility only.
GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=http://localhost/myapp/permissions
| Parameter | Condition | Description |
|---|---|---|
| tenant | Required | The directory tenant that you want to request permission from. This can be in GUID or 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. |
| client_id | Required | The Application ID that the Application Registration Portal assigned to your app. |
| redirect_uri | Required | The redirect URI where you want the response to be sent for your app to handle. It must exactly match one of the redirect URIs that you registered in the portal, except that it must be URL encoded, and it can have additional path segments. |
| 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. |
Azure AD enforces that only a tenant administrator can sign in to complete the request. The administrator will be asked to approve all the Application permissions that you have requested for your app in the app registration portal. The following is an example of the consent dialog that Azure AD presents to the administrator:
If the administrator approves the permissions for your application, the successful response looks like this:
GET http://localhost/myapp/permissions?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=state=12345&admin_consent=True
| Parameter | Description |
|---|---|
| tenant | The directory tenant that granted your application the permissions that it requested, in GUID format. |
| 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. |
| admin_consent | Set to true. |
Try You can try this for yourself by pasting the request below in a browser. If you sign in as a Global administrator for an Azure AD tenant, you will be presented with the administrator consent dialog for the app. (This will be a different app than that in the consent dialog screenshot shown above.)
https://login.microsoftonline.com/common/adminconsent?client_id=6731de76-14a6-49ae-97bc-6eba6914391e&state=12345&redirect_uri=http://localhost/myapp/permissions
In the OAuth 2.0 Client Credentials Grant flow, you use the Application Id and Application Secret values that you saved when you registered your app to request an access token directly from the Azure AD v2.0 /token endpoint.
You specify the pre-configured permissions by passing https://graph.microsoft.com/.default as the value for the scope parameter in the token request. See the scope parameter description in the token request below for details.
You send a POST request to the /token v2.0 endpoint to acquire an access token:
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=qWgdYAmab0YSkuL1qKv5bPX&grant_type=client_credentials
| Parameter | Condition | Description |
|---|---|---|
| tenant | Required | The directory tenant that you want to request permission from. This can be in GUID or friendly name format. |
| client_id | Required | The Application ID that the Microsoft App Registration Portal assigned when you registered your app. |
| scope | Required | The value passed for the scope parameter in this request should be the resource identifier (Application ID URI) of the resource you want, affixed with the .default suffix. For Microsoft Graph, the value is https://graph.microsoft.com/.default. This value informs the v2.0 endpoint that of all the Application permissions you have configured for your app, it should issue a token for the ones associated with the resource you want to use. |
| client_secret | Required | The Application Secret that you generated for your app in the app registration portal. |
| grant_type | Required | Must be client_credentials. |
A successful response looks like this:
{
"token_type": "Bearer",
"expires_in": 3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
| Parameter | Description |
|---|---|
| access_token | The requested access token. Your app can use this token in calls to Microsoft Graph. |
| token_type | Indicates the token type value. The only type that Azure AD supports is bearer. |
| expires_in | How long the access token is valid (in seconds). |
Once you have an access token, you can use it to call Microsoft Graph by including it in the Authorization header of a request. The following request gets the profile of a specific user. Your app must have the User.Read.All permission to call this API.
GET https://graph.microsoft.com/v1.0/user/12345678-73a6-4952-a53a-e9916737ff7f
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com
A successful response will look similar to this (some response headers have been removed):
HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8
request-id: f45d08c0-6901-473a-90f5-7867287de97f
client-request-id: f45d08c0-6901-473a-90f5-7867287de97f
OData-Version: 4.0
Duration: 309.0273
Date: Wed, 26 Apr 2017 19:53:49 GMT
Content-Length: 407
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users/$entity",
"id":"12345678-73a6-4952-a53a-e9916737ff7f",
"businessPhones":[
"+1 555555555"
],
"displayName":"Chris Green",
"givenName":"Chris",
"jobTitle":"Software Engineer",
"mail":null,
"mobilePhone":"+1 5555555555",
"officeLocation":"Seattle Office",
"preferredLanguage":null,
"surname":"Green",
"userPrincipalName":"[email protected]"
}
Background services run on a server without the presence of a signed-in user and use the OAuth 2.0 Client Credentials Grant to authenticate with Azure AD and get a token. For the v2.0 endpoint, you can explore this scenario further with the following resources:
If you are using the Azure AD endpoint, there are some differences in the way that you configure your app and the way that it signs in to Azure AD:
/adminconsent), instead, your app can request administrator consent during runtime by adding the prompt=admin_consent parameter to an authorization request. For more information, see Triggering the Azure AD consent framework at runtime in Integrating applications with Azure Active Directory.scope parameter in Azure AD endpoint requests; instead, the resource parameter is used to specify the URI of the resource (resource=https://graph.microsoft.com) that authorization (for administrator consent) or a token is being requested for.For the Azure AD endpoint, you can explore this scenario further with the following resources: