JETZT TESTEN
dracoon-login-w
Menu
JETZT TESTEN
LOGIN
Goodbye X-SDS-Auth-Token, hello OAuth 2.0

Goodbye X-SDS-Auth-Token, hello OAuth 2.0

Florian Scheuer
11.05.20 08:30

Wie die meisten von Ihnen wissen, erfordern nahezu alle DRACOON-API-Endpunkte eine Authentifizierung, bevor Sie diese nutzen können. 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)

Mit diesem Blog-Beitrag möchten wir Sie darüber informieren, dass der X-SDS-Auth-Token als Möglichkeit zur Authentifizierung von API-Requests mit dem Server-Release 4.13 als deprecated markiert wurde (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, um sicherzustellen, dass Ihre Anwendungen voll funktionsfähig bleiben.

Beachten Sie, dass diese Änderung nur selbstentwickelte Anwendungen betrifft; alle offiziellen DRACOON-Anwendungen sind bereits OAuth-basiert, und es sind hierfür keine Änderungen erforderlich.

 

Zum Hintergrund

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.

OAuth 2.0 ist ein offener Standard und ein weit verbreitetes Autorisierungsprotokoll. Eine der Haupteigenschaften von OAuth 2.0 ist die Unterstützung von zwei verschiedenen Autorisierungsflüssen:

  • Three-legged OAuth flow
  • Two-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).

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 selbstentwickelte 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. Die folgende Tabelle hilft Ihnen dabei, den passenden OAuth-Flow für Ihre Integration zu wählen:

  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:

  1. Öffnen Sie den Browser und loggen Sie sich in Ihr DRACOON-Konto ein (Für die folgenden Schritte ist die Rolle Config Manager erforderlich).
  2. Gehen Sie zu Systemeinstellungen → Apps.
  3. 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.
  4. 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.

 

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

Auth Request, um einen Access Token zu erhalten

curl -X POST \
  https://[DRACOON_HOSTNAME]/oauth/token \
  -H 'Authorization: Basic [BASE64_ENCODED [CLIENT_ID]:[CLIENT_SECRET]]' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&username=[USER_NAME]&password=[PASSWORD]'

 

Verwendung des Access Tokens, um Account-Informationen abzurufen

curl -X GET \
  https://[DRACOON_HOSTNAME]/api/v4/user/account \
  -H 'Authorization: Bearer [ACCESS_TOKEN]'
 
 

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/

dracoon-devices-free

Jetzt DRACOON testen

10 User – 10 GB für immer kostenlos

DRACOON testen

Bei neuen Blog-Artikeln benachrichtigen lassen: