services	platforms	author	level	client	service	endpoint
active-directory	dotnet	jmprieur	200	.NET Desktop (WPF)	ASP.NET Core Web API	AAD v2.0

Calling an ASP.NET Core Web API from a WPF application using Azure AD V2

About this sample

Scenario

You expose a Web API and you want to protect it so that only authenticated user can access it. You want to enable authenticated users with both work and school accounts or Microsoft personal accounts (formerly live account) to use your Web API.

An on demand video was created for the Build 2018 event, featuring this scenario and this sample. See the video Building Web API Solutions with Authentication, and the associated PowerPoint deck

Overview

This sample presents a Web API running on ASP.NET Core 2.0, protected by Azure AD OAuth Bearer Authentication. The Web API is exercised by a .NET Desktop WPF application. The .Net application uses the Active Directory Authentication Library MSAL.NET to obtain a JWT access token through the OAuth 2.0 protocol. The access token is sent to the ASP.NET Core Web API, which authenticates the user using the ASP.NET JWT Bearer Authentication middleware.

This sample is very similar to the active-directory-dotnet-native-aspnetcore sample except that that one is for the Azure AD V1 endpoint and the token is acquired using ADAL.NET, whereas this sample is for the V2 endpoint, and the token is acquired using MSAL.NET. The Web API was also modified to accept both V1 and V2 tokens.

User experience with this sample

The Web API (TodoListService) maintains an in-memory collection of to-do items per authenticated user. Several applications signed-in under the same identities share the same to-do list.

The WPF application (TodoListClient) enables a user to:

Sign in. The first time a user signs in, a consent screen is presented letting the user consent for the application accessing the TodoList Service and the Azure Active Directory.
When the user has signed-in, the user sees the list of to-do items exposed by Web API for the signed-in identity
The user can add more to-do items by clicking on Add item button.

Next time a user runs the application, the user is signed-in with the same identity as the application maintains a cache on disk. Users can clear the cache (which will also have the effect of signing them out)

How to run this sample

Pre-requisites

Install .NET Core for Windows by following the instructions at dot.net/core, which will include 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

Step 1: Clone or download this repository

From your shell or command line:

git clone https://github.com/Azure-Samples/active-directory-dotnet-native-aspnetcore-v2.git

Given that the name of the sample is pretty long, and so are the name of the referenced NuGet pacakges, 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 are two projects in this sample. Each needs to be separately registered in your Azure AD tenant. To register these projects, you can:

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

As a first step you'll need to:

Sign in to the Azure portal using either a work or school account or a personal Microsoft account.
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).
In the left-hand navigation pane, select the Azure Active Directory service, and then select App registrations (Preview).

Register the service app (TodoListService)

In App registrations (Preview) page, select New registration.
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 TodoListService.
- 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.
- For the Redirect URI, enter the base URL for the sample. By default, this sample uses https://localhost:44351/.
- Select Register to create the application.
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 (ClientId in TodoListService\appsettings.json).
In the list of pages for the app, select on Expose an API
- Select Add a scope
- accept the proposed Application ID URI (api://{clientId}) by selecting Save and Continue
- Enter the following parameters
  - for Scope name use access_as_user
  - Keep Admmins and users for Who can consent
  - in Admin consent display name type Access TodoListService as a user
  - in Admin consent description type Accesses the TodoListService Web API as a user
  - in User consent display name type Access TodoListService as a user
  - in User consent description type Accesses the TodoListService Web API as a user
  - Keep State as Enabled
  - Select Add scope

Register the client app (TodoListClient)

In App registrations (Preview) page, select New registration.
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 TodoListClient.
- In the Supported account types section, select Accounts in any organizational directory and personal Microsoft accounts (e.g. Skype, Xbox, Outlook.com).
- Select Register to create the application.
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 (ida:ClientId in TodoListClient\App.Config).
In the list of pages for the app, select Authentication.
- In the Redirect URLs | Suggested Redirect URLs for public clients (mobile, desktop) section, check urn:ietf:wg:oauth:2.0:oob
Select Save.
click on API permissions
- click the Add a permission button and then,
- Ensure that the My APIs tab is selected
- In the list of APIs, select the API TodoListService.
- In the Delegated permissions section, ensure that the right permissions are checked: access_as_user. Use the search box if necessary.
- Select the Add permissions button

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

Choose which users account to sign in

By default the sample is configured to enable users to sign in with any work and school accounts (AAD) or Microsoft Personal accounts (formerly live account). This is because ida:Tenant has the value of common.

Important note

common is not a proper tenant. It's just a convention to express that the accepted tenants are any Work and School organizations, or Personal Microsoft account (consumer accounts). Accepted tenants can have the following values:

Value	Meaning
`common`	users can sign in with any Work and School account, or Microsoft Personal account
`organizations`	users can sign in with any Work and School account
`consumers`	users can sign in with a Microsoft Personal account
a GUID or domain name	users can only sign in with an account for a specific organization described by its tenant ID (GUID) or domain name

Configure the TodoListService C# project

Open the solution in Visual Studio.
In the TodoListService project, open the appsettings.json file.
Find the ClientId property and replace the value with the Application ID (Client ID) property of the TodoListService-v2 application, that you registered earlier.
[Optional] if you want to limit sign-in to users in your organization, also update the following

The Domain property, replacing the existing value with your AAD tenant domain, for example, contoso.onmicrosoft.com.
The TenantId property replacing the existing value with the Tenant ID.

Configure the TodoListClient C# project

In the TodoListClient project, open App.config.
Find the app key ida:ClientId and replace the value with the ApplicationID (Client ID) for the TodoListClient-v2 app copied from the app registration page.
Find the app key todo:TodoListScope and replace the value with the scope of the TodoListService-v2 application copied from the app registration in the Expose an API tab (of the form api://<Application ID of service>/access_as_user if you followed the instructions above)
[Optional] If you want your application to work only in your organization (only in your tenant) you'll also need to Find the app key ida:Tenant and replace the value with your AAD Tenant ID (GUID). Alternatively you can also use your AAD tenant Name (for example, contoso.onmicrosoft.com)
[Optional] If you changed the default URL for your service application, find the app key todo:TodoListBaseAddress and replace the value with the base address of the TodoListService project.

Step 4: Run the sample

Clean the solution, rebuild the solution, and run it. You might want to go into the solution properties and set both projects as startup projects, with the service project starting first.

When you start the Web API from Visual Studio, depending on the browser you use, you'll get:

an empty web page (case with Edge)
or an error HTTP 401 (case with Chrome) This is expected as you are not authenticated. The WPF application will be authenticated, so it will be able to access the Web API.

Explore the sample by signing in into the TodoList client, adding items to the To Do list, removing the user account (clearing the cache), and starting again. As explained, if you stop the application without removing the user account, the next time you run the application, you won't be prompted to sign in again - that is because the sample implements a persistent cache for MSAL, and remembers the tokens from the previous run.

NOTE: Remember, the To-Do list is stored in memory in this TodoListService-v2 sample. Each time you run the TodoListService API, your To-Do list will get emptied.

How was the code created ?

Code for the service

The code for the service was created in the following way:

Create the web api using the ASP.NET templates

md TodoListService
cd TodoListService
dotnet new webapi -au=SingleOrg

Add a model (TodoListItem) and modify the controller

In the TodoListService project, add a folder named Models and then a file named TodoItem.cs with the following content:

namespace TodoListService.Models
{
    public class TodoItem
    {
        public string Owner { get; set; }
        public string Title { get; set; }
    }
}

Under the Controllers folder, rename the file ValuesController.cs to TodoListController.cs and copy the following content in this file:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.Linq;
using System.Security.Claims;
using TodoListService.Models;

namespace TodoListService.Controllers
{
    [Authorize]
    [Route("api/[controller]")]
    public class TodoListController : Controller
    {
        static ConcurrentBag<TodoItem> todoStore = new ConcurrentBag<TodoItem>();

        [HttpGet]
        public IEnumerable<TodoItem> Get()
        {
            string owner = (User.FindFirst(ClaimTypes.NameIdentifier))?.Value;
            return todoStore.Where(t => t.Owner == owner).ToList();
        }

        [HttpPost]
        public void Post([FromBody]TodoItem Todo)
        {
            string owner = (User.FindFirst(ClaimTypes.NameIdentifier))?.Value;
            todoStore.Add(new TodoItem { Owner = owner, Title = Todo.Title });
        }
    }
}

This code gets the todo list items associated with their owner, which is the identity of the user using the Web API. It also adds todo list items associated with the same user. There is no persistence as implementing token persistence on the service side would be beyond the scope of this sample

Make the following changes in the AzureAdServiceCollectionExtension.cs file.

using Microsoft.IdentityModel.Tokens;

The code of the overloaded `Configure` method is also modified to accept tokens coming from the V2 endpoint:

/// <summary>
/// Validate the issuer.
/// </summary>
/// <param name="issuer">Issuer to validate (will be tenanted)</param>
/// <param name="securityToken">Received Security Token</param>
/// <param name="validationParameters">Token Validation parameters</param>
/// <remarks>The issuer is considered as valid if it has the same http scheme and authority as the
/// authority from the configuration file, has a tenant Id, and optionally v2.0 (this web api
/// accepts both V1 and V2 tokens)</remarks>
/// <returns>The <c>issuer</c> if it's valid, or otherwise <c>null</c></returns>
private string ValidateIssuer(string issuer, SecurityToken securityToken, TokenValidationParameters validationParameters)
{
 Uri uri = new Uri(issuer);
 Uri authorityUri = new Uri(_azureOptions.Instance);
 string[] parts = uri.AbsolutePath.Split('/');
 if (parts.Length >= 2)
 {
  Guid tenantId;
  if (uri.Scheme != authorityUri.Scheme || uri.Authority != authorityUri.Authority)
  {
   throw new SecurityTokenInvalidIssuerException("Issuer has wrong authority");
  }
  if (!Guid.TryParse(parts[1], out tenantId))
  {
   throw new SecurityTokenInvalidIssuerException("Cannot find the tenant GUID for the issuer");
  }
  if (parts.Length> 2 && parts[2] != "v2.0")
  {
   throw new SecurityTokenInvalidIssuerException("Only accepted protocol versions are AAD v1.0 or V2.0");
  }
  return issuer;
 }
 else
 {
  throw new SecurityTokenInvalidIssuerException("Unknown issuer");
 }
}

public void Configure(string name, JwtBearerOptions options)
{
    options.Audience = _azureOptions.ClientId;
    options.Authority = $"{_azureOptions.Instance}{_azureOptions.TenantId}/v2.0/";

    // Instead of using the default validation (validating against a single tenant, as we do in line of business apps),
    // we inject our own multitenant validation logic (which even accepts both V1 and V2 tokens)
    options.TokenValidationParameters.ValidateIssuer = true;
    options.TokenValidationParameters.IssuerValidator = ValidateIssuer;
}

Change the App URL

If you're using Visual Studio 2017

Edit the TodoListService's properties (right click on TodoListService.csproj, and choose Properties)
In the Debug tab:
1. Check the Launch browser field to https://localhost:44351/api/todolist
2. Change the App URL field to be https://localhost:44351 as this is the URL registered in the Azure AD application representing the Web API.
3. Check the Enable SSL field

How to deploy this sample to Azure

This project has one WebApp / Web API projects. To deploy it to Azure Web Sites, you'll need to:

create an Azure Web Site
publish the Web App / Web APIs to the web site, and
update its client(s) to call the web site instead of IIS Express.

Create and Publish the `TodoListService` to an Azure Web Site

Sign in to the Azure portal.
Click Create a resource in the top left-hand corner, select Web + Mobile --> Web App, select the hosting plan and region, and give your web site a name, for example, TodoListService-contoso.azurewebsites.net. Click Create Web Site.
Once the web site is created, click on it to manage it. For this set of steps, download the publish profile by clicking Get publish profile and save it. Other deployment mechanisms, such as from source control, can also be used.
Switch to Visual Studio and go to the TodoListService project. Right click on the project in the Solution Explorer and select Publish. Click Import Profile on the bottom bar, and import the publish profile that you downloaded earlier.
Click on Settings and in the Connection tab, update the Destination URL so that it is https, for example https://TodoListService-contoso.azurewebsites.net. Click Next.
On the Settings tab, make sure Enable Organizational Authentication is NOT selected. Click Save. Click on Publish on the main screen.
Visual Studio will publish the project and automatically open a browser to the URL of the project. If you see the default web page of the project, the publication was successful.

Update the Active Directory tenant application registration for `TodoListService`

Navigate to the Azure portal.
On the top bar, click on your account and under the Directory list, choose the Active Directory tenant containing the TodoListService application.
On the applications tab, select the TodoListService application.
From the Settings -> Properties menu, update the Home page URL, to the address of your service, for example https://TodoListService-contoso.azurewebsites.net. Save the configuration.
Add the same URL in the list of values of the Settings -> Reply URLs menu

Update the `TodoListClient` to call the `TodoListService` running in Azure Web Sites

In Visual Studio, go to the TodoListClient project.
Open TodoListClient\App.Config. Only one change is needed - update the todo:TodoListBaseAddress key value to be the address of the website you published, for example, https://TodoListService-contoso.azurewebsites.net.
Run the client! If you are trying multiple different client types (for example, .Net, Windows Store, Android, iOS) you can have them all call this one published web API.

NOTE: Remember, the To-Do list is stored in memory in this TodoListService sample. Azure Web Sites will spin down your web site if it is inactive, and your To Do list will get emptied. Also, if you increase the instance count of the web site, requests will be distributed among the instances. To Do will, therefore, not be the same on each instance.

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

For more information, visit the following links:

To lean more about the application registration, visit:
To learn more about the code, visit Conceptual documentation for MSAL.NET and in particular:
- Acquiring tokens with authorization codes on web apps
- Customizing Token cache serialization
Articles about the Azure AD V2 endpoint http://aka.ms/aaddevv2, with a focus on:
- Azure Active Directory v2.0 and OAuth 2.0 On-Behalf-Of flow
Introduction to Identity on ASP.NET Core
- AuthenticationBuilder
- Azure Active Directory with ASP.NET Core

sivachamarthi/active-directory-dotnet-native-aspnetcore-v2