Zugehörige Dokumente
OAuth 2.0 ist als RFC 6749 standardisiert. Ein detailliertes Dokument ist unter https://oauth.net/2 verfügbar. Die HTTP-Basisauthentifizierung ist in Abschnitt 2 von RFC 2617 definiert.
Übersicht
Normalerweise muss der Endnutzer (Ressourceninhaber) seine Anmeldedaten an den Drittanbieter weitergeben, damit Drittanbieteranwendungen auf eingeschränkte Ressourcen wie Datenvolumen und Wallet-Details zugreifen können. Dies führt zu mehreren Problemen und Einschränkungen, z. B. bei der Speicherung von Anmeldedaten, der Passwortauthentifizierung, dem umfassenden Zugriff auf die Ressourcen des Endnutzers und dem Verlust von Passwörtern. OAuth 2.0 behebt diese Probleme durch die Einführung einer Autorisierungsebene und sichert und begrenzt so den Zugriff auf die geschützten Ressourcen des Endnutzers.
Anstatt die Anmeldedaten des Endnutzers für den Zugriff auf geschützte Ressourcen wie Details zum Datentarif zu verwenden, ruft das GTAF ein Zugriffstoken ab. Die Zugriffstokens werden für GTAF im Namen der Anmeldedaten von GTAF ausgestellt. Das GTAF verwendet dann das Zugriffstoken, um auf die vom DPA gehosteten Datenplan-Details zuzugreifen.
Die folgende Abbildung zeigt den allgemeinen Informationsfluss:
Abbildung 1. Abstrakter OAuth-Ablauf.
Zugriffstokens
Zugriffstokens sind die Anmeldedaten, die vom GTAF verwendet werden, um auf Details zum Datentarif aus der DPA des Mobilfunkanbieters zuzugreifen. Ein Zugriffstoken ist ein String, der eine für die GTAF erteilte Autorisierung darstellt. Der String ist für die GTAF in der Regel nicht transparent. Tokens repräsentieren bestimmte Bereiche und Zeiträume des Zugriffs, die vom Endnutzer dem Mobilfunkanbieter gewährt und von der DPA und dem OAuth-Server des Mobilfunkanbieters erzwungen werden.
Das Zugriffstoken bietet eine Abstraktionsebene und ersetzt verschiedene Autorisierungskonstrukte (z.B. Nutzername und Passwort) durch ein einzelnes Token, das vom DPA verstanden wird. Diese Abstraktion ermöglicht die Ausstellung von Zugriffstokens, die restriktiver sind als die zur Erlangung verwendeten Autorisierungs-Grants. Außerdem muss der DPA nicht eine Vielzahl von Authentifizierungsmethoden verstehen.
Zugriffstokens können je nach Sicherheitsanforderungen des Mobilfunkanbieters unterschiedliche Formate, Strukturen und Nutzungsmethoden (z.B. kryptografische Eigenschaften) haben. GTAF unterstützt nur Zugriffstokens vom Typ „Bearer“, die in [RFC6750] definiert sind.
Clientauthentifizierung
Die GTAF fungiert als „vertraulicher Client“ und kann Passwörter sicher aufbewahren. Das GTAF unterstützt derzeit nur die HTTP-Basisauthentifizierung für die Authentifizierung bei der DPA. Die Client-ID wird mit dem Codierungsalgorithmus „application/x-www-form-urlencoded“ codiert und der codierte Wert wird als Nutzername verwendet. Das Passwort wird mit demselben Algorithmus codiert und als Passwort verwendet.
Vertrauliche Clients wie GTAF, denen Clientanmeldedaten ausgestellt werden, authentifizieren sich beim OAuth-Server des Mobilfunkanbieters, wenn sie Anfragen an den Token-Endpunkt senden. Die Clientauthentifizierung wird für Folgendes verwendet: \
- Wiederherstellung nach einem kompromittierten Client durch Deaktivieren des Clients oder Ändern seiner Anmeldedaten, um zu verhindern, dass ein Angreifer gestohlene Aktualisierungstokens missbraucht. Das Ändern eines einzelnen Satzes von Clientanmeldedaten ist wesentlich schneller als das Widerrufen eines gesamten Satzes von Aktualisierungstokens.
- Implementierung von Best Practices für die Authentifizierungsverwaltung, die eine regelmäßige Rotation von Anmeldedaten erfordern.
Das GTAF verwendet den Anfrageparameter „client_id“, um sich beim Senden von Anfragen an den Token-Endpunkt zu identifizieren.
Besonders wichtig ist die Möglichkeit, Clientanmeldedaten zu rotieren. Der OAuth-Server muss während der Rotation zwei gleichzeitige Anmeldedatenpaare unterstützen und Anmeldedaten deaktivieren können. Bei einer typischen Rotation von Anmeldedaten:
- Der Mobilfunkanbieter erstellt neue Anmeldedaten auf dem OAuth-Server und stellt sie seinem Technical Account Manager auf sichere Weise zur Verfügung.
- Google testet die neuen Anmeldedaten und ändert die GTAF-Konfiguration, sodass die neuen Anmeldedaten verwendet werden.
- Google benachrichtigt den Mobilfunkanbieter, dass die alten Anmeldedaten möglicherweise deaktiviert werden.
- Der Mobilfunkanbieter deaktiviert die Anmeldedaten und benachrichtigt Google.
- Google prüft, ob die alten Anmeldedaten nicht mehr funktionieren.
Der OAuth-Server muss den oben genannten Rotationsprozess unterstützen.
Token-Endpunkt
Der Token-Endpunkt wird vom GTAF verwendet, um ein Zugriffstoken abzurufen, indem er sein Autorisierungs-Grant oder Aktualisierungstoken präsentiert. Der Token-Endpunkt wird mit jedem Autorisierungstyp verwendet, mit Ausnahme des impliziten Berechtigungstyps, da ein Zugriffstoken direkt ausgestellt wird.
Beim Konfigurieren eines Token-Endpunkts sind folgende Punkte zu beachten:
- Der Speicherort des Tokenendpunkts sollte in der Dienstdokumentation angegeben werden.
- Die Endpunkt-URI kann eine im Format „application/x-www-form-urlencoded“ formatierte Suchanfragekomponente enthalten, die beim Hinzufügen zusätzlicher Suchparameter beibehalten werden muss. Die Endpunkt-URI darf keine Fragmentkomponente enthalten.
- Da bei Anfragen an den Token-Endpunkt Anmeldedaten im Klartext übertragen werden (in der HTTP-Anfrage und -Antwort), muss der OAuth-Server des Mobilfunkanbieters TLS verwenden, um Anfragen an den Token-Endpunkt zu senden.
- Das GTAF verwendet die HTTP-Methode „POST“, wenn es eine Anfrage für ein Zugriffstoken stellt.
- Parameter, die ohne Wert gesendet werden, müssen so behandelt werden, als wären sie in der Anfrage nicht enthalten. Der OAuth-Server muss nicht erkannte Anfrageparameter ignorieren. Anfrage- und Antwortparameter dürfen nicht mehr als einmal enthalten sein.
- GTAF unterstützt nur Bearer-Zugriffstokens.
Bereich des Zugriffstokens
Mit den Autorisierungs- und Token-Endpunkten kann der Client den Umfang der Zugriffsanfrage mit dem Anfrageparameter „scope“ angeben. Der Autorisierungsserver verwendet den Antwortparameter „scope“, um den Client über den Bereich des ausgestellten Zugriffstokens zu informieren.
Der Wert des Parameters „scope“ wird als Liste von durch Leerzeichen getrennten Strings angegeben, bei denen die Groß-/Kleinschreibung beachtet wird. Die Strings werden vom Autorisierungsserver definiert. Wenn der Wert mehrere durch Leerzeichen getrennte Strings enthält, spielt ihre Reihenfolge keine Rolle. Jeder String fügt dem angeforderten Bereich einen zusätzlichen Zugriffsbereich hinzu.
scope = scope-token *( SP scope-token )
scope-token = 1*( %x21 / %x23-5B / %x5D-7E )
Für GTAF ist die Implementierung des Bereichs nicht erforderlich, aber diese Funktion wird unterstützt. Weitere Informationen finden Sie in Abschnitt 3.3 von RFC 6749.
Ausstellen eines Zugriffstokens
Wenn die vom GTAF gesendete Zugriffstokenanfrage gültig und autorisiert ist, gibt der OAuth-Server ein Zugriffstoken und ein optionales Aktualisierungstoken aus. Wenn die Clientauthentifizierung für die Anfrage fehlschlägt oder die Anfrage ungültig ist, gibt der OAuth-Server eine Fehlerantwort zurück, wie im folgenden Abschnitt beschrieben.
Erfolgreiche Antwort
Wenn das GTAF eine Anfrage sendet, gibt der OAuth-Server ein Zugriffstoken und optional ein Aktualisierungstoken aus und erstellt die Antwort, indem er dem Entity-Body der HTTP-Antwort mit dem Statuscode 200 (OK) die folgenden Parameter hinzufügt: \
- access_token::ERFORDERLICH. Das vom OAuth-Server ausgegebene Zugriffstoken. GTAF erwartet, dass der Token-Endpunkt ein Inhabertoken zurückgibt.
- expires_in::ERFORDERLICH. Die Lebensdauer des Zugriffstokens in Sekunden. Der Wert „3600“ gibt beispielsweise an, dass das Zugriffstoken eine Stunde nach dem Zeitpunkt, zu dem die Antwort generiert wurde, abläuft. Wenn sie nicht angegeben ist, sollte der OAuth-Server die Ablaufzeit auf andere Weise angeben oder den Standardwert dokumentieren.
- token_type::ERFORDERLICH. Der Typ des ausgestellten Tokens. Weitere Informationen zu den verschiedenen Arten von Tokens finden Sie in Abschnitt 7.1 von RFC 6749. Beim Wert wird die Groß-/Kleinschreibung nicht berücksichtigt. Zum Zeitpunkt der Veröffentlichung dieses Dokuments werden in GTAF nur Bearer-Tokens unterstützt.
- refresh_token::OPTIONAL. Das Aktualisierungstoken, mit dem mit derselben Autorisierungsgewährung neue Zugriffstokens abgerufen werden können.
- scope:OPTIONAL, wenn implementiert und identisch mit dem vom GTAF angeforderten Bereich; andernfalls erforderlich.
Die Parameter sind im Entity-Body der HTTP-Antwort mit „application/json“ enthalten. Die Parameter werden in eine JSON-Struktur (JavaScript Object Notation) serialisiert, indem jeder Parameter auf der höchsten Strukturebene hinzugefügt wird. Parameternamen und String-Werte sind als JSON-Strings enthalten. Numerische Werte werden als JSON-Zahlen eingefügt. Die Reihenfolge der Parameter spielt keine Rolle und kann variieren.
Der Autorisierungsserver MUSS in jede Antwort, die Tokens, Anmeldedaten oder andere vertrauliche Informationen enthält, das HTTP-Antwortheaderfeld „Cache-Control“ mit dem Wert „no-store“ sowie das Antwortheaderfeld „Pragma“ mit dem Wert „no-cache“ einfügen.
Beispiel:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
"example_parameter":"example_value"
}
Im Folgenden finden Sie einige wichtige Punkte, die Sie beachten sollten:
- Die GTAF ignoriert nicht erkannte Wertnamen in der Antwort.
- Die Größen von Tokens und anderen Werten, die vom OAuth-Server empfangen werden, sind nicht definiert.
- Im GTAF sollten keine Annahmen über die Größe von Werten getroffen werden. Der OAuth-Server sollte die Größe aller ausgegebenen Werte dokumentieren.
Fehlerantwort
Wenn eine Autorisierungsanfrage aus irgendeinem Grund fehlschlägt, z. B. weil die Weiterleitungs-URI fehlt, ungültig ist oder nicht übereinstimmt, oder wenn die Client-ID fehlt oder ungültig ist, sollte der OAuth-Server mit dem HTTP-Statuscode 400 (Bad Request) antworten (sofern nicht anders angegeben) und mindestens einen der im Abschnitt „Fehlerantwort und ‑codes“ aufgeführten Parameter enthalten.
Autorisierungsgewährung in GTAF
Eine Autorisierungsberechtigung ist ein Anmeldedatum, das die Autorisierung des Endnutzers (für den Zugriff auf seine geschützten Ressourcen wie Datenvolumeninformationen) darstellt und vom GTAF verwendet wird, um ein Zugriffstoken zu erhalten.
Das GTAF verwendet den Grant-Typ client_credentials. Beim Grant-Typ client_credentials fordert GTAF ein Token mit einer HTTP POST-Anfrage und der HTTP-Basisauthentifizierung an. Alle Anfragen werden über TLS gesendet (d.h. HTTPS) und GTAF kann nicht in einen OAuth-Server ohne gültiges TLS-Zertifikat eingebunden werden. GTAF kann einen konfigurierbaren Tokenbereich übergeben und übergibt einen leeren Bereich, wenn keiner konfiguriert ist.
GTAF erwartet, dass ein Zugriffstoken zusammen mit einem „expires_in“-Wert (Gültigkeitsdauer) zurückgegeben wird. Der Wert für „expires_in“ sollte mindestens 900 Sekunden und nicht mehr als einige Stunden betragen. Das Anfordern eines neuen Tokens darf nicht dazu führen, dass vorhandene Tokens vorzeitig ablaufen.
Weitere Informationen zu den verschiedenen Berechtigungstypen finden Sie in Abschnitt 1.3 von RFC 6749.
Beispielanfrage und ‑antwort
Angenommen, das GTAF hat die folgende Konfiguration für einen OAuth-Server:
URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa
Hinweis:Der Clientschlüssel für eine echte DPA muss viel sicherer sein als der im Beispiel gezeigte.
Um den Autorisierungsstring zu erstellen, werden die Client-ID, „:“ und das Passwort verkettet und base64-codiert. Dies kann in einer Befehlszeilenschnittstelle so nachgebildet werden:
$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==
GTAF sendet dann mit diesen Anmeldedaten, dem Berechtigungstyp „client_credentials“ und dem konfigurierten Bereich eine HTTPS-POST-Anfrage an den OAuth-Server. Im Beispiel sieht die Anfrage von GTAF so ähnlich aus wie die Anfrage, die durch Folgendes generiert wird:
$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'
Die von GTAF verwendeten Headern stimmen nicht mit den von curl gesendeten Headern überein, der Autorisierungsheader ist jedoch identisch.
GTAF erwartet eine Antwort in folgendem Format:
{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}
Hier ist ein Beispiel für eine gültige Antwort:
{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}
Hinweis:Die Antwort muss gültiges JSON-Format haben.
Fehlerantwort und ‑codes
Wenn eine Autorisierungsanfrage von GTAF aus einem der im Abschnitt „Fehlerantwort“ genannten Gründe fehlschlägt, muss der OAuth-Server mit dem Statuscode „HTTP 400“ (Bad Request) antworten (sofern nicht anders angegeben) und einen der folgenden Parameter in die Antwort aufnehmen:
Beispiel: \
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error":"invalid_request"
}
GTAF erwartet, dass der OAuth-Server die folgenden Fehlerantworten unterstützt:
| Fehlercode | Antwort | Grund |
| HTTP 400 | invalid_request | In der Anfrage fehlt ein erforderlicher Parameter, sie enthält einen nicht unterstützten Parameterwert (außer „grant_type“), ein Parameter wird wiederholt, sie enthält mehrere Anmeldedaten, es wird mehr als ein Mechanismus für die Authentifizierung bei der GTAF verwendet oder sie ist anderweitig fehlerhaft. |
| HTTP 401 | invalid_client | Die Clientauthentifizierung ist fehlgeschlagen (z.B. unbekannter Client, keine Clientauthentifizierung enthalten oder nicht unterstützte Authentifizierungsmethode). Der OAuth-Server kann einen HTTP-Statuscode 401 (Nicht autorisiert) zurückgeben, um anzugeben, welche HTTP-Authentifizierungsschemas unterstützt werden. Wenn der Client versucht hat, sich über das Anfrageheaderfeld „Authorization“ zu authentifizieren, muss der OAuth-Server mit dem HTTP-Statuscode 401 (Unauthorized) antworten und das Antwortheaderfeld „WWW-Authenticate“ einfügen, das dem vom Client verwendeten Authentifizierungsschema entspricht. |
| HTTP 500 | OAuth-Serverfehler |
Weitere Informationen zu anderen Antworten, die zum Debuggen verwendet werden können, finden Sie in Abschnitt 5.2 von RFC 6749.