Repository files navigation

In this tutorial, you will learn, incrementally, how to add sign-in users to your Web App, and how to call Web APIs, both Microsoft APIs or your own APIs. 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 window. 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)

1. In the first chapter you learn how toadd signing-in users to your Web App with the Microsoft identity platform for developers (formerly Microsoft Entra ID v2.0). You'll learn how to use theMicrosoft.Identity.Web to secure your Web App with the Microsoft Identity Platform.

   

   Depending on your business needs, the platform offers you flexibility in terms of what type of users (sign in audience) can sign-in to your application:

   1. If you are a Line of Business (LOB) developer, you'd probably want to onlysign-in users in your organization with their work or school accounts.
   2. If you are an ISV building a software-as-a-service (SaaS) application, you'd want tosign-in users in any Microsoft Entra tenant.
   3. If you are an an ISV building a software-as-a-service (SaaS) application who wish to sign-in users from both Microsoft Entra tenants and Microsoft consumer Accounts (MSA) you'll want tosign-in users with their work and school accounts or Microsoft personal accounts.
   4. If your application needs to sign-in users in Microsoft Entra tenants innational and sovereign clouds.
   5. If your application wants to connect with your customers, or with small business partners, you can have your applicationsign-in users with their social identities using Microsoft Azure Active Directory B2C.
   6. Finally, you'll want to let userssign-out from your application, or globally from their browser session.

2. If your Web app only needs to sign-in users, in that case you have all you need from the options provided above, but if your app needs to call APIs that you've developed yourselves or popular Microsoft APIs like Microsoft Graph, then the following chapters will help extend your work so far to also call these Web APIs.

   

   Learn how to update your Web app tocall Microsoft Graph:

   1. We'd use the theMicrosoft.Identity.Web library again to extend the web app tosign-in users and also call Microsoft Graph
   2. In this chapter we'd explain the token cache and howcustomize the token cache serializationwith different technologies depending on your needs (in-memory cache, Session token cache, SQL Server Cache, Redis Cache)
   3. Learn how tosecure a multi-tenant SaaS application
   4. Learn how to call Microsoft Graph innational and sovereign clouds.
   5. Learn how toauthenticate users on both the frontend and backend side simultaneously using theHybrid SPA code flow and call Microsoft Graph.
   6. Learn how toauthenticate users on the backend side and share the authentication state with the frontend side using theBackend for Frontend proxy architecture and call Microsoft Graph.

3. Your Web App might also want to call other Web APIs than Microsoft Graph.

   

   Learn how tocall popular Azure APIs. This also explains how to handle conditional access, incremental consent and claims challenge:

   1. TheAzure Storage API. This is the opportunity to learn about incremental consent, and conditional access, and how to process them.
   2. TheAzure Service Management API. This is the opportunity to learn about admin consent.

   Note that that chapter, as compared to the others, requires you to have anAzure Subscription

4. If you wish to secure a Web API of your own, and call it from your clients (Web apps, desktop apps).

   

   • Learn how to secure your own Web API and update your Web App tocall your own web API
   • Learn how to update your B2C Web App tocall you own B2C web API
   • Learn how tosecure a multi-tenant SaaS application with its own Web API

5. 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 toadd authorization to your Web application, and driving business logic according to roles and group assignments.

   1. based on their application roles
   2. based on their belonging to Microsoft Entra groups

6. If you want todeploy your complete app to Azure. Learn how to do that, along with best practices to ensure security:

   1. Changing the app registration to add more ReplyUris.
   2. Using certificates instead of client secrets.
   3. UseManaged identities to get these certificates from KeyVault

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 seeBuild a daemon Web App with Microsoft Identity platform for developers

• Install .NET Core for Windows by following the instructions atdot.net/core, which will includeVisual Studio.
• a Microsoft Entra tenant. For more information on how to get a Microsoft Entra tenant, seeHow to get a Microsoft Entra tenant
• A user account in your Microsoft Entra tenant, or a Microsoft personal account

From your shell or command line:

git clone https://github.com/Azure-Samples/microsoft-identity-platform-aspnetcore-webapp-tutorial

⚠️ Given that the name of the sample is quite long, and so are the names of the referenced 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.

• We recommend that you start from chapter1. 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 chapter of the tutorial as the full code is provided in each folder.

UseStack 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 [msaldotnet].

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

To provide a recommendation, visit the followingUser Voice page.

Consider taking a moment to share your experience with us.

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

This project has adopted theMicrosoft Open Source Code of Conduct. For more information, see theCode of Conduct FAQ or contactopencode@microsoft.com with any additional questions or comments.

• The documentation for the Microsoft identity platform is available fromhttps://aka.ms/aadv2.
• Other samples for the Microsoft identity platform are available fromhttps://aka.ms/aaddevsamplesv2.
• The conceptual documentation for MSAL.NET is available fromhttps://aka.ms/msalnet.