Merge pull request #42 from Azure-Samples/tibre/cleanup

Cleanup and README update

Author: Tiago Brenck

AppCreationScripts/AppCreationScripts.md

@@ -1,4 +1,4 @@
-# Registering the Azure Active Directory applications and updating the configuration files for this sample using PowerShell scripts
+# Registering the sample apps with Microsoft identity platform and updating the configuration files using PowerShell scripts
 
 ## Overview
 
@@ -9,9 +9,10 @@
    ```PowerShell
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
    ```
-1. Run the script to create your Azure AD application and configure the code of the sample application accordinly. (Other ways of running the scripts are described below)
+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"
+ ```

AppCreationScripts/Cleanup.ps1

@@ -2,21 +2,28 @@
 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
 )
 
 if ($null -eq (Get-Module -ListAvailable -Name "AzureAD")) { 
     Install-Module "AzureAD" -Scope CurrentUser 
 } 
 Import-Module AzureAD
-$ErrorActionPreference = 'Stop'
+$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 +32,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
         }
     }
 

AppCreationScripts/Configure.ps1

@@ -2,7 +2,9 @@
 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
 )
 
 <#
@@ -39,7 +41,7 @@ Function AddResourcePermission($requiredAccess, `
 }
 
 #
-# Exemple: GetRequiredPermissions "Microsoft Graph"  "Graph.Read|User.Read"
+# Example: GetRequiredPermissions "Microsoft Graph"  "Graph.Read|User.Read"
 # See also: http://stackoverflow.com/questions/42164581/how-to-configure-a-new-azure-ad-application-through-powershell
 Function GetRequiredPermissions([string] $applicationDisplayName, [string] $requiredDelegatedPermissions, [string]$requiredApplicationPermissions, $servicePrincipal)
 {
@@ -89,19 +91,61 @@ Function ReplaceSetting([string] $configFilePath, [string] $key, [string] $newVa
    $content.save($configFilePath)
 }
 
+<#.Description
+   This function creates a new Azure AD scope (OAuth2Permission) with default and provided values
+#>  
+Function CreateScope( [string] $value, [string] $userConsentDisplayName, [string] $userConsentDescription, [string] $adminConsentDisplayName, [string] $adminConsentDescription)
+{
+    $scope = New-Object Microsoft.Open.AzureAD.Model.OAuth2Permission
+    $scope.Id = New-Guid
+    $scope.Value = $value
+    $scope.UserConsentDisplayName = $userConsentDisplayName
+    $scope.UserConsentDescription = $userConsentDescription
+    $scope.AdminConsentDisplayName = $adminConsentDisplayName
+    $scope.AdminConsentDescription = $adminConsentDescription
+    $scope.IsEnabled = $true
+    $scope.Type = "User"
+    return $scope
+}
+
+<#.Description
+   This function creates a new Azure AD AppRole with default and provided values
+#>  
+Function CreateAppRole([string] $types, [string] $name, [string] $description)
+{
+    $appRole = New-Object Microsoft.Open.AzureAD.Model.AppRole
+    $appRole.AllowedMemberTypes = New-Object System.Collections.Generic.List[string]
+    $typesArr = $types.Split(',')
+    foreach($type in $typesArr)
+    {
+        $appRole.AllowedMemberTypes.Add($type);
+    }
+    $appRole.DisplayName = $name
+    $appRole.Id = New-Guid
+    $appRole.IsEnabled = $true
+    $appRole.Description = $description
+    $appRole.Value = $name;
+    return $appRole
+}
 
 Set-Content -Value "<html><body><table>" -Path createdApps.html
 Add-Content -Value "<thead><tr><th>Application</th><th>AppId</th><th>Url in the Azure portal</th></tr></thead><tbody>" -Path createdApps.html
 
+$ErrorActionPreference = "Stop"
+
 Function ConfigureApplications
 {
 <#.Description
    This function creates the Azure AD applications for the sample in the provided Azure AD tenant and updates the
    configuration files in the client and service project  of the visual studio solution (App.Config and Web.Config)
    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.
@@ -110,17 +154,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
         }
     }
 
@@ -129,20 +173,24 @@ Function ConfigureApplications
         $tenantId = $creds.Tenant.Id
     }
 
+    
+
     $tenant = Get-AzureADTenantDetail
     $tenantName =  ($tenant.VerifiedDomains | Where { $_._Default -eq $True }).Name
 
-    # Get the user running the script
+    # Get the user running the script to add the user as the app owner
     $user = Get-AzureADUser -ObjectId $creds.Account.Id
 
    # Create the service AAD application
    Write-Host "Creating the AAD application (TodoListService-ManualJwt)"
+   # create the application 
    $serviceAadApplication = New-AzureADApplication -DisplayName "TodoListService-ManualJwt" `
                                                    -HomePage "https://localhost:44324" `
                                                    -PublicClient $False
    $serviceIdentifierUri = 'api://'+$serviceAadApplication.AppId
    Set-AzureADApplication -ObjectId $serviceAadApplication.ObjectId -IdentifierUris $serviceIdentifierUri
 
+   # create the service principal of the newly created application 
    $currentAppId = $serviceAadApplication.AppId
    $serviceServicePrincipal = New-AzureADServicePrincipal -AppId $currentAppId -Tags {WindowsAzureActiveDirectoryIntegratedApp}
 
@@ -154,19 +202,52 @@ Function ConfigureApplications
         Write-Host "'$($user.UserPrincipalName)' added as an application owner to app '$($serviceServicePrincipal.DisplayName)'"
    }
 
+    # rename the user_impersonation scope if it exists to match the readme steps or add a new scope
+    $scopes = New-Object System.Collections.Generic.List[Microsoft.Open.AzureAD.Model.OAuth2Permission]
+   
+    if ($scopes.Count -ge 0) 
+    {
+        # add all existing scopes first
+        $serviceAadApplication.Oauth2Permissions | foreach-object { $scopes.Add($_) }
+
+        $scope = $serviceAadApplication.Oauth2Permissions | Where-Object { $_.Value -eq "User_impersonation" }
+
+        if ($scope -ne $null) 
+        {
+            $scope.Value = "access_as_user"
+        }
+        else 
+        {
+            # Add scope
+            $scope = CreateScope -value "access_as_user"  `
+                -userConsentDisplayName "Access TodoListService-ManualJwt"  `
+                -userConsentDescription "Allow the application to access TodoListService-ManualJwt on your behalf."  `
+                -adminConsentDisplayName "Access TodoListService-ManualJwt"  `
+                -adminConsentDescription "Allows the app to have the same access to information in the directory on behalf of the signed-in user."
+            
+            $scopes.Add($scope)
+        }        
+    }
+     
+    # add/update scopes
+    Set-AzureADApplication -ObjectId $serviceAadApplication.ObjectId -OAuth2Permission $scopes
+
    Write-Host "Done creating the service application (TodoListService-ManualJwt)"
 
    # URL of the AAD application in the Azure portal
    # Future? $servicePortalUrl = "https://portal.azure.com/#@"+$tenantName+"/blade/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/Overview/appId/"+$serviceAadApplication.AppId+"/objectId/"+$serviceAadApplication.ObjectId+"/isMSAApp/"
    $servicePortalUrl = "https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/CallAnAPI/appId/"+$serviceAadApplication.AppId+"/objectId/"+$serviceAadApplication.ObjectId+"/isMSAApp/"
    Add-Content -Value "<tr><td>service</td><td>$currentAppId</td><td><a href='$servicePortalUrl'>TodoListService-ManualJwt</a></td></tr>" -Path createdApps.html
 
+
    # Create the client AAD application
    Write-Host "Creating the AAD application (TodoListClient-ManualJwt)"
+   # create the application 
    $clientAadApplication = New-AzureADApplication -DisplayName "TodoListClient-ManualJwt" `
-                                                  -ReplyUrls "urn:ietf:wg:oauth:2.0:oob", "https://login.microsoftonline.com/common/oauth2/nativeclient" `
+                                                  -ReplyUrls "https://login.microsoftonline.com/common/oauth2/nativeclient" `
                                                   -PublicClient $True
 
+   # create the service principal of the newly created application 
    $currentAppId = $clientAadApplication.AppId
    $clientServicePrincipal = New-AzureADServicePrincipal -AppId $currentAppId -Tags {WindowsAzureActiveDirectoryIntegratedApp}
 
@@ -178,6 +259,7 @@ Function ConfigureApplications
         Write-Host "'$($user.UserPrincipalName)' added as an application owner to app '$($clientServicePrincipal.DisplayName)'"
    }
 
+
    Write-Host "Done creating the client application (TodoListClient-ManualJwt)"
 
    # URL of the AAD application in the Azure portal
@@ -190,7 +272,7 @@ Function ConfigureApplications
    # Add Required Resources Access (from 'client' to 'service')
    Write-Host "Getting access from 'client' to 'service'"
    $requiredPermissions = GetRequiredPermissions -applicationDisplayName "TodoListService-ManualJwt" `
-                                                -requiredDelegatedPermissions "user_impersonation" `
+                                                -requiredDelegatedPermissions "access_as_user" `
 
    $requiredResourcesAccess.Add($requiredPermissions)
 
@@ -201,25 +283,26 @@ Function ConfigureApplications
    # Update config file for 'service'
    $configFile = $pwd.Path + "\..\TodoListService-ManualJwt\Web.Config"
    Write-Host "Updating the sample code ($configFile)"
-   ReplaceSetting -configFilePath $configFile -key "ida:TenantId" -newValue $tenantId
-   ReplaceSetting -configFilePath $configFile -key "ida:Audience" -newValue $serviceIdentifierUri
-   ReplaceSetting -configFilePath $configFile -key "ida:ClientId" -newValue $serviceAadApplication.AppId
+   ReplaceSetting -configFilePath $configFile -key "ida:TenantId" -newValue ($tenantId)
+   ReplaceSetting -configFilePath $configFile -key "ida:Audience" -newValue ($serviceIdentifierUri)
+   ReplaceSetting -configFilePath $configFile -key "ida:ClientId" -newValue ($serviceAadApplication.AppId)
 
    # 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:TodoListResourceId" -newValue $serviceIdentifierUri
-   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:TodoListResourceId" -newValue ($serviceIdentifierUri)
+   ReplaceSetting -configFilePath $configFile -key "todo:TodoListBaseAddress" -newValue ($serviceAadApplication.HomePage)
 
    Add-Content -Value "</tbody></table></body></html>" -Path createdApps.html  
 }
 
 # Pre-requisites
 if ((Get-Module -ListAvailable -Name "AzureAD") -eq $null) { 
     Install-Module "AzureAD" -Scope CurrentUser 
-} 
+}
+
 Import-Module AzureAD
 
 # Run interactively (will ask you for the tenant ID)

AppCreationScripts/sample.json

@@ -25,12 +25,12 @@
       "Name": "TodoListClient-ManualJwt",
       "Kind": "Desktop",
       "Audience": "AzureADMyOrg",
-      "ReplyUrls": "urn:ietf:wg:oauth:2.0:oob,https://login.microsoftonline.com/common/oauth2/nativeclient",
+      "ReplyUrls": "https://login.microsoftonline.com/common/oauth2/nativeclient",
       "IsPublicClient": true,
       "RequiredResourcesAccess": [
         {
           "Resource": "service",
-          "DelegatedPermissions": [ "user_impersonation" ]
+          "DelegatedPermissions": [ "access_as_user" ]
         }
       ]
     }