Build an app with admin restricted scopes using the v2.0 endpoint

Dernière mise à jour : 26/02/2019
Modifier sur GitHub

About this sample

Overview

Certain actions in the Azure Active Directory tenant are considered highly sensitive, such as deleting a user from the tenant, creating and managing applications, listing and assigning users to security groups. 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 consent for permissions that have an administrative scope.

Scenario

The app is built as an ASP.NET 4.5 MVC application, using the OWIN OpenID Connect middleware to sign-in users and uses the Microsoft Authentication Library (MSAL)] to perform token acquisition. It uses an incremental consent pattern, in which it first requests consent for a basic set of permission that an ordinary user can consent to themselves; like 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 will ask 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.

How to run this sample

To run this sample, you'll need:

  • Visual Studio 2017
  • An Internet connection
  • An Azure Active Directory (Azure AD) tenant. For more information on how to get an Azure AD tenant, see How to get an Azure AD tenant
  • A user account in your Azure AD tenant, or a Microsoft personal account. You need to have at least one account which is a directory administrator to test the features which require an administrator to consent.

Step 1: Clone or download this repository

From your shell or command line:

git clone https://github.com/Azure-Samples/active-directory-dotnet-admin-restricted-scopes-v2.git

or download and extract the repository .zip file.

Given that the name of the sample is pretty long, and so are the name of the referenced NuGet packages, you might want to clone it in a folder close to the root of your hard drive, to avoid file size limitations on Windows.

Step 2: Register the sample with your Azure Active Directory tenant

Choose the Azure AD tenant where you want to create your applications

As a first step you'll need to:

  1. Sign in to the Azure portal using either a work or school account or a personal Microsoft account.
  2. If your account gives you access to more than one tenant, select your account in the top right corner, and set your portal session to the desired Azure AD tenant (using Switch Directory).
  3. In the left-hand navigation pane, select the Azure Active Directory service, and then select App registrations (Preview).

Register the service app (restricted-scopes-v2)

  1. In App registrations (Preview) page, select New registration.
  2. When the Register an application page appears, enter your application's registration information:
    • In the Name section, enter a meaningful application name that will be displayed to users of the app, for example restricted-scopes-v2.
    • In the Supported account types section, select Accounts in any organizational directory and personal Microsoft accounts (e.g. Skype, Xbox, Outlook.com).
    • In the Redirect URI (optional) section, select Web in the combo-box and enter the following redirect URIs.
      • https://localhost:44321/
      • https://localhost:44321/Account/AADTenantConnected
  3. Select Register to create the application.
  4. On the app Overview page, find the Application (client) ID value and record it for later. You'll need it to configure the Visual Studio configuration file for this project.
  5. In the list of pages for the app, select Authentication.
    • In the Advanced settings section set Logout URL to https://localhost:44321/Account/EndSession
    • In the Advanced settings | Implicit grant section, check Access tokens and ID tokens as this sample requires the Implicit grant flow to be enabled to sign-in the user, and call an API.
  6. Select Save.
  7. From the Certificates & secrets page, in the Client secrets section, choose New client secret:

    • Type a key description (of instance app secret),
    • Select a key duration of either In 1 year, In 2 years, or Never Expires.
    • When you press the Add button, the key value will be displayed, copy, and save the value in a safe location.
    • You'll need this key later to configure the project in Visual Studio. This key value will not be displayed again, nor retrievable by any other means, so record it as soon as it is visible from the Azure portal.
  8. In the list of pages for the app, select API permissions

    • Click the Add a permission button and then,
    • Ensure that the Microsoft APIs tab is selected
    • In the Commonly used Microsoft APIs section, click on Microsoft Graph
    • In the Delegated permissions section, ensure that the right permissions are checked: openid, email, profile, offline_access, User.Read, Group.Read.All, User.ReadBasic.All. Use the search box if necessary.
    • Select the Add permissions button

If you have an existing application that you have registered in the past, feel free to use that instead of creating a new registration.

Step 3: Configure the sample to use your Azure AD tenant

In the steps below, "ClientID" is the same as "Application ID" or "AppId".

Open the solution in Visual Studio to configure the projects

Configure the project

  1. Open the Utils\Globals.cs file, and replace the following values:
  2. Replace the clientId value with the application ID you copied above during App Registration.
  3. Replace the clientSecret value with the application secret you copied above during App Registration.

Step 4: Run the sample

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 groups 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.

About the code

The relevant code for this sample is in the following files:

  • Initial sign-in & basic permissions: App_Start\Startup.Auth.cs and Controllers\AccountController.cs. In particular, the actions on the controller have an Authorize attribute, which forces the user to sign-in. The application uses the authorization code flow to sign-in the user. When the token is received (See method OnAuthorizationCodeReceived) in Startup.Auth.cs#L58-L65, the application gets the token, which MSAL.NET stores into the token cache (See the Utils\MsalSessionTokenCache class). Then, when the controllers need to access the graph, they get a token by calling their private method GetGraphAccessToken GetGraphAccessToken

  • Getting the list of users: Controllers\UsersController.cs

  • Getting the list of groups: Controllers\GroupsController.cs

  • Acquiring permissions from the tenant admin using the admin consent endpoint: Controllers\AccountController.cs

Community Help and Support

Use Stack Overflow to get support from the community. Ask your questions on Stack Overflow first and browse existing issues to see if someone has asked your question before. Make sure that your questions or comments are tagged with [adal msal dotnet].

If you find a bug in the sample, please raise the issue on GitHub Issues.

To provide a recommendation, visit the following User Voice page.

Contributing

If you'd like to contribute to this sample, see CONTRIBUTING.MD.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

More information

For more information, see MSAL.NET's conceptual documentation:

For more information about how OAuth 2.0 protocols work in this scenario and other scenarios, see Authentication Scenarios for Azure AD.