services	platforms	author	level	client	service	endpoint
active-directory	dotnet	jmprieur	200	.NET native (WPF)	ASP.NET Core 2.0	AAD V2

Calling a 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 MSAL.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:

Navigate to the Application registration portal

Register the TodoListClient-v2 app

In the application registration portal, click Add an app
In the Register your application page, provide a name for your application for instance TodoListClient-v2
Press the Create button
In the registration page for your application, copy the application ID to the clipboard you will need it to configure the code for your application
Press the Save button at the bottom of the page.
In the Platforms section, click on the Add Platform button and then on Native application
Click on the My applications link at the top of the page to get back to the list of applications in the app registration portal

Register the TodoListService-v2 web API

In the application registration portal, click Add an app
In the Register your application page, provide a name for your application for instance TodoListService-v2
Press the Create button
In the registration page for your application, copy the application ID to the clipboard you will need it to configure the code for your application
In the Platforms section, click on the Add Platform button and then on Web API
Copy the scope proposed by default to access your web api as a user. It's in the form api://<Application ID>/access_as_user
In the Web API platform, in the Pre-authorized applications section click on Add application
In the application ID field, paste the application ID of the TodoListClient-v2 application as pasted from the registration
In the Scope field, click on the Select combo box and select the scope for this Web API api://<Application ID>/access_as_user
Press the Save button at the bottom of the page.

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 (of the form api://<Application ID of service>/access_as_user)
[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, you'll get an empty web page. This is expected.

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 New 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 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, and import the publish profile that you downloaded.
On 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 Publish.
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 and Settings -> Reply URLs menus, update the Sign-On URL, and Reply URL fields to the address of your service, for example https://TodoListService-contoso.azurewebsites.net. Save the configuration.

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

KalyanChanumolu-MSFT/active-directory-dotnet-native-aspnetcore-v2