matelso OAuth integration

This article explains how to setup an Google OAuth account in 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 gmail.

Create an OAuth client in Google

To access protected resources in the google services we first need to register our application with google. Within OAuth an application is called "client". In our example we setup a client using the Google Developer Console.

We click the following link to open the form. Link to Form

We set up the Google OAuth Playground as authorized redirect URI.

https://developers.google.com/oauthplayground/

We use the OAuth Playground to initially create our refresh- and access-token pair. After generating we will implement them into the control panel.

After the client setup we see our client Id and client Secret. This is important information. So keep them save.

Generate Refresh Token & Access Token in OAuth Playground

After creating our client we open the OAuth Playground. Within the OAuth Playground we click the settings button in the top right corner

and fill in our client Id & client Secret. 

After setting our client details we take a look at the left side and pick the scopes we want to access. In our example we select "https://www.googleapis.com/auth/gmail.send" in the group "GMail API v1".

After selecting our scope we click "Authorize APIs". Now the OAuth Playground will redirect us to the google login page. During the login flow we need to accept that our client can access the selected scopes.

After that Google redirects us back to the OAuth Playground again.

We now see an "Authorization Code" on the left side of the playground. This code can be exchanged for an refresh- and access-token pair. We click on "Exchange authorization code for tokens" and see that the refresh- and access-token fields are filled.

Setup OAuth Account in the matelso control panel

To setup the OAuth account in the control panel we navigate to "Configuration"->"Integrations 2.0" and select the "Accounts" tab.

On this page we click the "+"-button and pick "OAuth Account" from the dropdown.

In the now visible modal window we fill in the description. The description is just for our own use to organize the control panel. After the description we set up the "Parameter name in the DDD Browser"-field. This value will be used in our DDD Keys while accessing the access-token in an push configuration. After that we fill in our access- and refresh-token from the playground in the given fields. The last field we need to setup is the URL. For Google Authentication the url is as follows:

https://oauth2.googleapis.com/token?client_secret={client_secret}&grant_type=refresh_token&refresh_token={RefreshToken}&client_id={clientId}

Within this URL we need to replace the 3 placeholders (client_secret, RefreshToken, clientId) with the values we got from google earlier.

After filling in all our values we click "save".

Now we successfully set up an OAuth account in the matelso control panel. To use the access-token in our push configurations we pick the corresponding DDD key from the DDD browser.