Merge pull request #527 from sethmanheim/azsps

Update readme per Efi

Author: charlesjoy

Identity/README.md

@@ -48,17 +48,39 @@ and for AD FS is `https://adfs.local.azurestack.external/adfs`.
 ## Updating the Azure Stack AAD Home Directory (after installing updates or new Resource Providers)
 
 After installing updates or hotfixes to Azure Stack, new features may be introduced which require new permissions to be
-granted to one or more identity applications. Granting these permissions requires Administrative access to the
-home directory, and so it cannot be done automatically.
+granted to one or more identity applications. Granting these permissions requires administrative access to the
+home directory, so it cannot be done automatically.
+
+### Install PowerShell for Azure Stack
+
+Use the latest PowerShell module for Azure Stack to register with Azure.
+If the latest version is not already installed, see [install PowerShell for Azure Stack](https://docs.microsoft.com/azure-stack/operator/azure-stack-powershell-install).
+
+### Download Azure Stack tools
+
+The Azure Stack tools GitHub repository contains PowerShell modules that support Azure Stack functionality, including updating permissions on Azure AD. During the registration process, you must import and use the **AzureStack.Connect** and **AzureStack.Identity** PowerShell modules, found in the Azure Stack tools repository, to update the permissions on Azure AD for the Azure stack stamp.
+
+To ensure that you are using the latest version, delete any existing versions of the Azure Stack tools, then [download the latest version from GitHub](https://docs.microsoft.com/azure-stack/operator/azure-stack-powershell-download) before proceeding.
+
+### Updating Azure AD tenant permissions
+
+You should now be able to update the permissions which should clear the alert. Run the following commands from the **Azurestack-tools-master/identity** folder:
 
 ```powershell
+Import-Module ..\Connect\AzureStack.Connect.psm1
+Import-Module ..\Identity\AzureStack.Identity.psm1
+
 $adminResourceManagerEndpoint = "https://adminmanagement.<region>.<domain>"
-$homeDirectoryTenantName = "<homeDirectoryTenant>.onmicrosoft.com" # this is the primary tenant Azure Stack is registered to
+
+# This is the primary tenant Azure Stack is registered to:
+$homeDirectoryTenantName = "<homeDirectoryTenant>.onmicrosoft.com"
 
 Update-AzsHomeDirectoryTenant -AdminResourceManagerEndpoint $adminResourceManagerEndpoint `
-    -DirectoryTenantName $homeDirectoryTenantName -Verbose
+   -DirectoryTenantName $homeDirectoryTenantName -Verbose
 ```
 
+The script prompts you for administrative credentials on the Azure AD tenant, and takes several minutes to run. The alert should clear after you have run the cmdlet.
+
 ## Enabling AAD Multi-Tenancy in Azure Stack
 
 Allowing users and service principals from multiple AAD directory tenants to sign in and create resources on Azure Stack.