Merge pull request #149 from Azure-Samples/shama-k/Master+MIW2.0+ReadMePoP

Implementation and Readme Changes

Author: Shama-K

1. Desktop app calls Web API/AppCreationScripts/AppCreationScripts.md

@@ -1,4 +1,4 @@
-# Registering the sample apps with Microsoft Identity Platform and updating the configuration files using PowerShell scripts
+# Registering the sample apps with Microsoft identity platform and updating the configuration files using PowerShell scripts
 
 ## Overview
 
@@ -11,7 +11,8 @@
    ```
 1. Run the script to create your Azure AD application and configure the code of the sample application accordingly. (Other ways of running the scripts are described below)
    ```PowerShell
-   .\AppCreationScripts\Configure.ps1
+   cd .\AppCreationScripts\
+   .\Configure.ps1
    ```
 1. Open the Visual Studio solution and click start
 
@@ -26,6 +27,7 @@ The following paragraphs:
   - [Passing credentials](#option-2-non-interactive) to create the app in your home tenant
   - [Interactively in a specific tenant](#option-3-interactive-but-create-apps-in-a-specified-tenant)
   - [Passing credentials in a specific tenant](#option-4-non-interactive-and-create-apps-in-a-specified-tenant)
+  - [Passing environment name, for Sovereign clouds](#running-the-script-on-azure-sovereign-clouds)
 
 ## Goal of the scripts
 
@@ -49,7 +51,7 @@ These scripts are:
 
 The `Configure.ps1` will stop if it tries to create an Azure AD application which already exists in the tenant. For this, if you are using the script to try/test the sample, or in DevOps scenarios, you might want to run `Cleanup.ps1` just before `Configure.ps1`. This is what is shown in the steps below.
 
-## How to use the app creation scripts ?
+## How to use the app creation scripts?
 
 ### Pre-requisites
 
@@ -107,7 +109,7 @@ Note that the script will choose the tenant in which to create the applications,
 
 #### Option 2 (non-interactive)
 
-When you know the indentity and credentials of the user in the name of whom you want to create the applications, you can use the non-interactive approach. It's more adapted to DevOps. Here is an example of script you'd want to run in a PowerShell Window
+When you know the identity and credentials of the user in the name of whom you want to create the applications, you can use the non-interactive approach. It's more adapted to DevOps. Here is an example of script you'd want to run in a PowerShell Window
 
 ```PowerShell
 $secpasswd = ConvertTo-SecureString "[Password here]" -AsPlainText -Force
@@ -144,3 +146,21 @@ $tenantId = "yourTenantIdGuid"
 . .\Cleanup.ps1 -Credential $mycreds -TenantId $tenantId
 . .\Configure.ps1 -Credential $mycreds -TenantId $tenantId
 ```
+
+### Running the script on Azure Sovereign clouds
+
+All the four options listed above, can be used on any Azure Sovereign clouds. By default, the script targets `AzureCloud`, but it can be changed using the parameter `-AzureEnvironmentName`.
+
+The acceptable values for this parameter are:
+
+- AzureCloud
+- AzureChinaCloud
+- AzureUSGovernment
+- AzureGermanyCloud
+
+Example:
+
+ ```PowerShell
+ . .\Cleanup.ps1 -AzureEnvironmentName "AzureGermanyCloud"
+ . .\Configure.ps1 -AzureEnvironmentName "AzureGermanyCloud"
+ ```

1. Desktop app calls Web API/AppCreationScripts/Cleanup.ps1

@@ -2,9 +2,14 @@
 param(    
     [PSCredential] $Credential,
     [Parameter(Mandatory=$False, HelpMessage='Tenant ID (This is a GUID which represents the "Directory ID" of the AzureAD tenant into which you want to create the apps')]
-    [string] $tenantId
+    [string] $tenantId,
+    [Parameter(Mandatory=$False, HelpMessage='Azure environment to use while running the script (it defaults to AzureCloud)')]
+    [string] $azureEnvironmentName
 )
 
+#Requires -Modules AzureAD
+
+
 if ($null -eq (Get-Module -ListAvailable -Name "AzureAD")) { 
     Install-Module "AzureAD" -Scope CurrentUser 
 } 
@@ -13,10 +18,15 @@ $ErrorActionPreference = "Stop"
 
 Function Cleanup
 {
-<#
-.Description
-This function removes the Azure AD applications for the sample. These applications were created by the Configure.ps1 script
-#>
+    if (!$azureEnvironmentName)
+    {
+        $azureEnvironmentName = "AzureCloud"
+    }
+
+    <#
+    .Description
+    This function removes the Azure AD applications for the sample. These applications were created by the Configure.ps1 script
+    #>
 
     # $tenantId is the Active Directory Tenant. This is a GUID which represents the "Directory ID" of the AzureAD tenant 
     # into which you want to create the apps. Look it up in the Azure portal in the "Properties" of the Azure AD. 
@@ -25,17 +35,17 @@ This function removes the Azure AD applications for the sample. These applicatio
     # you'll need to sign-in with creds enabling your to create apps in the tenant)
     if (!$Credential -and $TenantId)
     {
-        $creds = Connect-AzureAD -TenantId $tenantId
+        $creds = Connect-AzureAD -TenantId $tenantId -AzureEnvironmentName $azureEnvironmentName
     }
     else
     {
         if (!$TenantId)
         {
-            $creds = Connect-AzureAD -Credential $Credential
+            $creds = Connect-AzureAD -Credential $Credential -AzureEnvironmentName $azureEnvironmentName
         }
         else
         {
-            $creds = Connect-AzureAD -TenantId $tenantId -Credential $Credential
+            $creds = Connect-AzureAD -TenantId $tenantId -Credential $Credential -AzureEnvironmentName $azureEnvironmentName
         }
     }
 

1. Desktop app calls Web API/AppCreationScripts/Configure.ps1

@@ -2,9 +2,13 @@
 param(
     [PSCredential] $Credential,
     [Parameter(Mandatory=$False, HelpMessage='Tenant ID (This is a GUID which represents the "Directory ID" of the AzureAD tenant into which you want to create the apps')]
-    [string] $tenantId
+    [string] $tenantId,
+    [Parameter(Mandatory=$False, HelpMessage='Azure environment to use while running the script (it defaults to AzureCloud)')]
+    [string] $azureEnvironmentName
 )
 
+#Requires -Modules AzureAD
+
 <#
  This script creates the Azure AD applications needed for this sample and updates the configuration files
  for the visual Studio projects from the data in the Azure AD applications.
@@ -175,6 +179,11 @@ Function ConfigureApplications
    so that they are consistent with the Applications parameters
 #> 
     $commonendpoint = "common"
+    
+    if (!$azureEnvironmentName)
+    {
+        $azureEnvironmentName = "AzureCloud"
+    }
 
     # $tenantId is the Active Directory Tenant. This is a GUID which represents the "Directory ID" of the AzureAD tenant
     # into which you want to create the apps. Look it up in the Azure portal in the "Properties" of the Azure AD.
@@ -183,17 +192,17 @@ Function ConfigureApplications
     # you'll need to sign-in with creds enabling your to create apps in the tenant)
     if (!$Credential -and $TenantId)
     {
-        $creds = Connect-AzureAD -TenantId $tenantId
+        $creds = Connect-AzureAD -TenantId $tenantId -AzureEnvironmentName $azureEnvironmentName
     }
     else
     {
         if (!$TenantId)
         {
-            $creds = Connect-AzureAD -Credential $Credential
+            $creds = Connect-AzureAD -Credential $Credential -AzureEnvironmentName $azureEnvironmentName
         }
         else
         {
-            $creds = Connect-AzureAD -TenantId $tenantId -Credential $Credential
+            $creds = Connect-AzureAD -TenantId $tenantId -Credential $Credential -AzureEnvironmentName $azureEnvironmentName
         }
     }
 
@@ -202,6 +211,8 @@ Function ConfigureApplications
         $tenantId = $creds.Tenant.Id
     }
 
+    
+
     $tenant = Get-AzureADTenantDetail
     $tenantName =  ($tenant.VerifiedDomains | Where { $_._Default -eq $True }).Name
 
@@ -318,10 +329,10 @@ Function ConfigureApplications
    # Update config file for 'client'
    $configFile = $pwd.Path + "\..\TodoListClient\App.Config"
    Write-Host "Updating the sample code ($configFile)"
-   ReplaceSetting -configFilePath $configFile -key "ida:Tenant" -newValue $tenantName
-   ReplaceSetting -configFilePath $configFile -key "ida:ClientId" -newValue $clientAadApplication.AppId
-   ReplaceSetting -configFilePath $configFile -key "todo:TodoListScope" -newValue ("api://"+$serviceAadApplication.AppId+"/access_as_user")
-   ReplaceSetting -configFilePath $configFile -key "todo:TodoListBaseAddress" -newValue $serviceAadApplication.HomePage
+   ReplaceSetting -configFilePath $configFile -key "ida:Tenant" -newValue ($tenantName)
+   ReplaceSetting -configFilePath $configFile -key "ida:ClientId" -newValue ($clientAadApplication.AppId)
+   ReplaceSetting -configFilePath $configFile -key "todo:TodoListScope" -newValue (("api://"+$serviceAadApplication.AppId+"/access_as_user"))
+   ReplaceSetting -configFilePath $configFile -key "todo:TodoListBaseAddress" -newValue ($serviceAadApplication.HomePage)
    Write-Host ""
    Write-Host -ForegroundColor Green "------------------------------------------------------------------------------------------------" 
    Write-Host "IMPORTANT: Please follow the instructions below to complete a few manual step(s) in the Azure portal":

1. Desktop app calls Web API/README-incremental.md

@@ -16,19 +16,16 @@ endpoint: Microsoft identity platform
 ### Table of content
 
 - [About this sample](#about-this-sample)
-    - [Scenario](#scenario)
-    - [Overview](#overview)
-    - [User experience when using this sample](#user-experience-when-using-this-sample)
+  - [Scenario](#scenario)
+  - [Overview](#overview)
+  - [User experience when using this sample](#user-experience-when-using-this-sample)
 - [How to run this sample](#how-to-run-this-sample)
-    - [Step 1:  In the downloaded folder](#step-1--in-the-downloaded-folder)
-    - [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)
-    - [Troubleshooting](#troubleshooting)
+  - [Step 1:  In the downloaded folder](#step-1-in-the-downloaded-folder)
+  - [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: Run the sample](#step-3-run-the-sample)
 - [How was the code created](#how-was-the-code-created)
 - [Choosing which scopes to expose](#choosing-which-scopes-to-expose)
 - [Next chapter of the tutorial: the Web API itself calls another downstream Web API](#next-chapter-of-the-tutorial-the-web-api-itself-calls-another-downstream-web-api)
-- [How to deploy this sample to Azure](#how-to-deploy-this-sample-to-azure)
 - [Community Help and Support](#community-help-and-support)
 - [Contributing](#contributing)
 - [More information](#more-information)
@@ -76,7 +73,7 @@ cd "1. Desktop app calls Web API"
 
 There are two projects in this sample. Each needs to be separately registered in your Azure AD tenant. To register these projects, you can:
 
-- either follow the steps [Step 2: Register the sample with your Azure Active Directory tenant](#step-2-register-the-sample-with-your-azure-active-directory-tenant) and [Step 3:  Configure the sample to use your Azure AD tenant](#choose-the-azure-ad-tenant-where-you-want-to-create-your-applications)
+- either follow the steps below for manual registration
 - or use PowerShell scripts that:
   - **automatically** creates the Azure AD applications and related objects (passwords, permissions, dependencies) for you. Note that this works for Visual Studio only.
   - modify the Visual Studio projects' configuration files.
@@ -119,7 +116,6 @@ As a first step you'll need to:
 
 #### Register the service app (TodoListService (active-directory-dotnet-native-aspnetcore-v2))
 
-
 1. Navigate to the Microsoft identity platform for developers [App registrations](https://go.microsoft.com/fwlink/?linkid=2083908) page.
 1. Select **New registration**.
 1. In the **Register an application page** that appears, enter your application's registration information:
@@ -143,10 +139,10 @@ The first thing that we need to do is to declare the unique [resource](https://d
         - Keep **State** as **Enabled**
         - Click on the **Add scope** button on the bottom to save this scope.
 
-##### Configure the  service app (TodoListService (active-directory-dotnet-native-aspnetcore-v2)) to use your app registration
+#### Configure the  service app (TodoListService (active-directory-dotnet-native-aspnetcore-v2)) to use your app registration
 
 Open the project in your IDE (like Visual Studio) to configure the code.
->In the steps below, "ClientID" is the same as "Application ID" or "AppId".						   					
+>In the steps below, "ClientID" is the same as "Application ID" or "AppId".	
 
 1. Open the `TodoListService\appsettings.json` file
 2. Find the app key `Domain` and replace the existing value with your Azure AD tenant name.
@@ -165,7 +161,6 @@ Open the project in your IDE (like Visual Studio) to configure the code.
 1. In the app's registration screen, select **Authentication** in the menu.
    - If you don't have a platform added, select **Add a platform** and select the **Public client (mobile & desktop)** option.
    - In the **Redirect URIs** | **Suggested Redirect URIs for public clients (mobile, desktop)** section, select **https://login.microsoftonline.com/common/oauth2/nativeclient**
-
 1. Select **Save** to save your changes.
 1. In the app's registration screen, click on the **API permissions** blade in the left to open the page where we add access to the Apis that your application needs.
    - Click the **Add a permission** button and then,
@@ -174,17 +169,17 @@ Open the project in your IDE (like Visual Studio) to configure the code.
    - In the **Delegated permissions** section, select the **access_as_user** in the list. Use the search box if necessary.
    - Click on the **Add permissions** button at the bottom.
 
-##### Configure the  client app (TodoListClient (active-directory-dotnet-native-aspnetcore-v2)) to use your app registration
+#### Configure the  client app (TodoListClient (active-directory-dotnet-native-aspnetcore-v2)) to use your app registration
 
 Open the project in your IDE (like Visual Studio) to configure the code.
->In the steps below, "ClientID" is the same as "Application ID" or "AppId".																																						  
+>In the steps below, "ClientID" is the same as "Application ID" or "AppId".						  
 1. Open the `TodoListClient\App.Config` file
-1. Find the app key `ida:Tenant` and replace the existing value with your Azure AD tenant name.
-1. Find the app key `ida:ClientId` and replace the existing value with the application ID (clientId) of the `TodoListClient (active-directory-dotnet-native-aspnetcore-v2)` application copied from the Azure portal.
-1. Find the app key `todo:TodoListScope` and replace the existing value with Scope.
-1. Find the app key `todo:TodoListBaseAddress` and replace the existing value with the base address of the TodoListService (active-directory-dotnet-native-aspnetcore-v2) project (by default `https://localhost:44351/`).
+2. Find the app key `ida:Tenant` and replace the existing value with your Azure AD tenant name.
+3. Find the app key `ida:ClientId` and replace the existing value with the application ID (clientId) of the `TodoListClient (active-directory-dotnet-native-aspnetcore-v2)` application copied from the Azure portal.
+4. Find the app key `todo:TodoListScope` and replace the existing value with Scope.
+5. Find the app key `todo:TodoListBaseAddress` and replace the existing value with the base address of the TodoListService (active-directory-dotnet-native-aspnetcore-v2) project (by default `https://localhost:44351/`).
 
-### Step 4: Run the sample
+### Step 3: 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.
 
@@ -340,7 +335,7 @@ See [2. Web API now calls Microsoft Graph](../2.%20Web%20API%20now%20calls%20Mic
 
 Use [Stack Overflow](http://stackoverflow.com/questions/tagged/msal) 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`].
+Make sure that your questions or comments are tagged with [`azure-active-directory` `msal` `dotnet`].
 
 To provide a recommendation, visit the following [User Voice page](https://feedback.azure.com/forums/169401-azure-active-directory).