In diesem Artikel konfigurieren wir einen Microsoft 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 der Client dann auf geschützte Ressourcen zugreifen. Beispiel: E-Mails via Office 365 versenden oder Daten an Bing-Ads übertragen.

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 über das Azure Portal ein. Azure portal - App registrations. Sobald wir das Portal über den obigen Link öffnen, öffnet sich der Dialog zum registrieren einer Anwendung.

Wenn das nicht automatisch passiert, klicken wir auf folgenden Button:

Im Registrierungsdialog geben wir einen Namen, die unterstützen Arten von Accounts und Weiterleitung-URIs ein.

Name: Hier vergeben wir einen Namen der einem Nutzer der Anwendung angezeigt wird. In unserem Beispiel setzen wir den Namen auf "Matelso Integrations Demo".

Art der unterstützen Accounts: Hier wählen wir aus, welche Arten von Accounts sich in dieser Anwendung anmelden dürfen. Der Einfachheit halber wählen wir den mittleren Punkt mit allen AD Accounts und persönlichen Konten aus.

Weiterleitung-URIs: Hier geben wir eine URL an, auf die wir nach der Anmeldung weitergeleitet werden. Da wir den OAuth Prozess manuell durchführen, gebe ich meine Demo-Website an.

Wir klicken auf den "Registrieren" Button und werden nach dem Anlegen unserer Anwendung auf die Detailseite unserer Anwendung weitergeleitet.

Client Id & Client Secret

Um weiter fortzufahren benötigen wir die Client Id und den Client Secret. Auf der Übersicht der Detailseite unserer Anwendung sehen wir die Client Id (bei Microsoft "Application (client) ID".

Außerdem müssen wir noch einen Client Secret erzeugen. Hierzu gibt es auf der Übersichtsseite auch einen Link:

Nachdem wir auf diesen Link geklickt haben, werden wir zu den "Zertifikaten & Secrets" weitergeleitet. Auf dieser Seite erzeugen wir uns einen neuen Client Secret.

Nachdem wir diesen Button geklickt haben, öffnet sich auf der rechten Seite ein Dialog in dem wir dem Secret eine Bezeichnung geben und die Laufzeit auswählen.

Wir geben eine Bezeichnung ein und wählen 24 Monate aus. Danach klicken wir auf Hinzufügen. Danach sehen wir in der Liste der Client Secrets unser angelegtes Secret. Wir kopieren uns den Wert des Secret.

Scopes

Nachdem wir unsere Client Id und unser Client secret haben, definieren wir auf welche Bereiche (Scopes) die Anwendung Zugriff haben soll. Hierzu navigieren wir zu "API Berechtigungen" und klicken auf "Berechtigung hinzufügen".

Es öffnet sich erneut ein Dialog auf der rechten Seite. Hier wählen wir für unser Beispiel "Microsoft Graph" -> "Delegierte Berechtigungen" und geben in das Suchfeld "mail.send" ein. Danach klappen wir "Mail" auf und setzen einen Haken bei "Mail.Send". Sobald diese Auswahl getroffen ist klicken wir auf "Berechtigung hinzufügen". Mit "Mail.Send" kann unsere Anwendung E-Mails im Namen des angemeldeten Benutzer versenden. Es können bei der Login-Anfrage noch weitere Berechtigungen angefordert werden.

Refresh- & Access-Token erzeugen

Um einen Refresh- & Access-Token zu erhalten müssen wir uns mit unserem Microsoft Account in unserer Anwendung anmelden. Hierzu erzeugen wir uns eine URL mit folgendem Muster.

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

In dieser URL sind 3 Platzhalter enthalten. Diese Platzhalter müssen wir noch ausfüllen. Bevor wir die Werte in die Platzhalter eintragen müssen diese aber URI-Codiert werden. Das bedeutet es müssten bestimmte Sonderzeichen ersetzt werden.

Der Platzhalter {ClientId} wird durch unsere erzeugte Client Id ersetzt.

Statt {RedirectURI} geben wir die gleiche Redirect-URI an wie beim erzeugen des Client. In meinem Fall https://www.matelso-maw.com/ oder codiert: https%3A%2F%2Fwww.matelso-maw.com%2F

Der Platzhalter {Scopes} wird mit zusätzlichen Berechtigungen, durch Leerzeichen getrennt, befüllt. Beispielsweise https://ads.microsoft.com/msads.manage oder Codiert https%3A%2F%2Fads.microsoft.com%2Fmsads.manage für die Bing-Ads API.

Sobald wir die Platzhalter in der URL ausgetauscht haben, entfernen wir die Zeilenumbrüche und öffnen die URL in unserem Browser.

Sobald wir diese URL geöffnet haben, öffnet sich die Microsoft Login-Seite. Hier melden wir uns mit unserem Microsoft-Konto an. Nach der Anmeldung, sehen wir welche Berechtigungen die Anwendung von uns als Benutzer benötigt (Consent-Screen).

Wir erteilen die Berechtigungen, indem wir auf "Ja" klicken und werden auf unsere Redirect-URI weitergeleitet. Hier ist ganz wichtig, dass im URL Feld des Browsers zusätzlich zu unserer Redirect-URI noch zwei Parameter angehängt wurden. "code" und "state". Der "state" Parameter enthält den Wert aus unserer Login URL. Dieser Code ist wichtig für den nächsten Schritt und sollte von uns herauskopiert werden. Der Code beginnt nach "?code=" und endet vor "&state...".

In OAuth kann dieser Code (Auth Code) + Client Id + Client Secret gegen ein Refresh- & Access-Token Paar ausgetauscht werden. Hierzu öffnen wir Postman und öffnen einen neuen Request.

In diesem Request wählen wir die Methode "POST" und setzen die URL auf die folgende URL.

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

Jetzt öffnen wir den Tab "Body" und wählen "x-www-form-urlencode" aus.

Danach tragen wir diverse Werte ein.

Als "client_id" tragen wir unsere zu beginn erzeugte Client Id ein.

Bei "scope" tragen wir die Dienste ein welche wir nutzen möchten, in diesem Beispiel Bing-Ads.

"code" ist der Auth Code den wir aus der URL entnommen haben und "redirect_url" unsere Redirect-Url.

"grant_type" ist "authorization_code". Dieser Wert sagt dem OAuth-Server das wir einen Auth Code gegen Access- und Refresh-Token tauschen möchten.

"client_secret" ist unser Client-Secret den wir beim erzeugen des Client erhalten haben.

Nachdem wir die Anfrage abgesendet haben, bekommen wir 3 Token. "access_token", "refresh_token" und "id_token". Uns interessieren ausschließlich der Access- und Refresh-Token. Diese kopieren wir uns, um damit gleich den OAuth Account im Control-Panel anzulegen.

Microsoft OAuth im matelso Control Panel

 
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. Als nächstes befüllen wir die Felder für Access- und Re fresh-Token mit unseren erzeugten Tokens.

Die URL setzen wir auf folgenden Wert:

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

Nachfolgend tragen wir noch ein paar Post-Body Werte ein:

Als "client_id" tragen wir unsere zu Beginn erzeugte Client Id ein.

Bei "scope" tragen wir die Dienste ein, welche wir nutzen möchten. In diesem Beispiel Bing-Ads.

"grant_type" ist "refresh_token". Dieser Wert sagt dem OAuth-Server das wir einen Refresh-Token benutzen, um einen neuen Access-Token zu erhalten.

"client_secret" ist unser Client-Secret, den wir beim erzeugen des Client erhalten haben.

"refresh_token" befüllen wir mit unserem Refresh-Token.

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.