Die Plattformübergreifende Datennutzung von Websites, Apps oder anderen Online-Diensten ist heute weit verbreiteter Standard und wird über verschiedene APIs (Schnittstellen) realisiert. Um die Daten vor unbefugten Zugriffen zu schützen, werden für den Datenaustausch Autorisierungs-Protokolle verwendet, wie OAuth 2.0.
Auch unsere DRACOON-API-Endprodukte erfordern vor der Nutzung eine solche Authentifizierung. Hier erfahren Sie, ob auf OAuth 2.0 umsteigen sollten und wie die Migration funktioniert. Doch beginnen wir von vorne.
Derzeit gibt es zwei Möglichkeiten, einen Benutzer zu authentifizieren und einen Client zu autorisieren:
- OAuth 2.0 (offener Standard)
- X-SDS-Auth-Token (proprietär)
Der X-SDS-Auth-Token als Möglichkeit zur Authentifizierung von API-Requests wurde mit dem Server-Release 4.13 als deprecated markiert (und ebenso die entsprechenden API-Endpunkte /auth/login und /user/account/logout). Die Unterstützung für den X-SDS-Auth-Token endet am 30. September 2020.
Falls Ihr Unternehmen derzeit den X-SDS-Auth-Token in eigenen Anwendungen oder Skripten verwendet, die von Ihnen oder Ihren Partnern entwickelt wurden, empfehlen wir Ihnen dringend, jetzt auf OAuth 2.0. zu wechseln. So stellen Sie sicher, dass Ihre Anwendungen weiterhin voll funktionsfähig bleiben.
💡 Für DRACOON-Nutzer gilt zu beachten, dass diese Änderung nur selbst entwickelte Anwendungen betreffen; alle offiziellen DRACOON-Anwendungen sind bereits OAuth-basiert, weshalb hierfür keine Änderungen erforderlich sind.
Hintergrund von OAuth 2.0 und OAuth flow
2014 wurde der X-SDS-Auth-Token als einfache und bequeme Möglichkeit eingeführt, als Benutzer authentifizierte API-Requests zu machen. Seitdem haben viele unserer Kunden Anwendungen und Integrationen auf der Basis von DRACOON entwickelt. Um unsere Kunden bei ihren Integrationsbemühungen besser zu unterstützen, unterstützt DRACOON seit 2016 auch OAuth 2.0.
Was ist OAuth 2.0?
OAuth 2.0 ist ein offener Standard und ein weit verbreitetes Autorisierungsprotokoll, das eine sichere API-Autorisierung ermöglicht. Eine der Haupteigenschaften von OAuth 2.0 ist die Unterstützung von zwei verschiedenen Autorisierungsflüssen:
- Three-legged OAuth flow
- Two-legged OAuth flow
Three-legged Oauth flow
Der three-legged OAuth flow ermöglicht es einem Ressourcenbesitzer, einem Client (bspw. einer selbst entwickelten Anwendung) Zugriff auf die Ressource zu gewähren, ohne die Anmeldeinformationen and den Client weiterzugeben. Dieser interaktive three-legged OAuth flow ist besonders wichtig für Anwendungen von Drittanbietern, bei denen Benutzer ihre Anmeldeinformationen nicht mit dieser Anwendung teilen möchten.
Die Benutzer werden dazu auf eine vertrauenswürdige Authentifizierungsschnittstelle (typischerweise eine Webseite) umgeleitet und die Anwendung erhält lediglich einen Authentifizierungs-Token, mit dem die API genutzt werden kann (dies gilt für die grant types Authorization Code und Implicit).
Two-legged Oauth flow
Der two-legged OAuth flow ist hauptsächlich für nicht-interaktive Fälle gedacht, in denen es das Konzept eines interagierenden Benutzers nicht gibt, beispielsweise bei Skripten (gilt für den grant type Password).
💡 DRACOON unterstützt sowohl den three-legged als auch den two-legged OAuth flow. Bitte beachten Sie, dass für den two-legged OAuth flow die Authentifizierung nur mit einem lokalen Konto (Anmeldung mit Benutzername/Kennwort), Active Directory und nicht-interaktivem RADIUS möglich ist. Weder interaktives RADIUS noch OpenID Connect können mit dem two-legged OAuth flow genutzt werden, da diese Authentifizierungsmethoden eine Benutzerinteraktion erfordern und der two-legged OAuth flow ein nicht-interaktiver Flow ist. Für den three-legged OAuth flow stehen alle Authentifizierungsmethoden zur Verfügung.
Migration von X-SDS-Auth-Token zu OAuth 2.0
Mit den folgenden Schritten können Sie prüfen, ob Sie Ihre selbst entwickelte Anwendung oder Integration aktualisieren müssen.
Stellen Sie zunächst fest, ob Ihre Anwendung den X-SDS-Auth-Token verwendet. Hierzu überprüfen Sie, ob Sie in Ihrer Anwendung den API-Endpunkt /auth/login aufrufen, um Benutzer zu authentifizieren. Ist dies der Fall, dann verwenden Sie den X-SDS-Auth-Token.
Übersicht zur Wahl des passenden OAuth-Flow für Ihre Integration:
| |
Interaktiv |
Nicht-interaktiv |
| Sicherer lokaler Speicher für OAuth-Anmelde-Informationen verfügbar (wie z.B. Desktop- oder mobile Anwendungen) |
Three-legged OAuth:
Authorization Code Flow |
Two-legged OAuth:
Password Flow |
| Kein sicherer lokaler Speicher verfügbar (z.B. client-seitige Web-Anwendungen) |
Three-legged OAuth:
Implicit Flow |
- |
Um OAuth für eigene Anwendungen oder Skripte zu verwenden, müssen Sie zunächst eine neue OAuth-Anwendung wie folgt registrieren:
- Öffnen Sie den Browser und loggen Sie sich in Ihr DRACOON-Konto ein (Für die folgenden Schritte ist die Rolle Config Manager erforderlich).
- Gehen Sie zu Systemeinstellungen → Apps.
- Klicken Sie auf die Schaltfläche Hinzufügen, um eine neue OAuth-App anzulegen. Für den two-legged OAuth flow muss mindestens der grant type password ausgewählt werden. Für den three-legged OAuth flow muss entweder der grant type implicit oder authorization code ausgewählt werden.
- Klicken Sie auf Speichern und notieren Sie Client ID und Client Secret für die angelegte OAuth-App.
Wenn Sie eine OAuth-App automatisiert registrieren möchten, finden Sie hier weitere Informationen: https://support.dracoon.com/hc/de/articles/115003832605
Im Folgenden zeigen wir Ihnen einige Beispiele, wie Sie die neue OAuth-App zur Authentifizierung mit DRACOON verwenden können.
OAuth flow Beispiele
Three-legged OAuth flow
Eine detaillierte Anleitung für den three-legged OAuth flow mit DRACOON finden Sie hier: https://support.dracoon.com/hc/de/articles/360001329825-OAuth-2-0-Example
Darüber hinaus finden Sie in unserem Java-SDK auch ein detailliertes Beispiel für den three-legged OAuth flow mit dem grant type authorization code: https://github.com/dracoon/dracoon-java-sdk/blob/master/example/src/main/java/com/dracoon/sdk/example/OAuthExamples.java
Two-legged OAuth flow
Im Folgenden zeigen wir Ihnen, wie man sich mit dem two-legged OAuth flow anmeldet und den access token verwendet, um API-Endpunkte aufzurufen, die eine Authentifizierung erfordern. Der two-legged OAuth flow ist vermutlich die beste Option, um einfache Skripte zu authentifizieren.
cURL
PowerShell
Auth Request, um einen Access Token zu erhalten
$Uri = "https://[DRACOON_HOSTNAME]/oauth/token"
$Username = "[USER_NAME]"
$Password = "[PASSWORD]"
$ClientId = "[CLIENT_ID]"
$ClientSecret = "[CLIENT_SECRET]"
$Base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $ClientId,$ClientSecret)))
$Body = @{ "grant_type" = "password"; "username" = $Username; "password" = $Password }
$Response = Invoke-WebRequest -URI $Uri -Method Post -ContentType "application/x-www-form-urlencoded" -Body $Body -Headers @{Authorization=("Basic {0}" -f $Base64AuthInfo)}
$Content = ConvertFrom-Json $Response.content
$Token = $Content.access_token
Write-Output $Token
Verwendung des Access Tokens, um Account-Informationen abzurufen
$Uri = "https://[DRACOON_HOSTNAME]/api/v4/user/account"
$Token = "[ACCESS_TOKEN]"
$Response = Invoke-WebRequest -URI $Uri -Method Get -ContentType "application/json" -Headers @{Authorization=("Bearer {0}" -f $Token)}
$Content = ConvertFrom-Json $Response.content
Write-Output $Content
Java (Using OkHttp Library)
Auth Request, um einen Access Token zu erhalten
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "grant_type=password&username=[USER_NAME]&password=[PASSWORD]");
Request request = new Request.Builder()
.url("https://[DRACOON_HOSTNAME]/oauth/token")
.post(body)
.addHeader("Content-Type", "application/x-www-form-urlencoded")
.addHeader("Authorization", "Basic [Base64([CLIENT_ID]:[CLIENT_SECRET])]")
.build();
Response response = client.newCall(request).execute();
Verwendung des Access Tokens, um Account-Informationen abzurufen
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://[DRACOON_HOSTNAME]/api/v4/user/account")
.get()
.addHeader("Authorization", "Bearer [ACCESS_TOKEN]")
.build();
Response response = client.newCall(request).execute();
Benötigen Sie weitere Hilfe?
OAuth 2.0 ist ein weit verbreitetes offenes Standardprotokoll, und Software-Bibliotheken für OAuth sind für fast alle Programmiersprachen verfügbar. Indem wir OAuth zum einzigen Authentifizierungs- und Autorisierungsframework machen, profitieren unsere Entwickler und Integratoren in hohem Maße von einem weit verbreiteten Standard.
Falls Sie Anwendungen oder Skripte nutzen, die noch den X-SDS-Auth-Token verwenden, finden Sie am Ende weitere Informationsquellen zu OAuth 2.0. Zusätzlich erhalten Sie in unserer Community weitere Hilfe.
Weiterführende Informationen
OAuth 2.0 RFC: https://tools.ietf.org/html/rfc6749
OAuth.net Ressourcen: https://oauth.net/2/
Florian Scheuer
Florian Scheuer : 07.07.20 00:00
