Use HTTPV2 integration to execute ANY API for Azure Products - Guide

[ylandovskyy]

In this guide, I am going to showcase, how to use the HTTPV2 integration to execute API requests to Azure products like Microsoft Graph. Main emphasis will be on the authentication, as everything else is covered by this guide.

Azure Authentication

In Azure, authentication is done via an App that you need to create inside "App Registration" section of Azure portal. Depending on the specific API within products, you will need to either define delegated or application permissions to the App, to be able to execute necessary API requests.

How to create an Azure App

1. Press on "New registration" under "App Registration Section"

2. Fill out the information about the App. To make it easier, setup the redirect url to be "https://localhost". This URL is used during authentication via Delegated workflows.

3. In the App overview page you will find Client ID and Tenant ID. Those 2 variables are critical for API.

4. Generate the Client Secret

5. Save the Client Secret. Note: the value is stored under "Value" colunm, not "Secret ID"

6. Add Necessary Permissions

Delegated Workflow

Delegated Workflow - flow, when you provide an app ability to execute API requests on behalf of the impersonated user.

In simple words, during the delegated flow all of the API requests will be executed as if a real User did it. For example, in Microsoft Teams integration you can send a message and if I configured the integration with my user impersonated, then all of the messages will be send from my name. They will be completely identical to the ones that I would send myself on Teams App.

This flow is a little bit challenging for the SecOps infra, as during the creation of credentials, in order to do the impersonation you need to login to Azure portal with your creds. Currently, SecOps doesn't support popups during integration/action configuration, which means that you need to manually copy authorisation link into the browser and then also manually copy the authorisation code, which will then be used to get "refresh_token". 

In general, due to this constraint, HTTPV2 integration is not going to work flawlessly, as "refresh_token" expires every 90 days and there is no way to extend that lifecycle, but if you are okay with generating the refresh_token every 90 days, then you can still make it work.

If you want to generate refresh_token using existing SecOps tools, then you should refer to Microsoft Teams integration documentation. It guides through all of the steps that are needed to get the refresh_token.

The configuration of the HTTPV2 integration for delegated flow will need to be like this:

Dedicated Auth API Request Method	Post
Dedicated Auth API Request URL	https://login.microsoftonline.com/{tenant id}/oauth2/v2.0/token
Dedicated Auth API Request Headers	{ "Content-Type": "application/x-www-form-urlencoded" }
Dedicated Auth API Request Body	{ "client_id": "{client id of the app}", "client_secret": "{client secret of the app}", "refresh_token": "{generated refresh token}", "grant_type": "refresh_token", "redirect_uri": "{redirect uri from the 2nd step}" }
Dedicated Auth API Request Token Field Name	access_token

If everything is done correctly, you expect to see the green checkmark:

Application Workflow

Application Workflow - flow, when the API is executed on behalf of the App itself.

Overall, this flow is significantly more simple, because you just to have Client ID and Secret in order to perform authentication, but a lot of API requests may not be supported for this flow.

The configuration for HTTPV2 integration will be almost identical, only the body payload will be slightly different.

Dedicated Auth API Request Method	Post
Dedicated Auth API Request URL	https://login.microsoftonline.com/{tenant id}/oauth2/v2.0/token
Dedicated Auth API Request Headers	{ "Content-Type": "application/x-www-form-urlencoded" }
Dedicated Auth API Request Body	{ "client_id": "{client id of the app}", "client_secret": "{client secret of the app}", "grant_type": "client_credentials", "scope": "{scope of your api (https://graph.microsoft.com/.default as example)}" }
Dedicated Auth API Request Token Field Name	access_token

If everything is done correctly, you expect to see the green checkmark:

Note: at any given point of time, you can only authenticate either with Delegated or Application permissions, but not both at the same time. 

How to understand what permissions are needed

Information about the necessary permissions is available inside the official documentation. Let's take as an example API request called "List Users" from Microsoft Graph API documentation. As part of the documentation page for API, there will be a section called "Permissions":

This section explains what API permissions are needed to execute this API request. In this case, the API endpoint supports both delegated and application workflows. 

Currently, permissions for my App look like this:

But I don't want to do impersonation, so instead I will add new Application permission "User.Read.All", so that I can authenticate with a simpler flow.

This permission requires Admin Consent, so you will need to provide with a "Grant Admin Consent ..." button.

After everything is done, you should see green checkmark.

Now my application will be able to execute ANY API request that requires "User.Read.All" permissions. Let's do a test.

Here is an example of "Execute HTTP Request" action needed to run "List Users" method.

In the headers, you need to make sure that you will put "Authorization" with "Bearer {{integration.token}}" value. This will tell our actions, where to put the generated access token.

As we can see, the action ran successfully. 

If you want to understand better, how to use HTTPV2 integration, refer to this guide.

Conclusion

HTTPV2 integration is a flexible tool that you can use to work with Azure stack of products.

If there are any integrations for which you would like a similar guide, please share it in the comments!