Dieser Artikel erklärt, wie man ein Microsoft OAuth-Konto im matelso Control Panel konfiguriert. #

Was ist OAuth? #

OAuth ist ein Autorisierungsstandard mit großer Akzeptanz auf dem Markt. Google und Microsoft sind nur zwei Beispiele für Unternehmen, die ihre Dienste mit OAuth schützen.

Es gibt eine Reihe von Erweiterungen zu OAuth, aber innerhalb des matelso-Systems unterstützen wir nur den Refresh-Token-Flow. RFC6749 Auffrischungs-Tokens

Dieser Teil der Spezifikation wird häufig im Server-Server-Kontext verwendet und ist daher die Art und Weise, wie wir dieses Konto einrichten.

TLDR: OAuth Refresh Token Fluss #

Ein Refresh Token ist eine spezielle Zeichenfolge, die von einer Anwendung (Client) verwendet werden kann, um ein Zugriffstoken über einen Autorisierungsserver zu erhalten. Dieses Zugriffs-Token kann dann verwendet werden, um auf geschützte Ressourcen zuzugreifen oder Aktionen auf Ressourcen durchzuführen, z.B. das Senden einer E-Mail über Outlook oder das Senden von Daten an Bing-Ads.

Client erstellen #

Um auf Ressourcen hinter OAuth zugreifen zu können, muss die Anwendung zunächst registriert werden. Eine Anwendung in OAuth wird als Client bezeichnet. In unserem Beispiel richten wir einen Client über das Azure-Portal ein. Azure-Portal – App-Registrierungen. Sobald wir das Portal über den obigen Link öffnen, öffnet sich der Dialog zur Registrierung einer Anwendung.

Falls dies nicht automatisch geschieht, klicken wir auf den folgenden Button:

Im Registrierungsdialog geben wir einen Namen, die unterstützten Kontotypen und Weiterleitungs-URIs ein.
Name: Hier vergeben wir einen Namen, der einem Benutzer der Anwendung angezeigt wird. In unserem Beispiel setzen wir den Namen auf „Matelso Integration Demo“.

Typ der unterstützten Konten: Diese Eingabe gibt an, welche Arten von Microsoft-Konten sich bei unserer Anwendung anmelden können. Um es einfach zu machen und nicht jede Unterart von Konten zu erklären, wählen wir einfach „Konten in jedem Organisationsverzeichnis (jedes Azure AD Directory – mandantenfähig) und persönliche Microsoft-Konten (z.B. Skype, XBox)“.

Redirect URIs: Die Redirect-URI ist die URI, zu der wir nach erfolgreicher Anmeldung weitergeleitet werden. In diesem Beispiel werde ich meine Demoseite verwenden.

Nachdem wir auf die Schaltfläche „Registrieren“ geklickt haben, werden wir auf die Detailseite unserer Anwendung weitergeleitet. Auf dieser Detailseite finden wir einige wichtige Informationen.

Kundennummer und Kundengeheimnis #

Für die nächsten Schritte benötigen wir die Kundennummer und das Kundengeheimnis für unsere neu erstellte Anwendung. Auf der Detailseite finden wir die Kundennummer.

Außerdem müssen wir ein neues Client Secret erstellen. Um ein neues Geheimnis zu erstellen, klicken wir auf den Link auf der Detailseite:

Nachdem wir auf diesen Link geklickt haben, werden wir zu „Zertifikate & Geheimnisse“ weitergeleitet. Auf dieser Seite klicken wir auf „Neues Kundengeheimnis“.

Nachdem wir auf diese Schaltfläche geklickt haben, wird auf der rechten Seite des Bildschirms ein Dialog angezeigt.

In diesem Dialogfeld geben wir unsere Beschreibung für das Geheimnis ein und wählen die Lebensdauer des Geheimnisses. In diesem Beispiel wähle ich 24 Monate. Wir klicken auf die Schaltfläche „Hinzufügen“ und kopieren unser neu erstelltes Geheimnis.

Geltungsbereiche #

Nachdem wir das Geheimnis erstellt haben, müssen wir Dienste hinzufügen, auf die die Anwendung zugreifen kann (Bereiche). Um einen neuen Dienst hinzuzufügen, navigieren wir zu „API-Berechtigungen“ und klicken auf die Schaltfläche „Eine Berechtigung hinzufügen“.

Es erscheint ein neuer Dialog auf der rechten Seite. Für dieses Beispiel navigieren wir zu „Microsoft Graph“ -> „delegierte Berechtigungen“ und suchen nach „mail.send“. In den gefilterten Ergebnissen wählen wir die Berechtigung „Mail.Send“ aus und klicken auf „Add permissions“.

Refresh- & Access-Token generieren #

Um ein Refresh- & Access-Token zu erhalten, müssen wir uns mit unserem Microsoft-Konto bei unserer Anwendung anmelden. Dazu erstellen wir 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 gibt es 3 Platzhalter. Wir müssen diese Platzhalter noch ausfüllen. Bevor wir die Werte in die Platzhalter eingeben, müssen sie URI-kodiert werden. Das bedeutet, dass bestimmte Sonderzeichen ersetzt werden müssen.
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 alle angeforderten Genehmigungen, indem wir einfach auf „Ja“ klicken, und werden zu unserer Redirect-uri umgeleitet. Es ist wichtig zu beachten, dass die URL, zu der wir umgeleitet werden, zusätzliche Werte enthält (Code und Status). Der Parameter state enthält denselben Status wie unsere Login-URL und kann ignoriert werden. Der code-Parameter enthält unseren Autorisierungscode, den wir gegen ein access-&refesh-token-Paar austauschen können.

Sobald wir diese URL geöffnet haben, öffnet sich die Anmeldeseite von Microsoft. Hier kann in OAuth dieser Code (Auth Code) + Client Id + Client Secret gegen ein Refresh & Access Token Paar ausgetauscht werden. Dazu öffnen wir Postman und öffnen eine neue Anfrage. Wir melden uns mit unserem Microsoft-Konto an. Nach dem Einloggen sehen wir, welche Berechtigungen die Anwendung von uns als Benutzer verlangt (Consent Screen).

In dieser Anfrage wählen wir die Methode „POST“ und setzen die URL auf die folgende URL.

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

Nun öffnen wir die Registerkarte „Body“ und wählen „x-www-form-urlencode“.

Dann geben wir verschiedene Werte ein.

Als „client_id“ geben wir unsere Kundennummer ein.

Für „scope“ geben wir wieder unsere angeforderten Dienste und Berechtigungen ein.

„code“ muss mit unserem Auth-Code aus der Redirect-Url gefüllt werden.

Als „grant_type“ verwenden wir „authorization_code“. Dies teilt dem Token-Endpunkt mit, dass wir unseren Autorisierungscode gegen ein Access- und Refresh-Token-Paar unter Verwendung des Code-Flows austauschen wollen.

„client_secret“ muss auf das von uns erstellte Client-Geheimnis gesetzt werden.

Jetzt klicken wir auf „Senden“ und sehen, dass die Antwort 3 Token enthält. „access_token“, „refresh_token“ und „id_token“. Wir interessieren uns nur für access und refresh. Wir kopieren diese Token und loggen uns in das Matelso Control Panel ein.

Microsoft OAuth im matelso-Kontrollzentrum #

Um einen OAuth-Account im matelso Control Panel hinzuzufügen, navigieren wir zu „Configuration“->“Integrations 2.0″ und öffnen den Reiter Accounts.

Auf dieser Seite klicken wir auf die Schaltfläche „+“ und wählen im Dropdown-Menü „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:

„scope“, „client_id“ und „client_secret“ werden auf die gleiche Weise wie in unserer Postman-Anfrage gefüllt.

Der „grant_type“ wird dieses Mal „refresh_token“ sein. Dies teilt dem Token-Endpunkt mit, dass wir unser Refresh-Token verwenden wollen, um ein neues Access-Token zu erhalten.

Und zu guter Letzt setzen wir das Feld „refresh_token“ auf unser Refresh-Token.

Nachdem wir auf „Speichern“ geklickt haben, können wir das Zugriffstoken in Push-Konfigurationen über den DDD-Browser verwenden.