Handling Microsoft Graph API Auth

Aka – making secure calls to Microsoft Graph API Endpoints

Microsoft Graph APIs are at the heart of everything Microsoft does but they’re not entirely straight forward to monitor or even call successfully – something even Microsoft can struggle with. Fortunately, this is a relatively easy problem to solve.

Overview

Microsoft Graph is an OAuth based service but has some additional layers which mean our Wizard doesn’t handle it directly ‘out of the box’ – instead we recommend a 2 stage workflow with environment variables set for your organization or project:

Workflow 1 will contain a single call which initiates the call to kick off the sign in process where you authenticate the service – this will uses unique GUIDs that are passed to Microsoft to be used in the generation of the tokens

Workflow 2 – contains a single call which obtains the access token, the expires in timing and sets the refresh token

The variables this process sets will be used in our security configuration to then handle ongoing authentication.

This will let you get an OAuth Token from Microsoft Graph, but we’ll need to add a final stage to handle a Refresh Token cleanly and securely so you don’t have to set it manually.

Basic Configuration for Microsoft Graph API Auth

In the “Environment Variables” menu set the following variables:

Client_id – provided by your Microsoft application

Client_secret – all provided by Microsoft Graph API Auth

Redirect_uri – this is the callback setting to allow Microsoft to know what to do after sign in – this will be https://client.apimetrics.io/tokens/callback

Scope – you’ll obtain this from Microsoft for the service you are authenticating the call to reach – more details can be found here: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent

Once they are set you need to create 3 API calls.

Call 1 – OAuth: Authorize – using the POST method you should enter something like this – note you don’t need to put a body for this URI

The call here uses 2 system variables we generate for you as well as the environment variables we set first.

Finally, this call needs to know to open the browser and make the authenticate call, so in the META tab, you need to add the following:

apimetrics:browser

Now when you run the call it will trigger the web browser to open.

 Call 2 – OAuth Access Token – to be triggered AFTER you’ve authenticated with your log in should look like this and when it’s setup, you should click on the CONDITIONS tab.

In the Conditions Tab you’ll need to set the variables we will be using for actual calls.

This will look something like this.

Call 3 – Refresh Token Auth

This will be called to refresh the authentication once we have everything set up, so you don’t have to worry about going in every time a token expires.

Once this is done, we recommend creating 3 worlflows, one for each of these API calls and naming them something like:

• Auth Step 1: (scope reference) Step 1 / 2
• Auth Step 2 (scope reference) Step 2 / 2
• OAuth: Refresh Token

Next we set up the security setting and token we will use.

Configure Security Settings and Tokens

We now need to set up a way to tell the APIs you create what Auth settings to use – you’ll have seen that already in the screen shots but now we set it up.

APImetrics handles security separate to the API calls, so you can set up a type of authentication and a token and then you can apply that to lots of calls without having to create and edit the security for each different API call you monitor.

Go to Auth & Tokens in the side navigation menu. Select ‘Create New Authentication’ – because the Microsoft Graph system is a little non-standard for an OAuth service we’re going to select ‘Manual Auth’

Things to note:

1) We do recommend adding the Endpoint domain that this auth will apply to – this will make it easier to track moving forward

2) Authentication Type is Manual Setup – don’t use the OAuth options

3) Select the OAuth: Refresh Token Workflow

4) It’s worth filling in the meta data fields so you can easily find docs later

5) Finally, under ‘Refresh Token Workflow’ select the Refresh Token Workflow you configured first. 

Save the configuration.

We can now create our first token to use with this auth. All the API will need is a header to be set with the following parameters: Authorization: Bearer (token number)

Create the Token and give it a name, then select enter values manually and set a header with:

Authorization with the parameter Bearer %%ACCESS_TOKEN%% – which is the variable we set in the work flow we created.

Pulling It All Together

Step 1 – Authenticate to service. Run Workflow 1 / 2 and sign in to the service

When you arrive back at the Callback screen, select Workflow 2 / 2 from the menu and run it. You should now have valid tokens!

Now go to the API call and select ‘RUN NOW’ from the top left.

This should run and pass.

From now on we’ll handle things for you, whenever the Token expires, the Refresh Token workflow will be triggered in the background and will automatically update the tokens for you.

Run a Microsoft Graph API call

Create an API call to your endpoint and select your Security Method and add the name of your auth settings and the token name to use.

Click Run Now to test – it should pass.

Start Monitoring your Microsoft Graph APIs

Select Monitor and pick a schedule and off you go!