Page tree
Skip to end of metadata
Go to start of metadata



Was ist oAuth2 (open Authorization) und wofür wird es verwendet?

  • oAuth2 ist ein Protokoll, welches dem Nutzer ermöglicht, mehrere (externe) Dienste, die einer Anmeldung bedürfen, mit nur einem DLRG-Account zu nutzen. Das kann z. B. interessant sein, wenn eine Gliederung eine eigene Cloud (nicht die DLRG-Cloud) betreibt und möchte, dass sich die Mitglieder der Gliederung über den DLRG-Account anmelden können. So müssen sich die Mitglieder nicht mehrere Zugangsdaten merken.
    • ein gutes Beispiel für oAuth ist z.B. die Möglichkeit, sich mit seinem Facebook-Account bei Spotify anzumelden. Hier kommt ebenfalls oAuth zum Einsatz
  • Das Anmeldeverfahren mit oAuth2 ist besonders sicher, da u. a. der externe Dienst nicht in den Besitz von Account-Passwörter gelangt und der Nutzer eine Kontrolle darüber hat, welche seiner Daten er für die Weitergabe freigibt.

Einrichtung

  • Die Einrichtung muss vom Betreiber des externen Dienstes, z. B. die Gliederung mit eigener Cloud, selbst vorgenommen werden.
  • Es erfolgt seitens des AK-IT kein Support bei der Einrichtung von oAuth2 auf eigenen Servern!

Wie kann ich oAuth2 beantragen?

Um oAuth2 nutzen zu können, benötigt man eine Client-ID und ein Passwort, manchmal auch Client-Secret genannt. Beides bekommt man vom AK-IT auf Antrag mitgeteilt.

Der Antrag erfolgt formlos über webmaster@dlrg.de und muss zwingend von einer DLRG-Funktionsadresse gestellt werden bzw. für AK-IT nachvollziehbar sein, dass die anfragende Person im Auftrag des Gliederungsvorstands handelt.

In der Mail müssen folgende Angaben enthalten sein:

  • URL des externen oAuth-Clients/Dienstes
    → hier muss die genaue URI angegeben werden, auf die der oAuth-Server von AK-IT seine Antwort auf die Authorisierungsanfrage sendet
  • Bezeichnung des Dienstes (z. B. Cloud, Forum, usw.) für eine interne Zuordnung
  • Zweck des Dienstes, falls nicht ersichtlich

Welche Rechte kann oAuth2 gewähren?

Zum aktuellen Zeitpunkt kann über oAuth2 folgende Rechte gewährt werden:

  • profile: das Recht, Benutzername, Vor- und Zuname des Nutzers abfragen zu dürfen
  • email: das Recht, die E-Mail-Adresse des Nutzers abfragen zu dürfen

Weitere Rechte werden zukünftig folgen.

Wie funktioniert oAuth2?

Die Funktion von oAuth2 erklären wir am Beispiel einer Gliederung, OG Musterstadt, die eine eigene Cloud betreibt.

Der Webmaster der OG Musterstadt hat auf seinem Cloud-Server den oAuth2-Client mit der beantragten Client-ID und dem Client-Passwort eingerichtet, so dass sich Mitglieder mit ihrem DLRG-Account in der Cloud der OG Musterstadt anmelden können.

Die Mitglieder rufen die Internetseite der Cloud auf, beispielhaft https://cloud.dlrg-musterstadt.de, und klicken dort als Anmeldemöglichkeit auf „mit DLRG-Account anmelden“.
Nun werden sie automatisch auf die Anmeldeseite des offiziellen DLRG-Servers geleitet auf dem der oAuth2-Server läuft. Über die im für die Weiterleitung zuständigen Link enthaltenen Daten (kryptische Zahlen- und Buchstabenfolgen) wird dem oAuth2-Server mitgeteilt, dass sich jemand mit seinem DLRG-Account in der Cloud der OG-Musterstadt anmelden möchte, welche Rechte die Cloud sich geben lassen möchte und auf welche Internetseite der Benutzer nach erfolgter Anmeldung zurückgeleitet werden soll.
Nach erfolgter Eingabe des Anmeldenamens und -passworts wird dem Mitglied in einer weiteren Abfrage aufgezeigt, welche Daten die Cloud übermittelt bekommen möchte. In diesem Fall den Benutzernamen, Vor- und Zunamen sowie die E-Mail-Adresse. Dies muss das Mitglied bestätigen und wird auf die Seite der Cloud zurück geleitet, auf der es nun angemeldet ist.

Das passiert für den Anwender nicht sichtbar im Hintergrund

Nachdem das Mitglied erlaubt hat, dass die geforderten Daten dem Drittanbieter, hier die Cloud der OG Musterstadt, preisgegeben werden dürfen, sendet der oAuth2-Server der DLRG eine Code an den oAuth2-Client auf dem Cloud-Server der OG Musterstadt.
Der oAuth2-Client der Cloud sendet nun eine erneute Abfrage an den oAuth-Server mit diesem Code, der spezifischen Client-ID sowie dem Client-Passwort um sich zu legitimieren. Diese Daten werden dabei nicht wie die der ersten Abfrage über den Browser, sondern im Hintergrund über eine gesicherte Verbindung übermittelt und ist für Angreifer nicht abfangbar und somit sicher vor Fremdzugriffen.
Nach erfolgter Legitimierung generiert der o2Auth-Server einen sogenannten Token, der ähnlich einem Cookie Informationen enthält und nur für einen bestimmten Zeitraum (in unserem Fall 1 Stunde) gültig ist.
Dieser Token wird an den oAuth2-Client der Cloud zurückgesendet, welcher diesen kurz verarbeitet und als letzten Legitimationsnachweis erneut an den oAuth2-Server zurücksendet.
Der oAuth2-Server weiß nun endgültig, dass die Cloud sie selbst ist und die Daten des Mitgliedes erhalten darf und erlaubt dem oAuth2-Client der Cloud den Zugriff auf die geforderten Daten (Benutzername, Vor- und Zuname und E-Mail-Adresse).

Vereinfacht erklärt


Vereinfacht gesprochen geht der oAuth2-Client der Cloud (im Weiteren Antragsteller genannt) zum oAuth2-Server der DLRG (im Weiteren Amt A und Amt B genannt) und stellt den Antrag auf Herausgabe von persönlichen Daten eines Mitmenschen.
Das Amt A prüft nun, ob der Antragsteller auch der ist, der er zu sein vorgibt und ob er einen berechtigten Anspruch auf die geforderten Daten hat sowie, ob die betroffene Person der Herausgabe der Daten eingewilligt hat.
Ist diese Prüfung positiv, stellt Amt A dem Antragsteller einen Erlaubnisschein (Token) aus, mit dem er zu Amt B gehen kann, welches die persönlichen Daten verwaltet.
Anhand des Erlaubnisscheins weiß das Amt B, dass der Antragsteller berechtigt ist, die gewünschten Daten zu erhalten und erteilt dem Antragsteller letztlich eine Auskunft.


Das Benutzerpasswort wurde bei dem gesamten Vorgang lediglich einmal bei der Anmeldung auf dem DLRG-Server eingegeben und nicht bei dem Drittanbieter. So hat der Drittanbieter keine Möglichkeit über seine Datenbank oder andere Wege das Benutzerpasswort des DLRG-Accounts auszulesen und dieses böswillig zu nutzen.

Fazit

Dem Endanwender macht oAuth2 das Leben deutlich einfacher, da man sich nicht mehr diverse Anmeldenamen und -passwörter für alle möglichen Dienste merken muss.
Einem potenziellen Angreifer wird es durch das Hin- und Herschicken von kryptischen Zeichen und das ständige Rückversichern (ähnlich Asterix und Obelix beim römischen Amt) sehr schwer bis quasi unmöglich gemacht die Anmeldedaten des Benutzers/Mitgliedes abzufangen und böswillig zu nutzen.

Technische Erklärung


Für externe Dienste schalten wir nur den "Authorization Grant" als Berechtigungsmethode frei. Daher beschränkt sich die Anleitung auf diesen "Grant-Type"

Erste Anfrage:

GET https://dlrg.net/oauth2/authorize

mit den Parametern:


  • response_type=code
  • client_id={vom AK IT erhaltene Client-ID}
  • redirect_uri={URL des eigenen Dienstes}
  • scope={eine Liste der Berechtigungen, die für den Dienst vom Nutzer erbeten werden}properties
  • state={ein CSRF-Token} (optional)


Wenn der Benutzer sich einloggt und die Anfrage bestätigt, erfolgt eine Weiterleitung auf die URl des eigenen Dienstes mit den Parametern:

  • code={der Autorisierungscode}
  • state={das CSRF-Token der vorherigen Anfrage}


Nach dem Login und Bestätigung der Rechtegewährung muss der eigene Dienst folgende Abfrage durchführen:
POST https://dlrg.net/oauth2/token

mit den Parametern:

  • grant_type=authorization_code
  • client_id={vom AK IT erhaltene Client-ID}
  • client_secret={vom AK IT erhaltenes Client-Passwort}
  • redirect_uri={URL des eigenen Dienstes}
  • code={der Autorisierungscode}


Es wird als Antwort ein JSON-Objekt gesendet mit folgenden Eigenschaften:

  • token_type: Bearer
  • expires_in: 3600
  • access_token: {das Token, welches u.a. die Benutzer-ID und die erhaltenen Rechte [Scopes] beinhaltet)
  • refresh_token: {ein "Auffrischungstoken", mit dem ein neues Token generiert werden kann, sollte dieses ungültig geworden sein}


Derzeit sind folgende Rechte vom Nutzer beantragbar:

  • profile : das Recht, den Benutzername, Vorname und Nachname des Nutzers abfragen zu dürfen
  • email : das Recht, die Email-Adresse des Nutzers abfragen zu dürfen


Diese Informationen sind abzufragen unter:
GET https://dlrg.net/oauth2/userinfo
mit dem "Authorization"-Header vom Typ "Bearer" und dem erhaltenen Token

Folgende Werte sind in der Antwort (JSON) bei vorhandener Berechtigung abrufbar:

{
    "sub": "80ca57cb-953d-4120-be07-53425dd5470a", // (Account-Id) immer vorhanden, wenn der Token nicht abgelaufen ist
    "name": "Max Mustermann", // Scope "profile" notwendig
    "given_name": "Max", // Scope "profile" notwendig
    "family_name": "Mustermann", // Scope "profile" notwendig
    "preferred_username": "m.mustermann", // Scope "profile" notwendig
    "email": "webmaster@dlrg.de", // Scope "email" notwendig
    "email_verified": true // Scope "email" notwendig
}