services	platforms	author	level	client	service	endpoint
active-directory	dotnet	jmprieur	200	ASP.NET Core .Web App	Microsoft Graph, Azure Storage, ASP.NET Core Web API	AAD v2.0

Tutorial - Enable your Web Apps to sign-in users and call APIs with the Microsoft identity platform for developers

About this tutorial

Scope of this tutorial

In this tutorial, you will learn, incrementally, how to add sign-in users to your Web App, and how to call Web APIs, either from Microsoft or your own. Finally, you'll learn best practices and how to deploy your app to Azure

Note

We recommend that you right click on the picture above and open it in a new tab, or a new windows. You'll see a clickable image:

clicking on a metro/railway station will get you directly to the README.md for the corresponding part of the tutorial (some are still in progress)

clicking on some of the connectors between stations will get you to an incremental README.md showing how to get from one part of the tutorial to the next (that's for instance the case for the Sign-in ... stations)

Details of the phases

The first phase is to add sign-in to your Web App leveraging the Microsoft identity platform for developers (fomerly Azure AD v2.0). You'll learn how to use the ASP.NET Core OpenID Connect (OIDC) middleware itself leveraging Microsoft Identity Model extensions for .NET to protect your Web App.

Depending on your business needs, you have the flexibility to decide which audience to sign-in to your application:
1. If you are a Line of Business (LOB) developer, you'll want to sign-in users in your organization with their work or school accounts.
2. If you are an ISV, you'll want to sign-in users in any organization, still with their work or school accounts.
3. If you are an ISV targetting both organizations and individuals, you'll want to sign-in users with their work and school accounts or Microsoft personal accounts.
4. LOB developer or ISV, if you target organizations (work or school accounts), you can also enable your application to sign-in users in [in progress] national and sovereign clouds.
5. If you are a business wanting to connect with your customers, or with small business partners, you might also want to [coming soon] sign-in users with their social identities using Microsoft Azure AD B2C.
6. Finally, you'll want to let users sign-out of our application, or globally of the browser.
Your Web App might maintain its own resources (in that case you have all you need so far), but it could also be that it calls Microsoft APIs.

Learn how to update your Web App to call Microsoft Graph:
1. Using the authorization code flow, initiated by ASP.NET Core, but completed by Microsoft Authentication Library for .NET (MSAL.NET)
2. Learn how to customize the token cache serialization ) with different technologies depending on your needs (in memory cache, Session token cache, SQL Cache, Redis Cache)
3. Learn the [coming soon] best practices and practices to avoid when calling an API.
Your Web App might also want to call other Web APIs than Microsoft Graph.

Learn how to call several Microsoft APIS, feature conditional access and claims challenge:
1. the Azure Storage API. This is the opportunity to learn about incremental consent, and conditional access, and how to process them.
2. the Azure ARM API. This is the opportunity to learn about admin consent.
[Planned] [coming soon] Then you might yourself have written a Web API, and want to call it from your Web App.
[Planned] [*in progress] Once you know how to sign-in users and call Web APIs from your Web App, you might want to restrict part of the application depending on the user having a role in the application or belonging to a group. So far you've learnt how to add and process authentication. Now learn how to add authorization to your Web application:
1. with application roles
2. with Azure AD groups
[Planned][coming soon] Chances are that you want to deploy your complete app to Azure. Learn how to do that, applying best practices:
1. Changing the app registration to add more ReplyUris
2. Using certificates instead of client secrets
3. Possibly leveraging Managed identities to get these certificates from KeyVault

Reusable code for your Web Apps and Web APIs

In this tutorial, the complexities of ASP.NET Core OpenID connect middleware and MSAL.NET are encapsulated into a library project that you can reuse in your own code, to make it easier to build your Web Apps on top of Microsoft identity platform for developers: Microsoft.Identity.Web

Daemon apps - Out of scope

This tutorial only covers the case the Web App calls a Web API on behalf of a user. If you are interested in Web Apps calling Web APIs with their own identity (daemon Web Apps), please see Build a daemon Web App with Microsoft Identity platform for developers

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/microsoft-identity-platform-aspnetcore-webapp-tutorial webapp
cd webapp

Given that the name of the sample is pretty long, that it has sub-folders 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.

We recommend that you start by the first part 1. WebApp signs-in users with Microsoft identity (OIDC) where you will learn how to sign-in users within your own organization
It's however possible to start at any phase of the tutorial as the full code is provided in each folder.

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.

jhattat/SampleAzureAD