Tag: PostMan

Tools to call Microsoft Graph API endpoints as a User and application

This blogpost will help you to explore and interact with MS graph API endpoint’s using the following tools

  • Postman client
    • Signed in as a user/On-behalf-of API call (Delegated permission)
    • Application/daemon API call (Application permissions)
  • Graph Explorer

I have used MS graph extensively on different MS cloud services like SharePoint, PowerAutomate, PowerApps, Azure services like Azure functions and on devices like Raspberry Pi. It is a very powerful service in Microsoft 365 platform. Let start with some basics

Introduction:

MS Graph API is a RESTful web API which enables you to access different Microsoft 365 cloud service resources through its unified programmability model.

Microsoft Graph exposes REST APIs and client libraries to access data on the following Microsoft cloud services:

  • Microsoft 365 services: Delve, Excel, Microsoft Bookings, Microsoft Teams, OneDrive, OneNote, Outlook/Exchange, Planner, SharePoint, Workplace Analytics.
  • Enterprise Mobility and Security services: Advanced Threat Analytics, Advanced Threat Protection, Azure Active Directory, Identity Manager, and Intune.
  • Windows 10 services: activities, devices, notifications, Universal Print (preview).
  • Dynamics 365 Business Central.

Permission Types:

MS Graph exposes granular permissions that controls the access of the apps that has to the different resources like sites, users, groups etc. There are two types of permission

  • Delegated permissions are used by apps that have a signed-in user present. For these apps, either the user or an administrator consents to the permissions that the app requests and the app can act as the signed-in user when making calls to Microsoft Graph.
  • Application permissions are used by apps that run without a signed-in user present. For e.g Apps that run as background services or daemons. Application permissions can only be consented by an administrator.

Access token:

To call a MS Graph API all you need is an access token in the authorization header of an HTTP request.

GET https://graph.microsoft.com/v1.0/me/ HTTP/1.1

Host: graph.microsoft.com

Authorization: Bearer EwAoA8l6BAAU … 7PqHGsykYj7A0XqHCjbKKgWSkcAg==

The access tokens are issued by the Microsoft identity platform which contains information to validate if the requestor has appropriate permissions to perform the operation they are requesting. An active directory app is a pre-requisite to generate an access token to call a Graph API endpoint.

There are also Microsoft identity platform authentication libraries for .NET, JS Android, Objective-C, Python, Java, Angular facilitating validation, cookie handling, token caching and on maintaining a secure connection. Let’s now go ahead and see the tools

MS Graph Explorer:

Graph explorer is a web-based tool which can be used to build and test requests using Microsoft Graph API. The explorer can be accessed from the following URL:

https://developer.microsoft.com/en-us/graph/graph-explorer

There will be a default Active directory application on the Organizational Active directory of the M365 tenant by the name Graph Explorer with application id de8bc8b5-d9f9-48b1-a8ad-b748da725064. This app can be accessed from the Enterprise applications blade of the Active directory as shown below

Delegated permissions are used by Graph Explorer. Based on your access role & admin consent’s you would be able to call different Microsoft Graph API from this tool. After you have signed into the Graph Explorer tool, the access token will be generated automatically

To view the token information, copy the token and paste it on the utility https://jwt.ms/

If your token has a scp (Scope) claim, then it’s a user based token (Delegated permissions). It is a JSON string containing a space separated list of scope the use has access to call different graph endpoints. You can also find other information related to the issued token, token issued at (iat), expirty not before (nbf), expiry time (exp). The data is in UNIX time stamp but you can convert this information to standard time using the online URL

https://www.epochconverter.com/

More information about JWT can be found at

https://auth0.com/docs/tokens/json-web-tokens

Postman Client:

Postman is a tool that can be used to build and test requests using the Microsoft graph API’s. To use this tool for testing the Graph API endpoint’s, register an app in Azure Active directory as per the instructions from this blog post. Provide the permission (Delegated & Application) as per your need to test it using Postman.

Copy the client id, client secret & tenant ID of the registered app. To access the various endpoints like authorization and token, click on the Endpoints from the Overview section of the Active directory app.

Setting up the environment using Postman collections:

There are Postman collections with many MS graph API requests created by Microsoft for us to explore. Import the collections and setup the environment (Client ID, Client secret, tenant id) for Application API calls and on-behalf-of API calls as per the instruction from the following article

https://docs.microsoft.com/en-us/graph/use-postman

Application API Token:

To generate an application token, make a POST request to Get App-Only Access Token from the collection Microsoft Graph. The grant_type is client_credentials since it is Application permissions.

Token Validity:

The token is valid for 3599 seconds which is 1 hour. Post that the token will expire, you will have to regenerate the token by making another call.

The AccessToken (Application API call) will be generated and automatically stored on the Environment (Microsoft Graph environment) AppAccessToken with the help of a script on the Tests tab in Postman. Copy the access token value & paste it on the utility https://jwt.ms/. Find the decoded token below which has information like the Application ID/client id of the AD app, display name and roles to which the app has access to poll the graph endpoint.

Graph API call:

The call to the Graph should have the bearer token

Signed-in user/on-behalf-of API Token:

To generate a Signed-in user token, make a POST request to Get user Access Token from the collection Microsoft Graph. The grant_type is password since it is delegated permissions.

The AccessToken (Signed-in user API call) will be generated and automatically stored on the Environment (Microsoft Graph environment) UserAccessToken with the help of a script on the Tests tab in Postman.

Copy the access token value & paste it on the utility https://jwt.ms/. Find the decoded token below which has information like the Application ID/client id of the AD app, display name and scopes (scp) to which the app has access to poll the graph endpoint. If you remember the Application API token had roles & not scopes, so this is how you can identify the token type.

Storing the production User ID and password is not recommended on the Environmental variables since the information is stored in Postman but this can be handled by generating an access token from the request Authorization tab, set the type as OAuth 2.0 and click Get New Access Token button

Fill in all the information gathered from the App in Azure AD like Appid, Secret, Endpoints (Authorization and Token), state can be any random value

Click Request token, this will prompt the user to enter the Username and password. After authentication, it will generate the token which could be used further to make API calls.

Graph API call:

The call to the Graph should have the bearer token on the Authorization tab or on the Headers tab

Summary: On this post we have seen how to use tools like Graph explorer & Postman to test different MS graph API endpoints. You can make requests like GET, POST, PUT, PATCH, DELETE based on its availability. Refer to the Microsoft documentation for v1.0 and beta endpoints. Once you have explored & tested the API, you are ready to use on applications using the available SDK’s for different programming languages. Let me know any feedback or comments on the comment section below

Post a Teams Conversation on a Channel using API call/HTTP Request

On this blog post, I am going to cover different options to post a Teams conversation in a Teams channel using API call.

  • Using a Flow with HTTP Request trigger & Flow action
  • Create an Incoming Webhook in Teams
  • Graph Endpoint to create a Teams conversation

I do now see more requirements from customer to integrate Teams with different applications. These options for posting a message in a Teams channel could be to used on an External application or from a SharePoint Site using SPFx.

Create a Flow with HTTP Request trigger

Create an Instant flow with Trigger “When a HTTP request is received” a premium trigger which gets triggered to a HTTP request. This is a responsive trigger as it responds to an HTTP Request. The structure of the requests/responses that Microsoft Flow uses is a RESTful API web service known as REST. The API or HTTP post URL will be generated only after the flow is saved with at least one action.

Let’s say I would like to post a Teams conversation with @mention to a specific user and some message. In this case I will have to pass the information either in Parameters or on the body of the call. On this example we will be passing the information on the request Body

{
    "To":"ashiqf@####.onmicrosoft.com",
    "Message": "Hello from HTTP Request"
}

Copy the above sample and paste it on the popup you get after clicking on Generate Schema. The tool will automatically generate the JSON schema for you. Also jsonschema.net could be used to generate the schema

Find the generated schema below for the information email address & message which would be passed on the request body while making the POST call

Add the action “Post a message as the Flow bot to a channel”, this will create a Teams conversation on a specific channel in a Team. On the below screenshot, look at the way I am doing @mention to a user, leaving a New line & making a text appear Bold

After you save the flow, the HTTP Post URL will be generated for us to use in an external application or where ever we want. The API is not secured its anonymous. Lets now use Postman client to trigger. Don’t forget to set the headers for content-type to application/json, Information on the body & method to POST else the trigger will fail

After the Post button is clicked on Postman client which would then trigger the flow. The message on Teams channel will appear as shown below

In Postman client, there is an option to generate the code to call the API for different programming languages

As already said, the HTTP post URL is anonymous. If you would like to secure the flow actions, you could do it after the flow is triggered with some validations. If you look at the output from the Flow run for the Trigger, there is information on the field “User-Agent”, with this information you would able to add some validations

Create an Incoming Webhook in Teams for a Specific channel

Incoming webhooks could be used to create Teams Conversations on a specific channel on a team. It’s special type of Connector in Teams that provides a simple way for an external app to share content in team channels

To create a Webhook, go to the Teams channel where you would like to have the conversation posted. Click connectors

Create Webhook

Look for Incoming Webhook from the list of connectors then click Add

Provide a Name for the webhook and click Create. Now the URL will be generated, click Done

The generated URL will be on this format, get this copied

https://outlook.office.com/webhook/24a&&546-75a8-4a24-b935-d1dbea060####@GUID/IncomingWebhook/GUID/GUID

I will now use post man to create a conversation in Teams, it has to be Post request with the information passed on the Body. The header information is not required for this POST call

{"text":"<b>Post using Incoming Webhook</b><br>Message from External Application!"}
Postman Client
Teams Channel conversation

Ref: https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook

Refer the below Microsoft documentation which has some example to create an Adaptive card in teams

https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using

Graph Endpoint to create a Teams conversation

There is also endpoint (REST) available in MS-Graph to post/create a Teams conversation. The time I am writing this post, its a Beta endpoint and its not recommended for production use

POST /teams/{id}/channels/{id}/messages

The ID of the Teams and the Channel ID must be passed along with the bearer Token to create a team’s conversation. To get the bearer token create a Azure AD app with API permissions for Graph to create a message. The permission could be either Delegated or Application permissions based on the requirement. There are lot of articles which covers the steps to create an App in Azure so am not going to cover those in this post.

Ref: https://docs.microsoft.com/en-us/graph/api/channel-post-messages?view=graph-rest-beta&tabs=http

Summary:

I’ve described different ways to create team’s conversation using API calls. Hope you find this post informative & useful. If you have any comments or questions, let me know on the comment section.