OAuth 2
In vielen Fällen erfordern externe Schnittstellen die Authentifizierung per OAuth 2. OAuth 2 unterstützt verschiedene Formen der Authentifizierung, die am häufigsten genutzte Form ist der sog. Authorization Code Grant.
Hierbei wird der Anwender von System A, welches Daten anfordert, zu System B weitergeleitet, wo die Daten liegen. Anschließend muss der Anwender zustimmen, dass System A auf die Daten von System B zugreifen darf.
Anschließend wird der Anwender zurück zu System A geleitet. Wenn der Anwender dem Datenzugriff zugestimmt hat, bekommt System A bei der Weiterleitung einen URL-Parameter, welcher einen Abruf Code beinhaltet. Dieser Code kann nun von System A über einen sicheren Kanal bei System B gegen ein Zugriffstoken austauschen.
Das ganze klingt erst einmal unkompliziert jedoch, gibt es diverse Sicherheitsmechanismen, welche die Implementierung in einer Umgebung wie SodaSync verkomplizieren. Ein Sicherheitsmechanismus ist Beispielsweise, dass in System B die Weiterleitung-URL zu System A kennen muss und nur dahin zurückleiten darf. Da du als Entwickler einer App die URLs von SodaSync nicht beeinflussen kannst, gibt es eine Abstraktion hierfür.
In der Regel wird der Zugriff auf das externe System mit Client Id und Client Secret gesichert.
Client Id und Client Secret sollten nicht im Code deiner App abgelegt werden. Verwende besser App Secrets, um diese sicher zu verwahren.
Weiterleitungs-URL (Redirect URL)
Die Redirect URL folgt dem folgenden Format:
https://app.soda-sync.com/callback/oauth/{packageId}
Lautet die Package Id deiner App com.example.cool_app, wäre die Redirect URL
https://app.soda-sync.com/callback/oauth/com.example.cool_app
Implementierung
Die Implementierung ist für dich relativ einfach. Innerhalb des AppDetails Datenmodell gibt es ein oauth2Client
Feld. Sobald du dieses Feld mit einer implementierung des OAuth2Client befüllst, weiß SodaSync, dass der Benutzer sich
mit OAuth 2 authentifizieren muss.
Ablauf
generateAuthRequest
Diese Methode wird zuerst aufgerufen. Neben der redirectUrl, welche zeigt, wo bei SodaSync hingeleitet werden muss, gibt es auch einen state Parameter. Dieser dient nach dem Zurückleiteten zur Wiederherstellung des Anwendungsstatus in SodaSync.
Der String, welcher im state Parameter gegeben wird muss unverändert an das externe System gegeben werden und
dieses muss den state zurückliefern da, ansonsten nicht erkannt werden kann, ob der Anwender eine bereits bestehende
Integration erneut authentifiziert oder, ob er eine neue Integration hinzufügt. Siehe auch RFC 6749 4.1.2.
Die Methode muss ein AuthRequest-Objekt zurückgeben, welches folgende Felder enthält:
- authUrl: Die URL, zu welcher der Benutzer geleitet werden muss, inkl. der redirectURL.
- state: hierbei handelt es sich um Key-Value-Objekt, welches von dir genutzt werden kann, um Informationen im State abzulegen
Einige Schnittstellen erfordern die Sicherung des Authorization Code Grant durch die OAuth 2 PKCE Erweiterung. Auch diese kannst du implementieren, indem du einfach die nötigen Informationen, welche du zur Verifizierung benötigst, im State ablegst. Die "echten" Daten des State liegen ausschließlich bei SodaSync, an das externe System wird nur ein randomisierter Schlüssel als State übertragen, welcher bei SodaSync zum Laden der Daten verwendet wird.
exchangeGrant
Die exchangeGrant Methode wird dazu verwendet, um den erhaltenen Code gegen ein Zugriffstoken einzutauschen.
Hierfür erhältst du HttpRequest Objekt, welches alle nötigen Daten (URL + Parameter) beinhaltet sowie zusätzlich den
kompletten state als Objekt.
Diese Methode liefert keine Rückgabe, das erhaltene AccessToken kannst du mit
SodaSync.context.config.set in der Konfiguration der Integration speichern.
Zugriffstoken sollten niemals an den Browser weitergegeben werden. Um dies zu erreichen, musst du für das
Konfigurationsfeld, in welchem du das Zugriffstoken speicherst, die isSecret Eigenschaft auf true setzen.
Zusätzlich dazu solltest du den type auf hidden setzen, damit das Feld auch nicht dem Benutzer angezeigt wird.