Was ist OAuth2?

OAuth 2.0, die Abkürzung für "Open Authorization", ist ein Zugriffs-Standard, der es einer Website oder Anwendung ermöglicht, im Namen eines Nutzers auf Ressourcen zuzugreifen, die von anderen Webanwendungen gehostet werden. Er löste 2012 OAuth 1.0 ab und ist nun der De-facto-Branchenstandard für die Online-Autorisierung. Auf eine detaillierte Beschreibung des OAuth-Prozesses verzichten wir an dieser Stelle. Mehr Informationen dazu finden Sie auf der offiziellen Seite: https://oauth.net.

Hier gilt folgender Ablauf: Ist in einem Profil der entsprechende Kanal mit aktiver OAuth-Konfiguration hinterlegt, wird vor dem Start des Cronjobs die Gültigkeit des Tokens im Kanal überprüft und dieser gegebenenfalls automatisiert erneuert.

Vor der Ersteinrichtung

Bevor Sie mit der Einrichtung beginnen, prüfen Sie bitte folgende Punkte:

• Handelt es sich um eine offizielle OAuth2-Anbindung? Einige Webservices und APIs sprechen zwar von OAuth, halten sich aber nicht an den offiziellen Standard (RFC). Weicht beispielsweise die Response vom Standard ab, kann diese nicht interpretiert und der Token nicht extrahiert werden. Sehen Sie sich für diesen Fall den Abschnitt Generic Bearer Token verwenden unten an.

• Ist der Endpunkt erreichbar oder müssen gegebenenfalls Firewalls/Ports freigeschaltet werden?

• Liegen alle benötigten Anmelde-Credentials vor?

Wo finde ich die OAuth2-Konfiguration?

Hierfür wechseln Sie in die Kanalübersicht (Verwaltung → Partner → Kanäle) und legen einen neuen HTTP(S)-Kanal an. Dort lassen sich neben einfachen Authentifizierungsmethoden wie Basic/Digest auch OAuth einrichten und testen.

Im Tab Eigener Zugang finden Sie den OAuth-Abschnitt.

Wie konfiguriere ich OAuth2? (Quickstart/Wizard)

1. Um einen ersten Verbindungstest durchzuführen, klicken Sie auf den Button OAuth2.0 konfigurieren.

2. Wählen Sie den benötigten Grant Type aus.

3. Geben Sie alle notwendigen Credentials ein (Client ID, Client Secret, etc).

4. Tragen Sie die Endpoint URL ein. Diese finden Sie in Ihrer Anwendung oder der Dokumentation zur API.

   1. Bei Grant Type Authorization Code muss zusätzlich die (O)Auth URL hinterlegt werden. Diese endet meist mit ... /authorize
      Außerdem wird eine Callback URL / Redirect URL benötig, diese wird automatisch ge füllt .

5. Klicken Sie auf Access Token holen, um einen Access Token zu erhalten.

   1. Bei Grant Type Authorization Code erfolgt eine zusätzliche Anmeldung/Autorisierung per Browser.

Schließt sich das Fenster automatisch, konnte der Token erfolgreich abgeholt werden! Öffnen Sie den Kanal erneut, sollte das Ablaufdatum des Tokens zu sehen sein:

Konnte kein Token in der Response gefunden werden, erscheint ein Pop-up-Fenster mit Errorlog. Je nach OAuth-Implementierung des Webservices, können diese sehr aussagekräftig sein.

Bei Problemen bitte die Fehlermeldung im Log ansehen, alternativ an unseren Support wenden.

Automatische Token-Erneuerung

Wurde der Token erfolgreich über OAuth2.0 konfigurieren... abgeholt, kann dieser automatisiert erneuert werden.

Dazu muss das Feld OAuth2 Refresh URL im Kanal angepasst bzw. zusammengestellt werden. Die Refresh URL muss alle Infos aus dem Wizard enthalten! Über den kleinen Button % lassen sich die folgenden Vorlagen einfügen.

Zusatzparameter, je nachdem, ob die Checkboxen im Wizard gesetzt wurden:

Hinweis: Ab Version 4.6.11 wird die OAuth2 Refresh URL automatisch generiert!

Wichtig: Der Endpoint https://<server>/oauth/token, also alles bis zum "?", muss manuell angepasst werden. Dieser entspricht der Endpoint URL im Wizard. Parameter, wie beispielsweise scope, können sich ebenfalls unterscheiden.

Verbindung mit DMZ: Wird ein DMZ-Server verwendet, muss bei Grant Type Authorization Code die Redirect URL in die Konfigurationsdatei ./etc/forward.properties des DMZ-Servers eingetragen werden! Siehe auch Abschnitt Weiterleitung von HTTP(S)-Anfragen nach innen‌.

Custom OAuth2

Wie zuvor beschrieben, kann es sein, dass keine offizielle Implementierung serverseitig vorliegt, der Server dennoch eine Response inclusive Token und Gültigkeit zurückliefert. Hierfür können Sie die Option Generic Bearer Token verwenden. Diese ist ab Version 4.6.5 verfügbar.