Setting up PostMan to call the Azure Management APIs#

If you want to test the deployment of API App or LogicApp templates, one of the easiest ways to do this is using the PostMan REST Client for Chrome. In this post I'll show you how to authenticate against your Azure subscription, and show you how to call the API from PostMan. Although all of this information can be found on other sites, I wanted to bring it all into one post, with steps showing you what to do, and explanation of the various parts e.g. what a JWT is, and why the api-version value is so important.

Step 1: Install Azure PowerShell Service Management libraries

If you don't already have it installed, install the Azure PowerShell Service Management libraries.

You can do this from the Web Platform Installer, or by downloading the standalone installer here:

https://github.com/Azure/azure-powershell/releases.

If you have issues, full installation instructions can be found here: https://azure.microsoft.com/en-us/documentation/articles/powershell-install-configure/

The easiest way to check if the libraries are installed is to open Windows Explorer, and type this in the address bar:

%ProgramFiles(x86)%\Microsoft SDKs\Azure\PowerShell\ServiceManagement

If that folder exists, and contains a sub-folder called "Azure", then the libraries are installed.

Step 2: Find out your AAD Tenant Name

There are many ways of doing this.

One way is to sign into the old portal (http://manage.windowsazure.com) and then look at the URL in your browser - specifically the bit after the '@' sign but before the '#' sign:

In the above example, the tenant name is 'MyTenant.onmicrosoft.com' - if you're logged in via a Microsoft Account, then it'll be a variation of your user id or current subscription name followed by 'onmicrosoft.com'.

If you've signed in using an Org Id (i.e. an AAD id) then it'll be the name of the AAD you're using e.g. "contoso.com".

Step 3: Create a powershell script to get JWT

(kudos to Keith Mayer for his excellent article here on how to do this: http://blogs.technet.com/b/keithmayer/archive/2014/12/30/authenticating-to-the-azure-service-management-rest-api-using-azure-active-directory-via-powershell-list-azure-administrators.aspx)

Open notepad (or your favorite text editor), and paste the following in, changing the value "contoso.onmicrosoft.com" (on line 9) to the value obtained in Step 2 above. Save the file with a ".ps1" extension, and save it in a folder where you have security rights to create a file:

# Load ADAL Assemblies

$adal = "${env:ProgramFiles(x86)}\Microsoft SDKs\Azure\PowerShell\ServiceManagement\Azure\Services\Microsoft.IdentityModel.Clients.ActiveDirectory.dll"

$adalforms = "${env:ProgramFiles(x86)}\Microsoft SDKs\Azure\PowerShell\ServiceManagement\Azure\Services\Microsoft.IdentityModel.Clients.ActiveDirectory.WindowsForms.dll"

[System.Reflection.Assembly]::LoadFrom($adal)

[System.Reflection.Assembly]::LoadFrom($adalforms)

# Set Azure AD Tenant name

$adTenant = "contoso.onmicrosoft.com"

# Set well-known client ID for Azure PowerShell

$clientId = "1950a258-227b-4e31-a9cf-717495945fc2"

# Set redirect URI for Azure PowerShell

$redirectUri = "urn:ietf:wg:oauth:2.0:oob"

# Set Resource URI to Azure Service Management API

$resourceAppIdURI = "https://management.core.windows.net/"

# Set Authority to Azure AD Tenant

$authority = "https://login.windows.net/$adTenant"

# Create Authentication Context tied to Azure AD Tenant

$authContext = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext" -ArgumentList $authority

# Acquire token

$authResult = $authContext.AcquireToken($resourceAppIdURI, $clientId, $redirectUri, "Auto")

# Create Authorization Header

$authHeader = $authResult.CreateAuthorizationHeader()

# Output the header value

Write-Host "Bearer Token: $authHeader"

$authHeader | Out-File bearerToken.txt

Step 4: Run the PowerShell script

Right-click on the ps1 file you created in the previous step, and select "Run with PowerShell".

If you don't get this option, then execute the PowerShell console, navigate to the folder where your file is, and execute ".\<name of your script>".

If you can't run the PowerShell console, then make sure PowerShell is installed ☺.

When the script runs, it'll pop up a login window, and prompt you to login to your subscription.

When it finishes running, there will be a file called "bearerHeader.txt" in the same folder as your script.

When you open the file, you should see a very long text string, which starts with the word "Bearer", like this:

Copy the entire contents of that file (should only be one line).

Step 5: Start PostMan and set HTTP Headers

In the Chrome browser, start the PostMan app.

Note: if you're using a different REST client, then the basic principle is the same: all we're doing here is setting two HTTP headers that will be sent with every request).

The steps below assume you're using PostMan 3.x, but the steps for earlier versions are similar enough.

  1. Click on the Headers option:

  1. On the right side, click the Presets link, and click Manage presets:
  2. In the Manage header presets dialog, select the Add button:

  1. In the new header window, give the header a name (I called mine AzureAuthentication), and create the following headers:
    Content-Type = application/json
    Authorization = (bearer token from Step 4 above)


The completed dialog should look like this:

  1. Click the submit button to save the changes, and then close the Manage header presets dialog.

Note: if you have multiple Azure subscriptions, and want to have all of these set up in PostMan, you can do this by creating a separate Environment per subscription, and using variables in your environment to store the bearer token for that subscription - you can then reference your variable in the header preset by using {{variable_name}} as the header value.

Step 6: Use the preset in PostMan

When you want to make a rest call to the Azure Management APIs in PostMan, switch to the Headers tab, click on the Presets link to the right, and select the preset you created:

The headers will be added to the request automatically.

Step 7: Test your authentication settings.

Now we can test the authentication settings.

Let's do a request to Azure to find out details about your subscriptions.

Make sure the HTTP verb is GET, and enter this as the URL:

https://management.azure.com/subscriptions?api-version=2014-04-01

Make sure you've added your headers via the preset - it should look like this:

Now click the Send button.

If everything is set up correctly, you should see something like this:

Great news - it worked!

Now you can start testing other API calls.

You can use the ARM Resource Explorer (https://resources.azure.com) for starters, or just go look at the Azure Resource Management API documentation: https://msdn.microsoft.com/en-us/library/azure/ee460799.aspx.

However, if you see something like this:

...then your bearer token has expired.

Bearer tokens have an expiry time, and the one we requested above expires after 1 hour.

After this time, you'll need to repeat Step 4 to get a new Bearer Token, and then update your preset in PostMan with the new value.

Sidebar: API Versioning

I'm going to cover this in another blog post, specifically with how it relates to API Apps and Logic Apps, but one thing to quickly touch on is the concept of API Versioning.

Microsoft now live in a cloud-first, agile-centric world - and this means that changes come a lot more quickly than they used to.

With APIs, this can cause problems: in the old Windows API world, Microsoft would go to great pains to make sure that older APIs did not ever break, as there were a lot of legacy windows apps that depended on them. This meant that when a change needed to be made to an API, Microsoft would invariably add a new version of an API method/function, often appending "2" or "Ex" to indicate it was a new version (e.g. GetVersion vs GetVersionEx).

With the management APIs, Microsoft have side-stepped this problem by versioning the APIs at various stages.

(I can't see a public link to the Resource Manager API versions, although there is a link to the Service Management API changes here: https://msdn.microsoft.com/en-us/library/azure/gg592580.aspx).

What this means to you, the consumer of the management APIs, is that you get to choose the version of the API you want to use: for example, let's say you built an app using version 2013-10-01.

Even though Microsoft continue to release newer versions of the API, as long as you specify that you wish to use that version, then your application will never break. And when you want to use a newer version, you just specify the required api version in your request. You do this via the api-version query string field.

You'll notice in the above example, we prefix a query string of api-version=2014-04-01.

This has even more meaning when we get on to talk about API Apps and Logic Apps, as the actual methods/operators/function supported in a Logic App are a function of the API version you are using.

Sidebar: JWTs.

JSON Web Tokens (JWT, pronounced JOT) are Base64 encoded JSON items that contain details about security claims.

You can decode a JWT by going to this web site: http://jwt.io/.

The structure of a JWT can be found here: https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32 (with a clearer explanation here: https://scotch.io/tutorials/the-anatomy-of-a-json-web-token).

Let's look at the structure of the JWT that we were issued. Using the JWT.IO website, when we decode the JWT we see this:

(obviously there's not a huge amount to see once you obscure the sensitive info!).

One of the interesting fields is the "exp" field - this gives you the expiry date/time of the token.

It's a date stored in NumericDate format, as defined by IETF.

What this means is that it's a date/time expressed as the number of seconds since Jan 1st 1970 at midnight i.e. 1970-01-01 00:00:00.

In the above example, we have a value of 1436131489 - that's 1,436,131,489 seconds.

We can work out the exact expiry date/time by using this date calculator: http://www.timeanddate.com/date/timeadd.html

If we enter in Jan 1st 1970 at 00:00:00, and add the correct number of seconds:

... we end up with a value of:

Note that the value is assumed to be UTC, which is why it may not match with your current date/time all that well depending on where you live.

Suffice to say, the JWT's you get issued by Azure by the code above are valid for 60mins - after that, you have to get a new JWT.

Wednesday, 08 July 2015 21:37:37 (GMT Daylight Time, UTC+01:00) #    Comments [0]  |  Trackback

 

All content © 2017, Daniel Probert
On this page
This site
Calendar
<2017 March>
SunMonTueWedThuFriSat
2627281234
567891011
12131415161718
19202122232425
2627282930311
2345678
Archives
Sitemap
Blogroll OPML
Disclaimer

Powered by: newtelligence dasBlog 2.3.12105.0

The opinions expressed herein are my own personal opinions and do not represent my employer's view in any way.

Send mail to the author(s) E-mail

Theme design by Jelle Druyts


Pick a theme: