Share via


How to Call Azure Stack API via Client Credential Grant

In order to manipulate Azure stack resource by programming, we can call the Azure Stack API to make it. As both of Azure and Azure Stack share the same API surface, if you have been working on API programming in Azure before, it will be very easy to make your current application support azure stack. What needs to be done is just to authenticate to the Microsoft Azure login endpoint. The endpoint will return a token to use in the header of every request sent to the Azure Stack API.
The Microsoft Azure login endpoint support several different OAuth 2.0 grant, I will use client credential here as it doesn't need expose an account password and very suitable for an automation scenario. Before the below process, we need make sure the azure stack has been deployed using Azure AD as the identity store. Also, the tenant user should have created his own subscription from tenant portal.

Create Service Principal in Azure AD

Firstly, we need create an application (service principal) in Azure AD that represents your application.

  1. Sign in to the Azure portal to which the Azure stack is registered.
  2. Select Azure Active Directory > App registrations > New application registration.
  3. Provide a name and URL for the application. Select either Web app / API or Native for the type of application you want to create. After setting the values, select Create.

We should be able to get the application id shown below and also the key in Keys tab. Save both of the application id and key, we will use them later.

Assign Contributor Role to Service Principal

Currently, the service principal doesn't have any permission to the subscription in Azure stack, we need assign it as contributor role for to the subscription, certainly you can assign owner or reader as well.

  1. In the Azure stack tenant portal, navigate to the subscription page, select Access Control(IAM) tab.
  2. Select Add, select contributor role, select the application which is just created above. If the application is not listed, use the application id to search shown below.

Retrieve Token from Azure

Firstly, we need access Azure Stack management endpoint https://management.{region}.{Azure Stack domain}/metadata/endpoints?api-version=2015-01-01 to figure out the azure stack's management resource url.
The audiences section in the response is the desired resource url. Notice that the url is for tenant user, if you want to perform cloud admin operation mentioned in https://docs.microsoft.com/en-us/rest/api/azure-stack/, please access https://adminmanagement.{region}.{Azure Stack domain}/metadata/endpoints?api-version=2015-01-011
Next, we will create a request body formatted using the content type x-www-form-urlencoded shown below to obtain an access token. POST your request to the Azure REST Authentication and Login endpoint https://login.microsoftonline.com/{tenant id}/oauth2/token. The tenant id can be tenant domain as well.

 
grant_type=client_credentials
&client_id=<the application id retrieved in the first step>
&client_secret=<the application key retrieved in the first step>
&resource=<the resource url just retrieved>
&scope=openid

The access_token section in the response is the expected token which will be used in the later API call.

Call Azure Stack API

Once you get your access token, you need to add it as a header to each of your API requests. In order to do so, you need to create a header authorization with value: Bearer <access token>. For more information about all the available APIs, see Azure REST API Reference.

Reference

https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-oauth2-client-creds-grant-flow
https://docs.microsoft.com/en-us/azure/azure-stack/user/azure-stack-rest-api-use
https://docs.microsoft.com/en-us/azure/azure-stack/azure-stack-create-service-principals