Microsoft Azure exposes many APIs. There is a Usage API which allows you to see how much Azure resources you have consumed in your subscription. There is a Rate Card API which allows you to see the public (retail) pricing for Azure resources associated with specific offers and there is a resource API that allows you to see what resources you have provisioned in your subscription(s). These APIs enable you to build all kinds of custom scenarios.
In this post, I will show how to query the Management API, but it will work for any of the API’s (just change the Uri). I will be using Postman, but once you see how easy it is, you should be able to use the tool or language of your choice (PowerShell, curl etc.) to query any of the Azure APIs.
The first thing you need to do is to authenticate you requests. The Azure APIs use the OAuth 2.0 Implicit Flow and for that, you will need to create a Service Principal in Azure Active Directory.
How to create an Azure App Registration that is configured for the OAuth 2.0 Implicit Flow
You will need to create a service principal to authenticate to the Azure management APIs. The service principal consists of two resources that need to be created and configured to work together. You will also need to configure the permissions the service principal will have in your subscription.
The two things that you need to create and configure are an Azure AD Enterprise Application and an Azure AD App Registration. Getting these things created and configured correctly is kind of complicated. Luckily, the Azure CLI provides a one line command that sets all of this up. That is what I will show in this post.
First, login with the Az CLI:
|
1 |
az login |
Second, ensure you are using the right subscription.
|
1 |
az account set --subscription {subscription-id} |
Finally (here’s the one liner part), create the App Registration.
|
1 |
az ad sp create-for-rbac -n "your service principal name" |
The response will look something like this.
The az command creates the Enterprise Application, the App Registration and configures it with Contributor permissions on the subscription.
How to setup Postman to query the Azure Management API
Start Postman if you haven’t already. Identify an existing collection you want to add your requests to or, create a new collection (not shown). On the collection, click on the elipses (…), then click Add Request.
On the Save Request popup, enter a sensible name and click the Save button.
In Azure AD, browse back to the App Registration. On the Overview tab, click Endpoints. On the Endpoints flyout, copy the OAuth 2.0 token endpoint (v1) URI.
Paste the URI into the location field in Postman. Also, ensure the verb is set to POST.
Click on the Body tab immediately under the location field. Click the dropdown and select x-www-form-urlencoded.
Four values must be set here: grant_type, client_id, client_secret and resource.
| Key | Value | Comments |
|---|---|---|
| grant_type | client_credentials | |
| resource | https://management.azure.com | This is the Uri of the Azure API you want to use. |
| client_id | A guid | This is found on the Overview tab of the App Registration. It is called “Application (client) ID”. |
| client_secret | A guid | If you created the App Registration using the Azure CLI, this is in the JSON blob that was returned. It is called “password”. |
After configuring the request with those values, test by clicking the Send button. You should get an access token in the response.
Finally, we want to test that we can use the token to query the Resource Groups in my subscription. Create a new request in Postman. Call it something like Get Resource Groups. On the new request tab, set the location field to https://management.azure.com/subscriptions/{subscription-id}/resourceGroups. Set the verb to GET.
Finally, click into the Headers tab immediately under the location field. Here we need to add a key-value pair that will contain the bearer token. Add a Key named Authorization and add the value, which should be Bearer, followed by a space and then the entire bearer token. The screen should look like this when configured.
Click on the Params tab. Add a query string parameter; set the api-version to 2017-05-10.
Now click the Send button.
You should get back a JSON document that shows all of the resource groups in your subscription.
Bonus
The way I have demonstrated configuring Postman is naïve. Postman supports variables that allow you to reuse the values across many queries. It also supports environments so you can have different values for the variables across different environments. Showing how to configure variables in Postman is beyond the scope of this post. However, copying the bearer token from the response of the first query to the to the request of the second query is a little painful. So, I want to share a very cool thing I discovered while researching this post. Insert the following code snippet in the Test tab of the request that uses the bearer token.
|
1 2 3 4 5 |
pm.test(pm.info.requestName, () => { pm.response.to.not.be.error; pm.response.to.not.have.jsonBody('error'); }); pm.globals.set("bearerToken", pm.response.json().access_token); |
In the Headers tab where you would paste in the bearer token, instead, set that to:
|
1 |
Bearer {{bearerToken}} |
Now the token will be saved to a variable and you don’t have to copy-paste it.
There are even better ways to configure this, but again, outside the scope of this post which I have wanted to keep scoped to how to create an App Registration that is configured to allow me to query Azure management APIs.
Conclusion
This post has shown a simple way to create a service principal in Azure that you can use to authenticate to the Azure Management API’s. It also shows how to configure Postman so you can query the APIs.