matelso OAuth Integration

In diesem Artikel konfigurieren wir einen Google OAuth Account im Control Panel.

Was ist OAuth?

OAuth ist ein Autorisierungsstandard der in einer wachsenden Anzahl von Diensten verwendet wird. Beispielsweise werden APIs von Google und Microsoft durch OAuth geschützt.

Da es unzählige unterschiedliche Implementierungen und Erweiterungen des Standards gibt, wird von matelso nur der Refresh Token Flow unterstützt. RFC6749 Refresh Tokens

Dieser Teil des Standards findet besonders in der Server-Server Kommunikation häufig Anwendung und wird als Kern der meisten OAuth Implementierungen unterstützt. 

TLDR: OAuth Refresh Token Flow

Ein Refresh Token ist eine spezielle Zeichenfolge mit der eine Anwendung (Client) über einen Autorisierungsserver einen Access Token abrufen kann. Mit diesem Access Token kann die Anwendung (Client) dann auf geschützte Ressourcen zugreifen. Beispiel: E-Mails via GMail versenden.

Client anlegen

Um auf Ressourcen hinter OAuth zugreifen zu können, muss als erstes die Anwendung registriert werden. Eine Anwendung in OAuth heißt Client. In unserem Beispiel richten wir einen Client in der Google Developer Console ein.

Wir öffnen den Link Client anlegen und füllen das Formular aus.

Als autorisierte Weiterleitungs-URL (Authorised redirect URIs) tragen wir den Google OAuth Developer Playground ein. 

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

Wir nutzen den OAuth Playground um initial einen Refresh Token zu erzeugen und diesen dann im CP zu hinterlegen.

Nachdem wir den Client angelegt haben, sehen wir die dazugehörige Client Id und das Client Secret.

Refresh Token & Access Token im OAuth Playground erzeugen

Nachdem unser Client angelegt wurde öffnen wir den OAuth Playground. Hier klicken wir auf das Zahnrad oben rechts um unsere Client Id & Client Secret zu hinterlegen.

Nachdem wir unsere Werte gesetzt haben, schließen wir das Pop-Up und wählen auf der linken Seite aus auf welche Scopes wir Zugriff benötigen. Für unser Beispiel wählen wir nur "https://www.googleapis.com/auth/gmail.send". Dieser Scope ist in der Gruppe "GMail API v1" zu finden. 

Sobald das erfolgt ist, klicken wir auf "Authorize APIs". Wir werden jetzt auf die Anmeldeseite von Google weitergeleitet. Nachdem wir uns angemeldet haben leitet uns Google auf die Consent-Seite weiter. Hier müssen wir bestätigen das wir unserem Client den Zugriff auf die ausgewählten Scopes gewähren. Danach leitet uns Google wieder auf den OAuth Playground weiter. 

Auf der linken Seite sehen wir jetzt unseren Authorization Code. Wir klicken jetzt auf "Exchange authorization code for tokens" um unseren Refresh Token & Access Token zu bekommen.

OAuth Account im matelso Control Panel einrichten

In diesem Schritt öffnen wir das matelso Control Panel und navigieren zu "Konfiguration"->"Integrations 2.0" und wechseln in den Tab "Accounts".

Hier klicken wir auf den "+"-Button und wählen im Dropdown "OAuth Account" aus.

In dem jetzt geöffneten Pop Up tragen wir als erstes eine Beschreibung ein. Diese Beschreibung dient zur eigenen Organisation im Account. Nach der Beschreibung vergeben wir einen "Parameter Name im DDD Browser". Dieser wird benötigt um in einer Push Konfiguration auf den Access Token zuzugreifen. Danach befüllen kopieren wir unseren Access- und Refresh-Token vom OAuth Playground in die entsprechenden Felder. 

Als letzten Punkt tragen wir noch eine URL ein. Diese URL hat im Fall von Google folgendes Muster:

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

In diesem Muster muss ich die 3 Platzhalter{(in geschweiften Klammern} mit meinen Werten ersetzen. 

Nach dem eintragen der Werte klicken wir auf "Speichern". 

Die Einrichtung unserer OAuth Authentifizierung ist damit abgeschlossen und ich kann im DDD Browser den Access-Token auswählen.