matelso OAuth Integration (Microsoft 365)

This article explains how to configure an Microsoft OAuth account within the matelso control panel.

What is OAuth?

OAuth is an authorization standard with great adoption within the market. Google and Microsoft are just two examples of companies that protect their services using OAuth.

There are a numbers of extensions to OAuth but within the matelso system we only support the refresh-token flow. RFC6749 Refresh Tokens

This part of the specification is used widely in the server-server context and is therefore how we setup this account.

TLDR: OAuth Refresh Token Flow

A refresh token is a special string that can be used by an application (client) to acquire an access-token via an authorization server. This access-token can then be used to access protected resources or perform actions on resources. eg. sending a mail via outlook or sending data to bing-ads.

Creating an oauth client

To access oauth protected resource you first need to register an application (client) with the oauth server. In our example we create the client using the azure portal. Azure portal - App registrations

After opening the link the page will open a dialog to register an application.

If this doesn't happen automatically you can click on the "new registration" button:

Within the registration dialog we enter a name, the type of supported accounts and our redirect URIs.

Name: This field contains the name of the application that will be shown to users while logging in. 

Type of supported accounts: This input specifies which types of microsoft accounts can login to our application. To make it easy and not explain every subtype of account we just pick "Accounts in any organizational directory (Any Azure AD Directory - multitenant) and personal Microsoft accounts (e.g. Skype, XBox)".

Redirect URIs: The redirect URI is the URI we are redirected to after successful login. In this example I will use my demo page.

After clicking on the "register" button we will be redirected to the details page of our application. On this details page we will find some important information.

Client Id & Client Secret

For the next steps we need to have the client id and the client secret of our newly created application. On the details page we find the Client Id. 

In addition we must create a new client secret. To create a new secret we click on the link on the details page: 

After clicking this link we get redirected to "certificates & secrets". On this page we click "new client secret".

After clicking this button we see a dialog on the right side of the screen.

Within this dialog we fill in our description for the secret and pick the lifetime of this secret. In this example I pick 24 months. We click on the "add" button and copy our newly created secret.

Scopes

After creating the secret we have to add services the application can access (scopes). To add a new service we navigate to "API permissions" and click the "Add a permission" button.

We see a new dialog on the right side. For this example navigate to "Microsoft Graph" -> "delegated permissions" and search for "mail.send". In the filtered results we pick the "Mail.Send" permission and click on "add permissions".

Generate Refresh- & Access-Token

After completing the setup of the application we need to generate a refresh- & access-token pair. To generate these tokens we need to login to our newly created application. We create a new URL using the following pattern:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id={ClientId}
&response_type=code
&redirect_uri={RedirectUri}
&response_mode=query
&scope=openid%20offline_access%20{Scopes}
&state=12345

Within this url there are 3 placeholder. We have to replace each of those placeholders. Before inserting the values for the placeholders we first must url encode our values. 

We replace the placeholder {ClientId} with our newly created client id.

{RedirectURI} will be replaced by our demo redirect url. In this case the redirect URI is https://www.matelso-maw.com/ and after URL encoding: https%3A%2F%2Fwww.matelso-maw.com%2F

{Scopes} can be replaced with additional services/permissions our application wants to use. If you don't need any additional permissions just remove the placeholder. One possible additional permission would be Bing Ads. https://ads.microsoft.com/msads.manage and after encoding https%3A%2F%2Fads.microsoft.com%2Fmsads.manage

After replacing those placeholders we remove the line breaks and open the URL in our webbrowser.

As soon as our browser starts loading the url we get redirected to the microsoft login screen. And after that to the consent screen on which the user has to grant the requested permissions.

We grant all the requested permissions by simply clicking on "yes" and get redirected to our redirect-uri. It is important to note that the URL we get redirected to includes additional values (code and state). The state parameter contains the same state as our login url and can be ignored. The code parameter contains our auth code which we can exchange for and access-&refesh-token pair. 

To exchange our auth code, client id and client secret for an access- & refresh-token pair we need to send an post request to the token endpoint. To do this we use Postman.

Inside of postman we open a new request and pick "POST" as method. After that we fill in the url of the token endpoint:

https://login.microsoftonline.com/common/oauth2/v2.0/token

Now we open the "body" tab und pick "x-www-form-urlencode".

After that we fill in some key-value pairs.

As "client_id" we insert our client id.

For "scope" we insert our requested services & permissions again. 

"code" needs to be filled with our auth code from the redirect url.

As "grant_type" we use "authorization_code". This tell the token endpoint that we want to exchange our auth code for an access- and refresh-token pair using the code flow.

"client_secret" needs to be set to the client secret we created.

Now we click and send and see that the response contains 3 tokens. "access_token", "refresh_token" and "id_token". We only care about access and refresh. We copy those tokens and log in to the matelso control panel.

Microsoft OAuth within the matelso control panel

To add an OAuth account in the matelso control panel we navigate to "Configuration"->"Integrations 2.0" and open the accounts tab.

On this page we click the "+" button and select "OAuth Account" in the dropdown menu.

In the newly opened modal we first fill in the description. This description field is only used to organize yourself in the partner id. After the description we pick an "Parameter name in the DDD browser". Now we copy our access and refresh token in the corresponding fields and set the url to the token endpoint. 

https://login.microsoftonline.com/common/oauth2/v2.0/token

Now we configure the post body for the token endpoint.

"scope", "client_id" and "client_secret" get filled the same way as in our postman request. 

The "grant_type" will be "refresh_token" this time. This tells the token endpoint that we want to use our refresh token to get a new access token.

And last but not least we set the "refresh_token" field to our refresh token.

After clicking on "save" we can use the access token in push configurations using the DDD Browser.