Using AAD Credentials with Azure PowerShell Cmdlets

  • Article

The Azure Service Management REST API (ASM) provides an extensive set of RESTful operations that can be used to manage almost all Azure services. This API has been used since Azure went GA in 2010, although the API has been significantly extended as new services have been added to the Azure Platform. The Azure Portal and the Azure PowerShell cmdlets both use the Azure Service Management REST API to manage services.

In recent years, there has been a dramatic increase in the number of services and features provided by Azure. Meanwhile, there has been an increasing desire to manage applications viewed as a collection of services rather than just individual services. This led to the creation of the Azure Resource Management REST API (ARM), a new API designed to support the management of resource groups which comprise collections of deployable services referred to as resources. The preview Azure Portal uses the Azure Resource Management REST API to manage services and the Azure PowerShell cmdlets have been extended to use the new API.

The Azure PowerShell cmdlets now has two modes: the classic Azure Service Management mode using the ASM; and an Azure Resource Manager mode using the ARM. The two modes are distinct and in a given PowerShell session only the cmdlets from one mode can be used at a time. The ASM mode is the default, so the Switch-AzureMode cmdlet must be used to switch to the ARM mode when desired. All new functionality, including the management of new Azure services, is being exposed only in ARM mode. Currently, the ARM does not support all Azure services – most notably Azure Compute (Azure Virtual Machines and Azure Cloud Services) – so the ASM PowerShell mode must be used to manage them. Similarly new services such as the Azure Redis Cache can only be managed from the ARM mode.

In the early days of Azure the only authentication method supported by the ASM was client-certificate authentication using self-signed X.509 certificates. This meant that the ASM PowerShell cmdlets only supported certificate authentication. The pain caused by this led to the use of publish settings files - automatically generated on the Azure Portal, inserted into a subscription, and downloaded to the local machine – as a convenience in creating and managing the required certificates.

Azure Active Directory (AAD) provides a user-authentication system that is sufficiently powerful it can be used as the directory service for Office 365. ASM was upgraded to support the use of AAD credentials as an alternative to X.509 certificates. ARM only supports the use of AAD credentials and explicitly does not support the use of X.509 certificates. This has the effect that the ASM mode of the Azure PowerShell cmdlets supports authentication using either certificates or AAD credentials while the ARM mode only supports the use of AAD credentials. Consequently, automated access to new Azure features such as Azure Redis Cache or to the entire Azure Resource Manager requires the use of AAD. Fortunately, AAD credentials can also be used with the ASM mode of PowerShell cmdlets. This means that using AAD credentials provides access to both PowerShell modes and to the full gamut of service and resource management operations they provide. Furthermore, AAD credentials are required to make use of the RBAC capability supported by the ARM API – and exposed in the preview Azure portal and the ARM mode of the PowerShell cmdlets.

Note that it is possible to use a Microsoft Account (formerly known as Live ID) to sign in to the Azure Portal. It is not possible to use a Microsoft Account to authenticate for the Azure PowerShell cmdlets unless that account is the subscription owner. However, since each Azure subscription has an associated AAD it is easy to create a user in that directory and use that account to sign in when using the Azure PowerShell cmdlets. The creation and use of AAD credentials is documented here.

The use of AAD credentials provides many benefits over the use of X.509 certificates including:

  • Access to ARM features
  • Access to RBAC
  • No need to manage and maintain X.509 certificates
  • No need to deal with publish-settings files

There is really no need to use certificates when using Azure PowerShell cmdlets.

Azure Profile Configuration File

An Azure administrator may want to use the PowerShell cmdlets against more than one Azure subscription and use more than one authentication account (or identity). Furthermore, the Azure PowerShell cmdlets can be used against multiple environments: Microsoft Azure; Azure China (managed by Via21net); and Windows Azure Pack. For convenience, those PowerShell cmdlets that actually interact with one of these environments use a default subscription, default account, default storage account and default environment. In practice, the default environment never needs to be changed since it is set to Microsoft Azure – however, the other defaults need to be set before the PowerShell cmdlets can be used. These default values are cached locally in the following file:

"%APPDATA%\Roaming\Windows Azure Powershell\AzureProfile.json"

This is a JSON file containing sections with cached information for all subscriptions, accounts and environments that the administrator has configured on the system. For example, an authorization using a specific user account leads to information for all subscriptions that account has access to being added to the configuration file.

Azure PowerShell Cmdlets

This post is focused on using the following Azure PowerShell cmdlets to manage the subscription and account information cached locally in the configuration file:

  • Add-AzureAccount – authenticates a user and updates the configuration file
  • Get-AzureAccount – lists the Azure accounts cached in the configuration file
  • Remove-AzureAccount – removes the account information from the configuration file 
  • Get-AzureSubscription – lists the Azure subscriptions cached in the configuration file
  • Select-AzureSubscription – specifies an Azure subscription as the default for cmdlets
  • Set-AzureSubscription – specifies an Azure Storage account as the default for cmdlets
  • Remove-AzureSubscription – removes the subscription information from the configuration file
  • Switch-AzureMode – switches between the ARM and ASM mode for Azure PowerShell cmdlets


 Add-AzureAccount

The Add-AzureAccount cmdlet is used to provide authentication credentials for the Azure PowerShell cmdlets. This typically pops up a sign-in dialog, but a username/password combination can also be provided in the command line to support authentication in a headless situation such as automated deployment. Add-AzureAccount updates the configuration file with the subscription information for all subscriptions associated with the account.  The authentication tokens are cached for about a day allowing Azure PowerShell cmdlets to be invoked in later sessions without the need to re-authenticate.

The following sample shows how to invoke Add-AzureAccount without the popup dialog:

 $username = "someorgid@orgaccount.com"
$password = "Pa$$w0rd" | ConvertTo-SecureString -AsPlainText -Force
 
$credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $username, $password 
Add-AzureAccount -Credential $credential

David Ebbo has a post showing how an AAD Service Principal can be created and then used as an identity for ONLY the ARM mode of the Azure
PowerShell cmdlets. The service principal identity essentially comprises an id and key associated with a specific AAD tenant. Currently, a service principal can only be created on the production Azure portal.

Remove-AzureAccount

Remove-AzureAccount removes all information about the specified account from the configuration file.

Get-AzureSubscription

Get-AzureSubscription returns the following details about each subscription cached in the configuration file:

  • SubscriptionId – ID of the subscription
  • Subscription Name – name of the subscription
  • Environment – name of the environment (e.g., AzureCloud or AzureChinaCloud)
  • SupportedModes – the modes (ASM and/or ARM) usable in the subscription
  • DefaultAccount – the default account used to manage the subscription
  • Accounts – the set of administrator accounts contained in the configuration file
  • IsDefault – indicates whether this is the default subscription for Azure PowerShell cmdlets
  • IsCurrent – indicates whether this subscription is used by default only for the current PowerShell session
  • CurrentStorageAccountName – specifies the storage account used by Azure PowerShell cmdlets
  • TenantID – specifies the ID of the default Azure Active Directory associated with the subscription

Select-AzureSubscription

Select-AzureSubscription selects a specified subscription as the default subscription for either the current or all future PowerShell sessions. This information is stored in the configuration file. For example:

 Select-AzureSubscription -SubscriptionName 'aSub' -Default 

Set-AzureSubscription

Set-AzureSubscription modifies the subscription data stored in the configuration file but it can also be used to manually add a subscription to the configuration file. Set-AzureSubscription is commonly used to modify the default storage account associated with a subscription, which is needed by some Azure PowerShell cmdlets. For example:

 Set-AzureSubscription -SubscriptionName 'aSub' -CurrentStorageAccountName 'anAccount'

Remove-AzureSubscription

Remove-AzureSubscription removes all information about the specified subscription from the configuration file.

Switch-AzureMode

Switch-AzureMode switches the use of the Azure PowerShell cmdlets between the two modes: AzureServiceManagement and AzureResourceManager. Each mode provides a distinct set of cmdlets. The following example shows the use of Add-AzureAccount to authenticate followed by two mode switches to demonstrate the use of cmdlets from each mode:

 Add-AzureAccount
 
Switch-AzureMode -Name AzureResourceManager
 
Get-AzureResource
 
Switch-AzureMode -Name AzureServiceManagement
 
Get-AzureService