Sovereign Tutorial Update (#81)

* Sovereign Tutorial

* Comments Fixed

* appsetiings.jason updates

* MS Graph folder for Sovereign scenarios

Author: negoe

1-WebApp-OIDC/1-4-Sovereign/README.md

@@ -1,7 +1,7 @@
 ---
 services: active-directory
 platforms: dotnet
-author: jmprieur
+author: negoe
 level: 100
 client: ASP.NET Core Web App
 endpoint: AAD v2.0
@@ -10,57 +10,60 @@ endpoint: AAD v2.0
 
 ## Scenario
 
-This sample shows how to build a .NET Core 2.2 MVC Web app that uses OpenID Connect to sign in users. Users can only sign-in with their `work and school` accounts in their organization **belonging to national or sovereign clouds**. It leverages the ASP.NET Core OpenID Connect middleware.
+This sample shows how to build a .NET Core 2.2 MVC Web app that uses OpenID Connect to sign in users. Users can only sign in with their `work and school` accounts in their organization **belonging to national or sovereign clouds**. This sample use  US Government cloud scenario. It leverages the ASP.NET Core OpenID Connect middleware.
 
 ![Sign in with Azure AD](ReadmeFiles/sign-in.png)
 
+National clouds (aka Sovereign clouds) are physically isolated instances of Azure. These regions of Azure are designed to make sure that data residency, sovereignty, and compliance requirements are honored within geographical boundaries.
 
+In addition to the public cloud​, Azure Active Directory is deployed in the following National clouds:  
 
-Note that, enabling your application for sovereign clouds requires you to:
+- Azure US Government
+- Azure China 21Vianet
+- Azure Germany
+
+Note that enabling your application for sovereign clouds requires you to:
 
 - register your application in a specific portal, depending on the cloud
 - use a specific authority, depending on the cloud in the config file for your application
 - in case you want to call the graph, this requires a specific Graph endpoint URL, depending on the cloud.
 
 More details in [Authentication in National Clouds](https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud)
 
-> This part of the tutorial is work in progress.
 
-<!-- ## How to run this sample
 
-To run this sample:
+## How to run this sample
 
-> Pre-requisites: Install .NET Core 2.2 or later (for example for Windows) by following the instructions at [.NET and C# - Get Started in 10 Minutes](https://www.microsoft.com/net/core). In addition to developing on Windows, you can develop on [Linux](https://www.microsoft.com/net/core#linuxredhat), [Mac](https://www.microsoft.com/net/core#macos), or [Docker](https://www.microsoft.com/net/core#dockercmd).
+To run this sample:
 
-### Step 1: Register the sample with your Azure AD tenant
+> Pre-requisites: Install .NET Core 2.2 or later (for example for Windows) by following the instructions at [.NET and C# - Get Started in 10 Minutes](https://www.microsoft.com/net/core). In addition to developing on Windows, you can develop on [Linux](https://ww w.microsoft.com/net/core#linuxredhat), [Mac](https://www.microsoft.com/net/core#macos), or [Docker](https://www.microsoft.com/net/core#dockercmd).
 
-There is one project in this sample. To register it, you can:
 
-- either use PowerShell scripts that **automatically** creates the Azure AD applications and related objects (passwords, permissions, dependencies) for you and modify the Visual Studio projects' configuration files. If you want to use this automation:
+### Step 1: Download/Clone this sample code 
+This sample was created from the dotnet core 2.2 [dotnet new mvc](https://docs.microsoft.com/dotnet/core/tools/dotnet-new?tabs=netcore2x) template with `SingleOrg` authentication, and then tweaked to let it support tokens for the Azure AD V2 endpoint.
 
-  1. On Windows run PowerShell and navigate to the solution's folder
-  2. In PowerShell run:
+You can clone this sample from your shell or command line:
 
-  ```PowerShell
-  Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
+  ```console
+git clone https://github.com/Azure-Samples/microsoft-identity-platform-aspnetcore-webapp-tutorial webapp
+cd webapp
+cd "1-WebApp-OIDC/1-4-Sovereign"
   ```
 
-  3. Run the script to create your Azure AD application and configure the code of the sample application accordinly
-
-  ```PowerShell
-  .\AppCreationScripts\Configure.ps1
-  ```
+> Given that the name of the sample is very long, and so are the name of the referenced NuGet 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.
 
-   > Other ways of running the scripts are described in [App Creation Scripts](./AppCreationScripts/AppCreationScripts.md)
+### Step 2: Register the sample with your Azure AD tenant
 
-  4. Open the Visual Studio solution and click start. That's it!
+1. Sign in to the [US Government Azure portal](https://portal.azure.us)
+    
+    - For registering your app in other National Clouds go to [App Registration endpoints](https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud#app-registration-endpoints) of the National Cloud of your choice using either a work or school account.
 
-- or, if you don't want to use automation, follow the steps below:
+> Note: Azure Germany doesn't support **App registrations (Preview)* experience.
 
-#### Choose the Azure AD tenant where you want to create your applications
+2. Choose the Azure AD tenant where you want to create your applications
+      - If your account is present in more than one Azure AD tenant, select profile button at the top-right corner in the menu on top of the page and select `Switch Directory`.
+      - On `Directory + Subscription` switch your portal session to the desired Azure AD tenant.
 
-1. Sign in to the [Azure portal](https://portal.azure.com) using either a work or school account or a personal Microsoft account.
-1. If your account is present in more than one Azure AD tenant, select `Directory + Subscription` at the top right corner in the menu on top of the page, and switch your portal session to the desired Azure AD tenant.
 1. In the left-hand navigation pane, select the **Azure Active Directory** service, and then select **App registrations (Preview)**.
 1. In **App registrations (Preview)** page, select **New registration**.
 1. When the **Register an application page** appears, enter your application's registration information:
@@ -74,33 +77,21 @@ There is one project in this sample. To register it, you can:
 1. In the list of pages for the app, select **Authentication**.
    - In the **Redirect URIs**, add a redirect URL of type Web and valued  `https://localhost:44321/signin-oidc`
    - In the **Advanced settings** section set **Logout URL** to `https://localhost:44321/signout-oidc`
-   - In the **Advanced settings** | **Implicit grant** section, check **ID tokens** as this sample requires the [Implicit grant flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-implicit-grant-flow) to be enabled to sign-in the user.
+   - In the **Advanced settings** | **Implicit grant** section, check **ID tokens** as this sample requires the [Implicit grant flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-implicit-grant-flow) to be enabled to sign in the user.
    - Select **Save**.
 
 > Note that unless the Web App calls a Web API no certificate or secret is needed.
 
-### Step 2: Download/ Clone this sample code or build the application using a template
-
-This sample was created from the dotnet core 2.2 [dotnet new mvc](https://docs.microsoft.com/dotnet/core/tools/dotnet-new?tabs=netcore2x) template with `SingleOrg` authentication, and then tweaked to let it support tokens for the Azure AD V2 endpoint. You can clone/download this repository or create the sample from the command line:
-
-#### Option 1: Download/ clone this sample
-
-You can clone this sample from your shell or command line:
-
-  ```console
-git clone https://github.com/Azure-Samples/microsoft-identity-platform-aspnetcore-webapp-tutorial webapp
-cd webapp
-cd "1-WebApp-OIDC\1-1-MyOrg"
-  ```
-
-> Given that the name of the sample is very long, and so are the name of the referenced NuGet 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.
+### Step 3: Configure your App
 
-  In the **appsettings.json** file:
+#### Option 1:  In the **appsettings.json** file:
 
-  - replace the `ClientID` value with the *Application ID* from the application you registered in Application Registration portal on *Step 1*.
-  - replace the `TenantId` value with he *Tenant ID* where you registered your Application on *Step 1*.
+  - replace the `Instance` value with the relevant authority value of the US Government cloud that is `https://login.microsoftonline.us`
+      - For other National Clouds go to [List of authority of National Clouds](https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud#azure-ad-authentication-endpoints)
+  -  replace the `ClientID` value with the *Application ID* from the application you registered in Application Registration portal on *Step 2*.
+  - replace the `TenantId` value with the *Tenant ID* where you registered your Application on *Step 2*.
 
-#### Option 2: Create the sample from the command line
+#### Option 2: Create and configure sample from the command line
 
 1. Run the following command to create a sample from the command line using the `SingleOrg` template:
 
@@ -111,7 +102,7 @@ cd "1-WebApp-OIDC\1-1-MyOrg"
     > Note: Replace *`Enter_the_Application_Id_here`* with the *Application Id* from the application Id you just registered in the Application Registration Portal and *`<yourTenantId>`* with the *Directory (tenant) ID* where you created your application.
 
 1. Open the generated project (.csproj) in Visual Studio, and save the solution.
-1. Add the `Microsoft.Identity.Web.csproj` project which is located at the root of this sample repo, to your solution (**Add Existing Project ...**). It's used to simplify signing-in and, in the next tutorial phases, to get a token
+1. Add the `Microsoft.Identity.Web.csproj` project, which is located at the root of this sample repo, to your solution (**Add Existing Project ...**). It's used to simplify signing-in and, in the next tutorial phases, to get a token
 1. Add a reference from your newly generated project to `Microsoft.Identity.Web` (right click on the **Dependencies** node under your new project, and choose **Add Reference ...**, and then in the projects tab find the `Microsoft.Identity.Web` project)
 1. Open the **Startup.cs** file and:
 
@@ -134,7 +125,7 @@ cd "1-WebApp-OIDC\1-1-MyOrg"
             services.AddAzureAdV2Authentication(Configuration);
      ```
 
-     This enables your application to use the Microsoft identity platform (fomerly Azure AD v2.0) endpoint. This endpoint is capable of signing-in users both with their Work and School and Microsoft Personal accounts.
+     This enables your application to use the Microsoft identity platform (formerly known as Azure AD v2.0) endpoint. This endpoint is capable of signing-in users both with their Work and School and Microsoft Personal accounts.
 
     1. Change the `Properties\launchSettings.json` file to ensure that you start your web app from <https://localhost:44321> as registered. For this:
     - update the `sslPort` of the `iisSettings` section to be `44321`
@@ -146,13 +137,13 @@ cd "1-WebApp-OIDC\1-1-MyOrg"
 
 2. Open your web browser and make a request to the app. Accept the IIS Express SSL certificate if needed. The app immediately attempts to authenticate you via the Azure AD v2 endpoint. Sign in with your personal account or with work or school account.
 
-## Toubleshooting
+## Troubleshooting
 
 ### known issue on iOS 12
 
-ASP.NET core applications create session cookies that represent the identity of the caller. Some Safari users using iOS 12 had issues which are described in [ASP.NET Core #4467](https://github.com/aspnet/AspNetCore/issues/4647) and the Web kit bugs database [Bug 188165 - iOS 12 Safari breaks ASP.NET Core 2.1 OIDC authentication](https://bugs.webkit.org/show_bug.cgi?id=188165). 
+ASP.NET core applications create session cookies that represent the identity of the caller. Some Safari users using iOS 12 had issues, which are described in [ASP.NET Core #4467](https://github.com/aspnet/AspNetCore/issues/4647) and the Web kit bugs database [Bug 188165 - iOS 12 Safari breaks ASP.NET Core 2.1 OIDC authentication](https://bugs.webkit.org/show_bug.cgi?id=188165). 
 
-If your web site needs to be accessed from users using iOS 12, you probably want to disable the SameSite protection, but also ensure that state changes are protected with CSRF anti-forgery mecanism. See the how to fix section of [Microsoft Security Advisory: iOS12 breaks social, WSFed and OIDC logins #4647](https://github.com/aspnet/AspNetCore/issues/4647)
+If your web site needs to be accessed from users using iOS 12, you probably want to disable the SameSite protection, but also ensure that state changes are protected with CSRF anti-forgery mechanism. See the how to fix section of [Microsoft Security Advisory: iOS12 breaks social, WSFed, and OIDC logins #4647](https://github.com/aspnet/AspNetCore/issues/4647)
 
 ## About The code
 
@@ -162,7 +153,7 @@ This sample shows how to use the OpenID Connect ASP.NET Core middleware to sign
 - Processing OpenID Connect sign-in responses by validating the signature and issuer in an incoming JWT, extracting the user's claims, and putting the claims in `ClaimsPrincipal.Current`.
 - Integrating with the session cookie ASP.NET Core middleware to establish a session for the user.
 
-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):
+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):
 
 
 The middleware in this project is created as a part of the open-source [ASP.NET Core Security](https://github.com/aspnet/aspnetcore) project.
@@ -171,7 +162,7 @@ These steps are encapsulated in the [Microsoft.Identity.Web](..\..\Microsoft.Ide
 
 ## Next steps
 
-- Learn how to enable [any organization](../1-2-AnyOrg) or [any Microsoft accounts](../1-3-AnyOrgOrPersonal) to sign-in
+- Learn how to enable [any organization](../1-2-AnyOrg) or [any Microsoft accounts](../1-3-AnyOrgOrPersonal) to sign in
 - Learn how to enable your [Web App to call a Web API on behalf of the signed-in user](../../2-WebApp-graph-user)
 
 ## Learn more

1-WebApp-OIDC/1-4-Sovereign/appsettings.json

@@ -1,6 +1,6 @@
 {
   "AzureAd": {
-    "Instance": "https://login.microsoftonline.com/",
+    "Instance": "[Enter the right Azure AD authentication endpoints, e.g. for US Government https://login.microsoftonline.us]",
     "Domain": "[Enter the domain of your tenant, e.g. contoso.onmicrosoft.com]",
     "TenantId": "[Enter 'common', or 'organizations' or the Tenant Id (Obtained from the Azure portal. Select 'Endpoints' from the 'App registrations' blade and use the GUID in any of the URLs), e.g. da41245a5-11b3-996c-00a8-4d99re19f292]",
     "ClientId": "[Enter the Client Id (Application ID obtained from the Azure portal), e.g. ba74781c2-53c2-442a-97c2-3d60re42f403]",

2-WebApp-graph-user/2-4-Sovereign-Call-MSGraph/.gitignore

@@ -0,0 +1,3 @@
+./vs
+./obj
+./bin