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.

 

Create client #

In order to access resources behind OAuth, the application must first be registered. An application in OAuth is called a client. In our example, we set up a client via the Azure portal. Azure portal – App registrations. As soon as we open the portal via the link above, the dialogue for registering an application opens.

If this does not happen automatically, we click on the following button:

In the registration dialogue we enter a name, the supported types of accounts and forwarding URIs.

Name: Here we assign a name that is displayed to a user of the application. In our example, we set the name to “Matelso Integration Demo”.

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 #

In order to obtain a Refresh & Access token, we must log in to our application with our Microsoft account. To do this, we create a URL with 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

There are 3 placeholders in this URL. We still have to fill in these placeholders. Before we enter the values in the placeholders, they must be URI-coded. This means that certain special characters must be replaced.

The placeholder {ClientId} is replaced by our generated Client Id.

Instead of {RedirectURI} we enter the same Redirect-URI as when we created the client. In my case https://www.matelso-maw.com/ or coded: https%3A%2F%2Fwww.matelso-maw.com%2F
The placeholder {Scopes} is filled with additional permissions, separated by spaces. For example, https://ads.microsoft.com/msads.manage or Encoded https%3A%2F%2Fads.microsoft.com%2Fmsads.manage for the Bing Ads API.

Once we have replaced the placeholders in the URL, we remove the line breaks and open the URL in our browser.

As soon as we have opened this URL, the Microsoft login page opens. Here we log in with our Microsoft account. After logging in, we see which permissions the application requires from us as a user (Consent Screen).

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.

As soon as we have opened this URL, the Microsoft login page opens. Here In OAuth, this code (Auth Code) + Client Id + Client Secret can be exchanged for a Refresh & Access Token pair. To do this, we open Postman and open a new request. we log in with our Microsoft account. After logging in, we see which permissions the application requires from us as a user (Consent Screen).

In this request we choose the method “POST” and set the URL to the following URL.

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

Now we open the tab “Body” and select “x-www-form-urlencode”.

Then we enter various values.

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 pop-up that now opens, we first enter a description. This description is used for your own organization in the account. After the description, we assign a “Parameter name in the DDD browser”. This is required to access the access token in a push configuration. Next, we fill the fields for access and fresh tokens with our generated tokens.

We set the URL to the following value:

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

We then enter a few post-body values:

“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.

matelso platform
matelso optimally connects telephony, chat, email or contact forms. Our intelligent lead management simplifies communication and enables you to achieve better marketing results.
matelso platform in detail
Call Tracking

MarTech phone call analysis software for companies, agencies & portals to get valuable data from inbound calls.

Call Tracking in detail
Marketing Use Case
How the matelso platform boosts your marketing.
Sales Use Case
How the matelso platform boosts your sales process.
E-Commerce Showcase

Showcase of the matelso platform in E-Commerce

Features
What capabilities does our matelso platform offer? All features at a glance.
Consulting
Do-it-with-me instead of DIY: Work with our consultants to really get the most out of the platform.
Consulting
Do-it-with-me instead of DIY: Achieving more together with our consultants.
Use Cases

Three industries that should rely on call tracking: B2B, automotive and agencies!

Learn
Blog Through our blog, we share knowledge and insights with our readers - always useful, always interesting.
Webinars With our matelso webinars, you can experience our MarTech technologies and solutions and get valuable tips for your online marketing.
Knowledge Base On our matelso Knowledge Base you can delve deep into the engine room of our Call Tracking and MarTech technology.

Connect

Career Creating a new data-based era of communication - if you share this vision, we should get to know each other.
Partner model Help your customers better understand and manage their customer journey - while also generating a new revenue stream.

matelso

About Us The MarTech company matelso - we stand for innovative and simple solutions that make your marketing more efficient.
Newsroom News, press releases and more - all news about matelso at a glance.