Hopp over navigasjon

Build a multi-tenant daemon with the Azure AD v2.0 endpoint

Sist oppdatert: 22.11.2018
Rediger på GitHub

For a simpler console daemon application, check out the following sample: active-directory-dotnetcore-daemon-v2

About this sample

Overview

This sample application shows how to use the Azure AD v2.0 endpoint to access the data of Microsoft business customers in a long-running, non-interactive process. It uses the OAuth2 client credentials grant to acquire an access token, which can be used to call the Microsoft Graph and access organizational data.

The app is built as an ASP.NET 4.5 MVC application, using the OWIN OpenID Connect middleware to sign in users. Its "daemon" component is simply an API controller, which, when called, syncs a list of users from the customer's Azure AD tenant. This SyncController.cs is triggered by an ajax call in the web application, and uses the Microsoft Authentication Library (MSAL) Preview for .NET to acquire a token.

Scenario

Because the app is a multi-tenant app intended for use by any Microsoft business customer, it must provide a way for customers to "sign up" or "connect" the application to their company data. During the connect flow, a company administrator can grant application permissions directly to the app so that it can access company data in a non-interactive fashion, without the presence of a signed-in user. The majority of the logic in this sample shows how to achieve this connect flow using the v2.0 admin consent endpoint.

For more information on the concepts used in this sample, be sure to read the v2.0 endpoint client credentials protocol documentation.

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
  • One or more user accounts in your Azure AD tenant. This sample will not work with a Microsoft account (formerly Windows Live account). Therefore, if you signed in to the Azure portal with a Microsoft account and have never created a user account in your directory before, you need to do that now.

Step 1: Clone or download this repository

From your shell or command line:

git clone https://github.com/Azure-Samples/active-directory-dotnet-daemon-v2.git`

or download and exact 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

There is one project in this sample. To register it, you can:

  • either follow the steps in the paragraphs below (Step 2 and Step 3)
  • or use PowerShell scripts that:
    • automatically create for you the Azure AD applications and related objects (passwords, permissions, dependencies)
    • modify the Visual Studio projects' configuration files.

If you want to use this automation, read the instructions in App Creation Scripts

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 client app (dotnet-web-daemon-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 dotnet-web-daemon-v2.
    • In the Supported account types section, select Accounts in any organizational directory.
    • In the Redirect URI (optional) section, select Web in the combo-box.
    • For the Redirect URI, enter the base URL for the sample. By default, this sample uses https://localhost:44316/. Also add https://localhost:44316/Account/GrantPermissions as another redirect Uri.
    • Select Register to create the application.
  3. 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.
  4. In the list of pages for the app, select Authentication.
    • In the Advanced settings section set Logout URL to https://localhost:44316/Account/EndSession
    • In the Advanced settings | Implicit grant section, check Access tokens and ID tokens as this sample requires the Implicit grant flowto be enabled to sign-in the user, and call an API.
  5. Select Save.
  6. 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.
  7. 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 Application permissions section, ensure that the right permissions are checked: User.Read.All
    • Select the Add permissions button

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 client project

  1. Open the UserSync\Web.Config file
  2. Find the app key ida:ClientId and replace the existing value with the application ID (clientId) of the dotnet-web-daemon-v2 application copied from the Azure portal.
  3. Find the app key ida:ClientSecret and replace the existing value with the key you saved during the creation of the dotnet-web-daemon-v2 app, in the Azure portal.

Run the sample

Clean the solution, rebuild the solution, and run UserSync 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. This consent allows the application to ensure that you are a business user.

The application will then try to sync a list of users from your Azure AD tenant, via the Microsoft Graph. If it is unable to do so, it will ask you (the tenant administrator) to connect your tenant to the application.

The application will then ask for permission to read the list of users in your tenant.

When you grant the permission, the application will then be able to query for users at any point. You can verify this by clicking the Sync Users button on the users page, refreshing the list of users. Try adding or removing a user and resyncing the list (but note that it only syncs the first page of users!).

About the code

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

  • Initial sign-in: App_Start\Startup.Auth.cs, 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.
  • Syncing the list of users to the local in-memory store: Controllers\SyncController.cs
  • Displaying the list of users from the local in-memory store: Controllers\UserController.cs
  • Acquiring permissions from the tenant admin using the admin consent endpoint: Controllers\AccountController.cs

How to recreate this sample

Code for the service

  1. In Visual Studio 2017, create a new Visual C# ASP.NET Web Application (.NET Framework) project. In the next screen, choose the MVC project template. Also add folder and core references for Web API as you would be adding a Web API controller later. Leave the project's chosen authentication mode as the default, that is, No Authentication".
  2. Select the project in the Solution Explorer window and press the F4 key to bring project properties. In the project properties, set SSL Enabled to be True. Note the SSL URL. You will need it when configuring this application's registration in the Azure portal.
  3. Add the following ASP.Net OWIN middleware NuGets: Microsoft.Owin.Security.ActiveDirectory, Microsoft.Owin.Security.Cookies and Microsoft.Owin.Host.SystemWeb, Microsoft.IdentityModel.Protocol.Extensions, Microsoft.Owin.Security.OpenIdConnect and Microsoft.Identity.Client (preview). You will need to check the Include prerelease box to obtain the preview version of the Microsoft Authentication Library (MSAL) Preview for .NET library.
  4. In the App_Start folder, create a class Startup.Auth.cs.You will need to remove .App_Start from the namespace name. Replace the code for the Startup class with the code from the same file of the sample app. Be sure to take the whole class definition! The definition changes from public class Startup to public partial class Startup
  5. In Startup.Auth.cs resolve missing references by adding using statements as suggested by Visual Studio intellisense.
  6. Right-click on the project, select Add, select "Class", and in the search box enter "OWIN". "OWIN Startup class" will appear as a selection; select it, and name the class Startup.cs.
  7. In Startup.cs, replace the code for the Startup class with the code from the same file of the sample app. Again, note the definition changes from public class Startup to public partial class Startup.
  8. In the folder, add a new class called MsGraphUser.cs. Replace the implementation with the contents of the file of the same name from the sample.
  9. Add a new MVC 5 Controller - Empty called AccountController. Replace the implementation with the contents of the file of the same name from the sample.
  10. Add a new MVC 5 Controller - Empty called UserController. Replace the implementation with the contents of the file of the same name from the sample.
  11. Add a new Web API 2 Controller - Empty called SyncController. Replace the implementation with the contents of the file of the same name from the sample.
  12. For the user interface, in the Views\Account folder, add three Empty (without model) Views named GrantPermissions, Index and UserMismatch and one named Index in the Views\User folder. Replace the implementation with the contents of the file of the same name from the sample.
  13. Update the Shared\_Layout.cshtml and Home\Index.cshtml to correctly link the various views together.

Troubleshooting

If you are repeatedly asked to Grant permissions. See the note in SyncController on how to clear your token cache.

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 and bug in the sample, please raise the issue on GitHub Issues.

If you find a bug in msal.Net, please raise the issue on MSAL.NET 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 the underlying protocol:

For a simpler multi-tenant console daemon application, see active-directory-dotnetcore-daemon-v2