Backend (Daemon) App calling API protected by Entra ID

Uncategorized

By Tsuyoshi Matsuzaki on 2016-10-07 • ( 59 Comments )

OAuth : App development working with Microsoft Entra ID (Azure AD)

1. Build Standard Web or Native Application
2. Build JavaScript Application
3. Build Backend Application (Daemon app, Service app)
4. How to Verify Token
5. Build Your Custom API Application
6. Workload Identity Federation

In this blog post, I’ll introduce you newly supported Entra ID client credential flow (with application permissions) in Entra ID endpoint, and describe details about how it works and how to use.

To simplify examples, we use Microsoft Graph in this post, but you can also use this flow for other application’s scopes. (See “Entra ID – How to use custom scopes for admin consent” for custom scopes.)

Note (Dec 2022) : As you can see in this post, the current app permission in Microsoft Graph is granted at a tenant-wide scope, but new RBAC permission model can limit the data an application can access using either of two resource scopes, management scopes or administrative units.
This new model will replace the current application permission in the future.
See here for the announcement.
(Microsoft Azure has already taken RBAC permission model.)

When to use Application Permissions ?

You should remember that application permissions are very strong and powerful permissions.

Imagine that you want to synchronize all user’s information in your organization between Entra ID and your custom application periodically. This app’s sync should work without login UI (i.e, as daemon or services) and access data of all Entra ID users (read/write).
With user flows (such as, code grant flow), of course, this is impossible.

The flow in this post uses the organization-level access privilege using a certificate or secret (app password) without interactive login UI, and can then access to all data in some organization (tenant) – such as, all users, all messages, all calendars, all files, all contacts, all registered devices, so on and so forth.
This client credential flow exactly helps these scenarios.

Note : Server-side backend logic with front-end application (such as, 3-tier web application) doesn’t need to use this flow. For these applications, you can use OAuth on-behalf-of flow in Entra ID (in which the user context is kept).

Application Registration

Before you start, you should register and configure your application.

First, you login to https://portal.azure.com/ (Azure Portal) and go to “Azure Active Directory”. In Entra ID management, click “App registrations” in the navigation, and then push “New registration” to register your app. In app registration wizard, be sure to select an option “Accounts in any organizational directory (Any Azure AD directory – Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)” (i.e, which means v2 application).
After the application is created (registered), you can get the application id in the application page. (See the following screenshot.)

In the application page, click “API permissions” in the navigation and push “Add a permission”. In the API permission pane, select “Microsoft Graph” and select “Files.Read.All” permission in “Application permissions” (not “Delegated permissions”) as the following screenshot.

Note : For other applications except for “Microsoft Graph”, please see “Entra ID – How to use custom scopes for admin consent“. (Added 02/07/2018)

Note : In the usual user consent’s flow, you don’t need to pre-define scopes in Azure Portal and you can set scopes dynamically (on the fly) when you authenticate.
As I explain later, this flow uses the pre-defined scope attached on your application.

Next click “Certificates & secrets” in the navigation, and add a new client secret (app password) to your app.

Lastly, set your application’s url as redirect URI in application page. (See the following screenshot.)
In this post, we assume https://localhost/testapp02 as redirect URI.

You application’s configuration is all done !

Admin Consent

We assume that this application (service) is multi-tenant application and share this service to user’s organization. How to deliver this application for each organization (tenant) ?

In this case, you can use the delivery mechanism called “consent”.
For example, if you use the Facebook integrated application, the application informs you operations (“read your friend list”, “create posts”, etc) the application is needing. If the user approve, the user can use this application. No extra setup is needed.
The application using Microsoft identity is having the same mechanism, and this is called “user consent” which grants the application to access your own data (your messages, your files, etc).

But as I wrote above, this application uses the all organization’s data, not for the specific user. In such a case, the “administrator consent” (admin consent) is used in Entra ID, and this consent must be done by the administrator in the organization.

Note : When you skip admin consent, access token will include neither scp (scope) nor roles. (And the request for calling API will then fail.)
Admin consent isn’t required when no Entra ID permission is used in the flow. If you want to avoid IT admin’s consent for granting to your application, you can skip this process (admin consent) by building its own role management (app-specific role and admin management) in your application without Entra ID permissions.
This approach is used in Microsoft Azure. Azure has its own role management framework, called Role-Based Access Control (RBAC), and the admin consent is not then required in client credential flow. (See here  for details.)

Note : The admin consent is not only for the application permissions, but also used for granting delegated permissions (user permissions) for all users in your organization (tenant).
With admin consent workflow enabled in Entra ID, the users can also request (ask) the admin consents to organization’s administrators.

When you use the administrator consent, all you have to do is to go to https://login.microsoftonline.com/{tenant name}/adminconsent?client_id={application id}&state={some state data}&redirect_uri={redirect uri} using web browser.
In this example, we go to the following url. (We assume the user tenant is testdirectory.onmicrosoft.com.)

https://login.microsoftonline.com/testdirectory.onmicrosoft.com/adminconsent?client_id=69f2b31d-d99d-4f9c-a27c-91c7be8d40b5&state=12345&redirect_uri=https%3a%2f%2flocalhost%2ftestapp02

Note : The state parameter is returned as the same value after login. Your application can use this data (state), if you want to keep some state after login.

If you access to the above url, the login screen (the following screenshot) is shown. Before using this application, the tenant administrator must login and permit to use this application only once, and the login is needed no longer.
When you are using v2.0 endpoint, you can use both Entra ID Account (organizational account) and Microsoft Account (personal account). But, in this case, this application needs the organization-level permission, then you must login using Entra ID tenant administrator’s account here. (If you use the other kind of account, the error occurs.)

After you login using the administrator account in Entra ID, the following consent screen is displayed. This screen says that if you grant to this application, this app takes the organization-level access privilege.

If you agree this consent, this application is granted to access your organization’s data. After that, the web page is redirected to {redirect uri}?admin_consent=True&tenant={tenant name}&state={state data}. In this example, this is the following url.

https://localhost/testapp02?admin_consent=True&tenant=testdirectory.onmicrosoft.com&state=12345

Note : If the error occurs, the page is redirected to the following uri.
http://localhost/testapp02?error=permission_denied&error_description=The+admin+canceled+the+request

If you (an administrator) don’t need this consented application in your tenant anymore, you can revoke this application using Azure Portal.
To revoke an admin-consented application, select “Enterprise applications” in the navigation (on Entra ID management page) and select this application in the list. (See the following screenshot.) In application page, select “Properties” and click “Delete” button.

Note : If you change your application permission in this application, the users (tenant administrators) must consent to this application again. (The user can consent many times.)

Get Access Token

Now it’s ready ! Your application can get the access token including permissions (scope or roles) and call some proper operations by the given permissions.

Your application can get access token using the following HTTP request (OAuth).
Note that you cannot use https://login.microsoftonline.com/common/oauth2/v2.0/token (which is commonly used) for getting the token. Instead, you must use https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token, which identifies the specific tenant. (In this example, we use “testdirectory.onmicrosoft.com” as user’s organization.)

The scope must be https://graph.microsoft.com/.default .
Remind that you can use the scope (permission) values on the fly in user authentication flow, such like https://graph.microsoft.com/mail.read. The .default scope in client credential flow means that the application uses the pre-defined scopes, i.e, Files.Read.All in this example. (See previous “Application Registration” section for pre-defined scopes.)

POST https://login.microsoftonline.com/testdirectory.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=69f2b31d-d99d-4f9c-a27c-91c7be8d40b5&client_secret=7XO2%2F%40...&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default

Your application can get the following HTTP response. The access token is used for calling APIs (services).

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "ext_expires_in": 0,
  "access_token": "eyJ0eXAiOi..."
}

Call Services (Microsoft Graph)

Lastly your application calls the service of Microsoft Graph using the provided access token.
In this example, the “Files.Read.All” permission is used for your application, then your application can read the all user’s files using Microsoft Graph in the given organization (testdirectory.onmicrosoft.com).
The following is retrieving all files in the OneDrive root folder for the user “demouser01@testdirectory.onmicrosoft.com”. The result is returning the two folder items.
Your application can get the files of arbitrary users in the organization in the same way.

HTTP Request

GET https://graph.microsoft.com/v1.0/users/demouser01@testdirectory.onmicrosoft.com/drive/root/children
Accept: application/json
Authorization: Bearer eyJ0eXAiOi...

HTTP Response

HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('demouser01%40testdirectory.onmicrosoft.com')/drive/root/children",
  "value": [
    {
      "createdBy": {
        "user": {
          "id": "cf258756-2623-47cb-be46-c85d436265bb",
          "displayName": "Demo Taro"
        }
      },
      "createdDateTime": "2015-12-22T07:24:46Z",
      "eTag": ""{4C06E4DE-B89C-4A78-848A-FCC6118041F6},1"",
      "id": "01B6UXIPO64QDEZHFYPBFIJCX4YYIYAQPW",
      "lastModifiedBy": {
        "user": {
          "id": "cf258756-2623-47cb-be46-c85d436265bb",
          "displayName": "Demo Taro"
        }
      },
      "lastModifiedDateTime": "2016-05-23T11:45:24Z",
      "name": "testfol",
      "webUrl": "https://o365directory-my.sharepoint.com/personal/demouser01_o365directory_onmicrosoft_com/Documents/testfol",
      "cTag": ""c:{4C06E4DE-B89C-4A78-848A-FCC6118041F6},0"",
      "folder": {
        "childCount": 2
      },
      "parentReference": {
        "driveId": "b!iXgvhy0l90q10oljtqrTKLCkDzZ204FFhgSqDnNXhktfZNOb9jHxQrzimH24Z67t",
        "id": "01B6UXIPN6Y2GOVW7725BZO354PWSELRRZ",
        "path": "/drive/root:"
      },
      "size": 0
    },
    {
      "createdBy": {
        "user": {
          "id": "cf258756-2623-47cb-be46-c85d436265bb",
          "displayName": "Demo Taro"
        }
      },
      "createdDateTime": "2016-05-20T12:57:32Z",
      "eTag": ""{2135DDF2-5458-49E6-8C8E-2AB08501A7E4},1"",
      "id": "01B6UXIPPS3U2SCWCU4ZEYZDRKWCCQDJ7E",
      "lastModifiedBy": {
        "user": {
          "id": "cf258756-2623-47cb-be46-c85d436265bb",
          "displayName": "Demo Taro"
        }
      },
      "lastModifiedDateTime": "2016-05-20T13:04:11Z",
      "name": "expense",
      "webUrl": "https://o365directory-my.sharepoint.com/personal/demouser01_o365directory_onmicrosoft_com/Documents/expense",
      "cTag": ""c:{2135DDF2-5458-49E6-8C8E-2AB08501A7E4},0"",
      "folder": {
        "childCount": 2
      },
      "parentReference": {
        "driveId": "b!iXgvhy0l90q10oljtqrTKLCkDzZ204FFhgSqDnNXhktfZNOb9jHxQrzimH24Z67t",
        "id": "01B6UXIPN6Y2GOVW7725BZO354PWSELRRZ",
        "path": "/drive/root:"
      },
      "size": 0
    }
  ]
}

Using Microsoft Authentication Library (MSAL)

Microsoft Authentication Library (MSAL) is the library that helps you to develop applications that work with v2.0 endpoint. Now this also supports this scenarios.

The following is the C# MSAL sample code, which gets the access token for this application permission’s scenario.
You must install the NuGet package “Microsoft.Identity.Client” (Microsoft Authentication Library, MSAL) in your project.

using Microsoft.Identity.Client;

static void Main(string[] args)
{
  // get access token including application permissions
  ConfidentialClientApplication cl = new ConfidentialClientApplication(
    "https://login.microsoftonline.com/testdirectory.onmicrosoft.com/v2.0",
    "69f2b31d-d99d-4f9c-a27c-91c7be8d40b5",
    "https://localhost/testapp02",
    new ClientCredential("7XO2/@=t@a..."),
    new TokenCache());
  AuthenticationResult authResult = cl.AcquireTokenForClient(
    new string[] { "https://graph.microsoft.com/.default" },
    null).Result;

  Console.WriteLine(authResult.Token);
  Console.ReadLine();
}

 

Update History :

Dec 04, 2019 Update App Registration Portal (https://apps.dev.microsoft.com) to Azure Portal, because of App Registration Portal deprecation

 

Categories: Uncategorized

Tagged as: Identity