Certain actions in the Microsoft ecosystem are considered highly sensitive, such as deleting a user from a company's tenant, changing a user's password, or reading a list of groups in a company. Yet there are many valid reasons why applications need to perform these actions for their customers. For this reason, some permissions are considered admin restricted, and require a tenant administrator to approve their use in applications. This sample application shows how to use the Azure AD v2.0 endpoint to access data in the Microsoft Graph that requires administrative consent.
The app is built as an ASP.NET 4.5 MVC application, using the OWIN OpenID Connect middleware to sign-in users and the preview Microsoft Authentication Library (MSAL) to perform token acquisition. It uses an incremental consent pattern, in which it first requests a basic permission that an ordinary user can consent to; the ability to read a list of users in the user's organization. Then, when the user tries to read a list of groups in the user's organization, it asks the administrator for the necessary admin restricted permission. In this way, any Microsoft business user can sign up for the application without contacting their tenant administrator, and the tenant administrator is only involved when absolutely necessary.
For more information on the concepts used in this sample, be sure to read the v2.0 scope and permission reference.
Looking for previous versions of this code sample? Check out the tags on the releases GitHub page.
Follow the steps below to run the application and create your own multi-tenant web app. We recommend using Visual Studio 2015 to do so.
https://localhost:44321/, as well as
https://localhost:44321/Account/AADTenantConnected. These are the locations which the v2.0 endpoint will be allowed to return to after authentication.
If you have an existing application that you have registered in the past, feel free to use that instead of creating a new registration.
In order to request admin restricted permissions, you'll need to declare the permissions your app will use ahead of time. While still in the registration portal,
If you have issues saving the
offline_accessscopes, you can continue with the rest of the sample. This is a known issue that will be fixed shortly.
You can download this repo as a .zip file using the button above, or run the following command:
Once you've downloaded the sample, open it using Visual Studio. Open the
Utils\Globals.cs file, and replace the following values:
clientIdvalue with the application ID you copied above.
clientSecretvalue with the application secret you copied above.
Start the GroupManager application, and begin by signing in as an administrator in your Azure AD tenant. If you don't have an Azure AD tenant for testing, you can follow these instructions to get one.
When you sign in, the app will first ask you for permission to sign you in, read your user profile, and read a list of users in your tenant. Any user in your tenant will be able to consent to these permissions. The application will then show a list of users from your Azure AD tenant via the Microsoft Graph, on the Users page.
Then, navigate to the Groups page. The app will try to query the Microsoft Graph for a list of users in your tenant. If it is unable to do so, it will ask you (the tenant administrator) to connect your tenant to the application, providing permission to read groups in your tenant. Only administrators in your tenant will be able to consent to this permission. Once administrative consent is acquired, no other users in the tenant will be asked to consent to the app going forward.
The relevant code for this sample is in the following files: