Over the past year my primary project at Azure Active Directory has been to design finer-grained access management for Azure. We’ve built roles-based access control capabilities in the new service management API layer of Azure called Azure Resource Manager (ARM). Management APIs of Azure resource providers (Compute, Websites, ClearDB MySQL etc.) are being built behind ARM, which lights up consistent roles-based access management across all those resource providers.
I often need to work directly with the ARM REST APIs. To call ARM one needs an access token from the Azure Active Directory (Azure AD) to which the Azure subscription is homed. I work with a set of test accouts that have access to multiple Azure subscriptions homed to more than one Azure ADs. So everytime I needed to access ARM APIs for an account I had to do a bunch of boilerplate work – discovering Azure ADs in which the account exists, discovering subscriptions in those directories to which the account has some kind of access, source access tokens from those directories using Active Directory Authentication Library (ADAL) … So I built this PowerShell script client for Azure Resource Manager to make my life easier.
ARMPowerShell does the heavy lifting work for me, of authenticating with Azure AD and discovering the user’ Azure subscriptions, and allows me to focus on calling the ARM APIs.
I start the session using the Connect-ARM command that prompts me to authenticate using my Azure AD account, and then I mostly use the Execute-ARM. Ok I’m getting a little ahead. Let’s start by installing the module:
Install ARMPowerShell (one time)
- Download and unzip the archive: https://github.com/dushyantgill/AzureResourceManagerPowerShell/archive/master.zip
- Fireup PowerShell. Make sure you’ve set execution policy to RemoteSigned, if not, run: Set-ExecutionPolicy RemoteSigned -Scope Process.
- Run the Install-ARMModule.ps1 script from the location where you unzipped the archive. This script will do a couple of things: download the Azure AD Auth Library (ADAL) nuget, create a new module folder for ARM under user’ Documents\WindowsPowerShell\Modules with the PSD1 and PSM1 files.
Start ARM Session (Connect-ARM)
Now, whenever you want to work with ARM REST APIs, you’ll start PowerShell and run the Connect-ARM command. It will pop-up an ADAL authentication dialog. Sign-in with your Azure AD account (formally known as Work or School Account) that has access to Azure subscriptions. You can also sign-in using your Microsoft Account (also known as LiveId).
Connect-ARM does a bunch of stuff:
- Loads the ADAL libraries and authenticates the user
- Retrieves the Azure Active Directories that the account is part of (using the https://management.azure.com/tenants API) and persists the identifiers in the $ARMTenants session variable
- Acquires access tokens for ARM API and Directory Graph API from each of the directories and persists them in the $ARMTenantAccessTokensARM and $ARMTenantAccessTokensGraph session variables
- Retrieves the Azure subscriptions in which the user has some kind of access for each of the directories (using the https://management.azure.com/subscriptions API) and persists them in the $ARMSubscriptions session variable
Call ARM REST APIs (Execute-ARMQuery)
Use the Execute-ARMQuery command to access the ARM APIs.
- HTTPVerb is a mandatory parameter. Use ‘GET’, ‘PUT’, ‘POST’, ‘DELETE’, ‘PATCH’.
- SubscriptionId is a mandatory parameter. Don’t worry, you don’t need to write these down – get the SubscriptionId from the $ARMSubscriptions session variable – it holds all your subscriptions and their Ids.
- Base is a mandatory parameter. This gets appended to the ARM host address (https://management.azure.com) to form the base of the REST API URI.
- APIVersion: If this parameter isn’t specific, the default value of ‘2014-04-01-preview’ is used.
- Query: query string that is appended to ‘?api-version=<api version value>’
- Data: the body to be added to PUT, POST and PATCH requests
List the Resource Groups in the Subscription:
Execute-ARMQuery -SubscriptionId c276fc76-9cd4-44c9-99a7-4fd71546436e -HTTPVerb GET -Base /subscriptions/c276fc76-9cd4-44c9-99a7-4fd71546436e/resourcegroups
List all Resources in the Subscription:
Execute-ARMQuery -SubscriptionId c276fc76-9cd4-44c9-99a7-4fd71546436e -HTTPVerb GET -Base /subscriptions/c276fc76-9cd4-44c9-99a7-4fd71546436e/resources
List Resources of a specific type in the Subscription:
Execute-ARMQuery -SubscriptionId c276fc76-9cd4-44c9-99a7-4fd71546436e -HTTPVerb GET -Base /subscriptions/c276fc76-9cd 4-44c9-99a7-4fd71546436e/resources -Query "&`$filter=resourceType eq ‘Microsoft.Web/sites’"