This post will guide you through communicating with the Azure Stack REST API using PowerShell. Here I am focusing on the https://adminmanagement.{region}.{dns suffix} endpoint but this could be converted to using the https://management.{region}.{dns suffix} endpoint very easily.

For this article we will be using the Invoke-WebRequest cmdlet and we are going to use the ConvertFrom-Json cmdlet to handle the web request responses.

The list below will summarise the steps we are going to cover today and then we’ll dig into each one.

  • Get the resource audience value dynamically for the bearer token we need to authenticate with the various endpoints.
  • Construct the request body and send (POST) this to the https://login.microsoftonline.com/{AAD Tenant name or id}/oauth2/token endpoint to get a bearer token which is required for queries against the Azure Stack API
  • Use the bearer token to make make API requests against the Authenticated Azure Stack API Endpoints

The first thing you will need to do is query the https://adminmanagement.{region}.{dns suffix} /metadata/endpoints API endpoint to get the audience value that will be required to get a bearer token.

For that we will use the following PowerShell.
This will store the relevant audience in to the $bearerTokenResource variable.

# // Variables

# Enter your tenant name or id below
$tenantid = "yourdomain.onmicrosoft.com"
# Enter the API version (If in doubt, use this one)
$apiversion = "2015-11-01"
# Enter the region for your stamp below
$region = "north"
# Enter the dns for your stamp below
$dns = "my.azurestack"

# // Main Routine

# get the resource endpoint for the authorisation token
$method= "Get"
$uri = "https://adminmanagement.$region.$dns/metadata/endpoints?api-version=$apiversion"
$response = Invoke-WebRequest $uri -Method $method -ErrorAction Stop | ConvertFrom-Json
$bearerTokenResource = $response.authentication.audiences[0]
# Output the bearer token response
$bearerTokenResource

The second thing you will need to do is authenticate for, and store, a Bearer Token.

This is common whether you are talking to Azure Stack or Azure or a variety of APIs for that matter. The things that can change here are the variables required in the Authentication body and the client identifier and, as above, the audience. The audience basically defines which endpoints will trust your bearer token.

The PowerShell below will go to https://login.microsoftonline.com and get a bearer token we can use to communicate with the Azure Stack API Endpoints.

When the script is complete you will have a $token object for populating the Authentication Headers for future API calls.

# // Variables

# Enter your tenant name or id below
$tenantid = "yourdomain.onmicrosoft.com"
# Enter credentials with permissions to the Azure Stack
$username = 'admin@yourdomain.onmicrosoft.com'
$password = '555-hack-me-please'

// Main Routine

# Get a bearar token
# Note: The client_id, grant_type and scope values are constants
# Note: Use the $bearerTokenResource from the sample above
$body = @{
    grant_type = "password"
    client_id = "1950a258-227b-4e31-a9cf-717495945fc2"
    resource = $bearerTokenResource
    username = $username
    password = $password
    scope= "openid"
}

# Store token
$method = "POST"
$uri = "https://login.microsoftonline.com/$tenantid/oauth2/token"
$token = Invoke-RestMethod $uri -Body $body -Method $method -ErrorAction Stop -ContentType 'application/x-www-form-urlencoded'
# Output the token
$token

Third. Now armed with our Bearer Token, we can now start to query the various Azure Stack API Endpoints.

I am going to show you some examples below but you should go to
https://docs.microsoft.com/en-us/rest/api/azure-stack/
for the complete list.

This first PowerShell sample will get all the tenant directories registered with your Azure Stack Hub.

# // Variables

# The API version of the endpoint
$apiversion = "2015-11-01"
# Enter the region for your stamp below
$region = "north"
# Enter the dns for your stamp below
$dns = "my.azurestack"
# Enter the subscription id for your default provider subscription
$subscriptionid = "a44de15f-f210-4578-840c-c311d962d3ef"
# Enter the resource group name where you store tenant azure ad registrations
$resourcegroup = "custom.registrations"

# // Main Routine

# Setup the headers for the request
# Note: use the $token variable for the sample above
$headers = @{}
$headers.Add("Authorization","$($token.token_type) "+ " " + "$($token.access_token)")
# Setup the call and add it to the standard uri
# Note: the subscription below is an example of the default provider subscription
$method = "Get"
$call = "subscriptions/$subscriptionid/providers/resourcegroups/$resourcegroup/providers/Microsoft.Subscriptions.Admin/directoryTenants?api-version=$apiversion"
$uri = "https://adminmanagement.$region.$dns/$call"
$Response = Invoke-WebRequest -Uri $URI -Method $Method -Headers $Headers | ConvertFrom-Json
# Output the results
$Response.value | fl *

Here is another example to give context. Here we are listing the user subscriptions.

# // Variables

# The API version of the endpoint
$apiversion = "2015-11-01"
# Enter the region for your stamp below
$region = "north"
# Enter the dns for your stamp below
$dns = "my.azurestack"
# Enter the subscription id for your default provider subscription
$subscriptionid = "a44de15f-f210-4578-840c-c311d962d3ef"

# // Main Routine

# Setup the headers for the request
# Note: use the $token variable for the sample above
$headers = @{}
$headers.Add("Authorization","$($token.token_type) "+ " " + "$($token.access_token)")
# Setup the call and add it to the standard uri
# Note: the subscription below is an example of the default provider subscription
$method = "Get"
$call = "subscriptions/$subscriptionid/providers/Microsoft.Subscriptions.Admin/Subscriptions?api-version=$apiversion"
$uri = "https://adminmanagement.$region.$dns/$call"
$Response = Invoke-WebRequest -Uri $URI -Method $Method -Headers $Headers | ConvertFrom-Json
# Output the results
$Response.value | fl *

Last one. Here we are listing the 3 base subscriptions registered to your stamp. This will also list the ID for your default provider subscription for the two samples above.

# // Variables

# The API version of the endpoint
$apiversion = "2015-11-01"
# Enter the region for your stamp below
$region = "north"
# Enter the dns for your stamp below
$dns = "my.azurestack"

# // Main Routine

# Setup the headers for the request
# Note: use the $token variable for the sample above
$headers = @{}
$headers.Add("Authorization","$($token.token_type) "+ " " + "$($token.access_token)")
# Setup the call and add it to the standard uri
# Note: the subscription below is an example of the default provider subscription
$method = "Get"
$call = "subscriptions?api-version=$apiversion"
$uri = "https://adminmanagement.$region.$dns/$call"
$Response = Invoke-WebRequest -Uri $URI -Method $Method -Headers $Headers | ConvertFrom-Json
# Output the results
$Response.value | fl *

There you go! I hope this article saves you time. Happy coding.