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 SDKsAzurePowerShellServiceManagement
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 SDKsAzurePowerShellServiceManagementAzureServicesMicrosoft.IdentityModel.Clients.ActiveDirectory.dll”
$adalforms = “${env:ProgramFiles(x86)}Microsoft SDKsAzurePowerShellServiceManagementAzureServicesMicrosoft.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.
The completed dialog should look like this:
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.
