Merge pull request #370 from Azure-Samples/shama/MultiTenant

Multi Tenant sample for Web App calling Web API

Author: Kalyan Krishna

.gitignore

@@ -1,7 +1,10 @@
 ################################################################################
 # This .gitignore file was automatically created by Microsoft(R) Visual Studio.
 ################################################################################
-
+.vs
+obj
+bin
+packages
 /.vs
 /obj
 /bin

1-WebApp-OIDC/README.md

@@ -1,23 +1,23 @@
 [![Build status](https://identitydivision.visualstudio.com/IDDP/_apis/build/status/AAD%20Samples/.NET%20client%20samples/ASP.NET%20Core%20Web%20App%20tutorial)](https://identitydivision.visualstudio.com/IDDP/_build/latest?definitionId=819)
 
-# Tutorial Phase - Enable your Web Apps to sign-in users
+# Chapter - Enable your Web app to sign-in users using the Microsoft Identity Platform
 
-## Scope of this phase
+## Objectives of this chapter
 
-In this phase of the tutorial, you will learn how to add sign-in users to your Web App, leveraging the Microsoft identity platform. You'll learn how to use the ASP.NET Core OpenID Connect (OIDC) middleware itself leveraging [Microsoft Identity Model extensions for .NET](https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/wiki) to protect your Web App.
+In this chapter of the tutorial, You'll learn how to use the [Microsoft.Identity.Web](https://aka.ms/microsoft-identity-web) to secure your Web App with the Microsoft Identity Platform..
 
    <img src="../ReadmeFiles/sign-in-audiences.png" width="50%"/>
 
-   Depending on your business needs, you have the flexibility to decide what type of users [(signInAudience)](https://docs.microsoft.com/azure/active-directory/develop/supported-accounts-validation) you wish to sign-in to your application:
+   Depending on your business needs, the platform offers you flexibility in terms of what type of users ([sign in audience](https://aka.ms/signinaudience)) can 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](./1-1-MyOrg) with their work or school accounts.
-   1. If you are an ISV, you'll want to [sign-in users from any organization](./1-2-AnyOrg), still with their work or school accounts.
-   1. If you are an ISV targeting both organizations and individuals, you'll want to [sign-in users with their work and school accounts or Microsoft personal accounts](./1-3-AnyOrgOrPersonal).
-   1. If you target organizations (work or school accounts), you can also enable your application to sign-in users in [national and sovereign clouds](./1-4-Sovereign).
-   1. If you wish to sign-in your customers or business partners to your app, you might  want to look into [sign-in users with their social identities](./1-5-B2C) using Microsoft Azure AD B2C.
-   1. Finally, you'll want to let users [sign-out](./1-6-SignOut) of our application, or from their browser session.
+   1. If you are a Line of Business (LOB) developer, you'd probably want to only [sign-in users in your organization](./1-1-MyOrg/README.md) with their work or school accounts.
+   1. If you are an ISV building a software-as-a-service (SaaS) application, you'd want to [sign-in users in any Azure AD tenant](./1-2-AnyOrg/README-1-1-to-1-2.md).
+   1. If you are an an ISV building a software-as-a-service (SaaS) application who wish to sign-in users from both Azure AD tenants and Microsoft consumer Accounts (MSA) you'll want to [sign-in users with their work and school accounts or Microsoft personal accounts](./1-3-AnyOrgOrPersonal/README-1-1-to-1-3.md).
+   1. If your application needs to sign-in users in Azure AD tenants in [national and sovereign clouds](./1-4-Sovereign/README.md).
+   1. If you application wants to connect with your customers, or with small business partners, you can have your application [sign-in users with their social identities](./1-5-B2C/README.md) using Microsoft Azure AD B2C.
+   1. Finally, you'll want to let users [sign-out](./1-6-SignOut/README.md) from your application, or globally from their browser session.
 
 ## Next chapters
 
-- If you signed-in users with Work or School accounts, or Microsoft personal accounts, you might want to learn how to call an API, starting with [Microsoft Graph](./2-WebApp-graph-user).
-- If you signed-in users with social identities, you might want to learn how to [call your own Web API directly](.\4-WebApp-your-API).
+- If you signed-in users with Work or School accounts, or Microsoft personal accounts, you might want to learn how to call an API, starting with [Microsoft Graph](./2-WebApp-graph-user/2-1-Call-MSGraph/README.md).
+- If you wish to protect your web APIs using the Microsoft Identity Platform, please look into [call your own Web API directly](./4-WebApp-your-API/4-1-MyOrg/README.md).

2-WebApp-graph-user/2-3-Multi-Tenant/README.md

@@ -15,15 +15,36 @@ products:
   - dotnet
   - CSharp
   - office-ms-graph
-description: "Build a multi-tenant SaaS web application that calls Microsoft Graph using Azure AD & OpenID Connect"
+description: "Protect a multi-tenant SaaS web application that calls Microsoft Graph using Azure AD & OpenID Connect"
 ---
 
-# Build a multi-tenant SaaS web application that calls Microsoft Graph using Azure AD & OpenID Connect
+# Protect a multi-tenant SaaS web application that calls Microsoft Graph using Azure AD & OpenID Connect
 
 > This sample is for Azure AD, not Azure AD B2C.
 
 [![Build status](https://identitydivision.visualstudio.com/IDDP/_apis/build/status/AAD%20Samples/.NET%20client%20samples/ASP.NET%20Core%20Web%20App%20tutorial)](https://identitydivision.visualstudio.com/IDDP/_build/latest?definitionId=819)
 
+- [About this sample](#about-this-sample)
+  - [Overview](#overview)
+- [Scenario](#scenario)
+- [How to run this sample](#how-to-run-this-sample)
+  - [Step 1:  Clone or download this repository](#step-1-clone-or-download-this-repository)
+  - [Step 2:  Register the sample application with your Azure Active Directory tenant](#step-2-register-the-sample-application-with-your-azure-active-directory-tenant)
+  - [Step 3:  Configure the sample to use your Azure AD tenant](#step-3-configure-the-sample-to-use-your-azure-ad-tenant)
+  - [Step 4: Run the sample](#step-4-run-the-sample)
+- [About The code](#about-the-code)
+  - [Usage of `/common` endpoint](#usage-of-common-endpoint)
+  - [Service principal provisioning for new tenants (onboarding process)](#service-principal-provisioning-for-new-tenants-onboarding-process)
+  - [Custom token validation allowing only registered tenants](#custom-token-validation-allowing-only-registered-tenants)
+  - [Partitioning data by tenant](#partitioning-data-by-tenant)
+  - [Acquiring Access token for Microsoft Graph for each tenant](#acquiring-access-token-for-microsoft-graph-for-each-tenant)
+- [Troubleshooting](#troubleshooting)
+  - [Error AADSTS650051](#error-aadsts650051)
+  - [Error `The provided request must include a 'response_type' input parameter`](#error-the-provided-request-must-include-a-response_type-input-parameter)
+- [Next Steps](#next-steps)
+- [Contributing](#contributing)
+- [Learn more](#learn-more)
+  
 ## About this sample
 
 This sample shows how to build an ASP.NET Core MVC web application that uses OpenID Connect to sign in users from multiple Azure AD tenants. Additionally it also introduces developers to the concept of a [multi-tenant](https://docs.microsoft.com/azure/active-directory/develop/single-and-multi-tenant-apps) Azure Active Directory application.
@@ -205,7 +226,7 @@ This sample is using the OpenID Connect ASP.NET Core middleware to sign in users
 
 You can trigger the middleware to send an OpenID Connect sign-in request by decorating a class or method with the `[Authorize]` attribute or by issuing a challenge (see the [AccountController.cs](https://github.com/aspnet/AspNetCore/blob/master/src/Azure/AzureAD/Authentication.AzureAD.UI/src/Areas/AzureAD/Controllers/AccountController.cs) file which is part of ASP.NET Core):
 
-These steps are encapsulated in the [Microsoft.Identity.Web](..\..\Microsoft.Identity.Web) project, and in particular in the [WebAppServiceCollectionExtensions.cs](..\..\Microsoft.Identity.Web\WebAppServiceCollectionExtensions.cs) file
+These steps are encapsulated in the [Microsoft.Identity.Web](https://github.com/AzureAD/microsoft-identity-web) project, and in particular in the [WebAppServiceCollectionExtensions.cs](https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web/WebAppExtensions/WebAppServiceCollectionExtensions.cs) file
 
 ### Usage of `/common` endpoint
 
@@ -288,7 +309,7 @@ services.Configure<OpenIdConnectOptions>(OpenIdConnectDefaults.AuthenticationSch
 });
 ```
 
-### Data partitioning by tenant
+### Partitioning data by tenant
 
 There are two common scenarios regarding data partition on a multi-tenant app. Having a separate database for each tenant or having a single database and using the **tenantId** to separate the data of each tenant. In this sample, we have taken the single database approach to save the ToDo items for all users from all tenants.
 
@@ -332,6 +353,10 @@ If you had provisioned a service principal of this app in the past and created a
 If you try to sign-in with a Microsoft account (MSA), such as hotmail.com, outlook.com, and msn.com, you'd receive this error during admin consent because MSA is not supported at the `/common` endpoint which this sample is using to obtain the admin consent.
 Please use an admin account with from the Azure AD tenant for this purpose.
 
+## Next Steps
+
+If your application topology comprises of multiple apps, for example a web API that the multi-tenant app will call, we recommend you also go through the [Protect a multi-tenant SaaS web application and a Web API which calls Microsoft Graph on-behalf of the user with the Microsoft Identity Platform](../../4-WebApp-your-API\4-3-AnyOrg/Readme.md) sample.
+
 ## Contributing
 
 If you'd like to contribute to this sample, see [CONTRIBUTING.MD](/CONTRIBUTING.md).
@@ -342,23 +367,24 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
 
 To learn more about single and multi-tenant apps
 
-- [Tenancy in Azure Active Directory](https://docs.microsoft.com/en-us/azure/active-directory/develop/single-and-multi-tenant-apps)
-- [How to: Sign in any Azure Active Directory user using the multi-tenant application pattern](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-convert-app-to-be-multi-tenant)
-- [Application and service principal objects in Azure Active Directory](https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals)
-- [National Clouds](https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud)
-- [Endpoints](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols#endpoints)
+- [Tenancy in Azure Active Directory](https://docs.microsoft.com/azure/active-directory/develop/single-and-multi-tenant-apps)
+- [How to: Sign in any Azure Active Directory user using the multi-tenant application pattern](https://docs.microsoft.com/azure/active-directory/develop/howto-convert-app-to-be-multi-tenant)
+- [Application and service principal objects in Azure Active Directory](https://docs.microsoft.com/azure/active-directory/develop/app-objects-and-service-principals)
+- [National Clouds](https://docs.microsoft.com/azure/active-directory/develop/authentication-national-cloud)
+- [Endpoints](https://docs.microsoft.com/azure/active-directory/develop/active-directory-v2-protocols#endpoints)
 - [Multi-tenant SaaS database tenancy patterns](https://docs.microsoft.com/azure/sql-database/saas-tenancy-app-design-patterns)
 
 To learn more about admin consent experiences
-- [Understanding Azure AD application consent experiences](https://docs.microsoft.com/en-us/azure/active-directory/develop/application-consent-experience)
-- [Understand user and admin consent](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-convert-app-to-be-multi-tenant#understand-user-and-admin-consent)
+
+- [Understanding Azure AD application consent experiences](https://docs.microsoft.com/azure/active-directory/develop/application-consent-experience)
+- [Understand user and admin consent](https://docs.microsoft.com/azure/active-directory/develop/howto-convert-app-to-be-multi-tenant#understand-user-and-admin-consent)
 
 To learn more about token validation, see
+
 - [Validating tokens](https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/wiki/ValidatingTokens)
-- [Validating an id_token](https://docs.microsoft.com/en-us/azure/active-directory/develop/id-tokens#validating-an-id_token)
+- [Validating an id_token](https://docs.microsoft.com/azure/active-directory/develop/id-tokens#validating-an-id_token)
 
 To understand more about app registration, see:
 
 - [Quickstart: Register an application with the Microsoft identity platform (Preview)](https://docs.microsoft.com/azure/active-directory/develop/quickstart-register-app)
-- [Quickstart: Configure a client application to access web APIs (Preview)](https://docs.microsoft.com/azure/active-directory/develop/quickstart-configure-app-access-web-apis)
-
+- [Quickstart: Configure a client application to access web APIs (Preview)](https://docs.microsoft.com/azure/active-directory/develop/quickstart-configure-app-access-web-apis)