OAuth mit den Google Data APIs verwenden

Eric Bidelman, Google Data APIs-Team
September 2008

Einführung

Das sind spannende Zeiten für Entwickler. Wir sehen, dass eine Reihe offener Standards im Web eingeführt werden. Google war schon immer ein großer Fan von Standards und der Förderung der Open-Source-Community.

Vor Kurzem wurde in allen Google Data APIs die Unterstützung für OAuth eingeführt. Dieses offene Protokoll soll die Art und Weise standardisieren, wie Desktop- und Webanwendungen auf die privaten Daten eines Nutzers zugreifen. OAuth bietet eine standardisierte und sichere Methode zur API-Authentifizierung. Als Programmierer lernen wir, Code nach Möglichkeit wiederzuverwenden. OAuth hilft Entwicklern, die Menge an doppeltem Code zu reduzieren, und erleichtert die Erstellung von Tools, die mit mehreren Diensten von verschiedenen Anbietern funktionieren.

Zielgruppe

In diesem Artikel wird davon ausgegangen, dass Sie mit einer oder mehreren Google Data APIs vertraut sind, aber nicht unbedingt mit den Konzepten hinter OAuth. Wenn Sie gerade erst anfangen oder einfach nur mehr über OAuth erfahren möchten, sind Sie hier genau richtig. In diesem Artikel werden die Grundlagen der Konzepte erläutert. Außerdem werde ich die Details der OAuth-Implementierung von Google erläutern.

Dieses Dokument richtet sich auch an Entwickler, die mit der Verwendung von AuthSub vertraut sind, insbesondere im Modus mit erweiterter Sicherheit registriert. Im Folgenden werde ich versuchen, die Ähnlichkeiten und Unterschiede zwischen den beiden Protokollen hervorzuheben. Wenn Sie Anwendungen mit AuthSub haben, können Sie diese Informationen verwenden, um zu OAuth zu migrieren, einem offeneren, modernen Protokoll.

Einige Begriffe

Um OAuth zu verstehen, müssen Sie die Terminologie kennen. Die OAuth-Spezifikation und die Dokumentation OAuth-Authentifizierung für Webanwendungen von Google basieren stark auf bestimmten Definitionen. Daher möchten wir klären, was die einzelnen Begriffe im Kontext der OAuth-Implementierung von Google bedeuten.

  1. „OAuth-Ablauf“

    Mein inoffizieller Begriff für den vollständigen OAuth-Authentifizierungs- und ‑Autorisierungsprozess.

  2. (OAuth) Anfragetoken

    Ein erstes Token, mit dem Google erfährt, dass Ihre Anwendung Zugriff auf eine der Google Data APIs anfordert. Im zweiten Schritt des OAuth-Ablaufs muss der Nutzer manuell Zugriff auf seine Daten gewähren. Wenn dieser Schritt erfolgreich ist, wird das Anfragetoken autorisiert.

  3. (OAuth-)Zugriffstoken

    Im letzten Schritt wird das autorisierte Anfragetoken gegen ein Zugriffstoken eingetauscht. Sobald Ihre Anwendung dieses Token hat, muss ein Nutzer den OAuth-Ablauf nicht noch einmal durchlaufen, es sei denn, das Token wird widerrufen.

    Ähnlichkeit zu AuthSub
    Ein OAuth-Zugriffstoken ist dasselbe wie ein sicheres AuthSub-Sitzungstoken.

  4. (OAuth-)Endpunkte

    Dies sind URIs, die zum Authentifizieren einer Anwendung und zum Abrufen eines Zugriffstokens erforderlich sind. Es gibt insgesamt drei, einen für jeden Schritt des OAuth-Prozesses. Die OAuth-Endpunkte von Google sind:

    Fordern Sie ein Anfrage-Token an:https://www.google.com/accounts/OAuthGetRequestToken
    Autorisieren Sie das Anfragetoken:https://www.google.com/accounts/OAuthAuthorizeToken
    So führen Sie ein Upgrade auf ein Zugriffstoken durch:https://www.google.com/accounts/OAuthGetAccessToken

    Ähnlichkeit zu AuthSub:
    Das Eintauschen eines autorisierten Anfragetokens gegen ein Zugriffstoken entspricht dem Upgrade eines AuthSub-Einmal-Tokens auf ein langlebiges Sitzungstoken unter https://www.google.com/accounts/AuthSubRequestToken bzw. https://www.google.com/accounts/AuthSubSessionToken. Der Unterschied besteht darin, dass es bei AuthSub kein Konzept für ein anfängliches Anfragetoken gibt. Stattdessen startet der Nutzer den Tokenprozess auf der Autorisierungsseite AuthSubRequestToken.

  5. (OAuth-)Dienstanbieter

    Bei den Google Data APIs ist dieser Anbieter Google. Im Allgemeinen wird der Begriff „Dienstanbieter“ verwendet, um die Website oder den Webdienst zu beschreiben, der die OAuth-Endpunkte bereitstellt. Ein weiteres Beispiel für einen OAuth-Dienstanbieter ist MySpace.

  6. (OAuth-)Consumer

    Das Programm, das die Berechtigung zum Zugriff auf die Daten eines Nutzers anfordert (d.h. Ihre Anwendung). Das OAuth-Protokoll ist flexibel und unterstützt eine Vielzahl verschiedener Clienttypen (Web, installiert, Desktop, Mobil).

Hinweis: Das OAuth-Protokoll unterstützt zwar den Anwendungsfall für Desktop-/installierte Anwendungen, Google unterstützt OAuth jedoch nur für Webanwendungen.

Erste Schritte

Anmeldung

Bevor Sie OAuth mit den Google Data APIs verwenden können, müssen Sie einige Schritte ausführen. Da alle OAuth-Anfragen digital signiert werden müssen, müssen Sie zuerst Ihre Domain registrieren und ein öffentliches Zertifikat bei Google hochladen. Weitere Informationen dazu finden Sie unter Registrierung für webbasierte Anwendungen und Schlüssel und Zertifikate für die Verwendung im registrierten Modus generieren.

Signieranfragen

Sobald Ihre Domain registriert ist, können Sie Anfragen signieren. Eines der schwierigsten Konzepte von OAuth ist die richtige Erstellung von oauth_signature und die Signaturbasiszeichenfolge. Die Basis-String ist der Wert, den Sie mit Ihrem privaten Schlüssel signieren (mit RSA_SHA1). Das Ergebnis ist der Wert, den Sie für oauth_signature festlegen.

Beispielanfrage

GET eine Liste der Google-Kalender eines Nutzers unter http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime

Format des Basis-Strings base_string = http-method&base-http-request-url&normalized-string-of-oauth_parameters
Beispiel für einen Basisstring GET&http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D4572616e48616d6d%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D137131200%26oauth_token%3D1%252Fab3cd9j4ks73hf7g%26oauth_version%3D1.0%26orderby%3Dstarttime
Beispiel für eine HTTP-Anfrage 
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: OAuth oauth_token="1%2Fab3cd9j4ks73hf7g", oauth_signature_method="RSA-SHA1", oauth_signature="wOJIO9AvZbTSMK%2FPY%3D...", oauth_consumer_key="example.com", oauth_timestamp="137131200", oauth_nonce="4572616e48616d6d", oauth_version="1.0"

Hinweis: Dies dient nur als Darstellung. Ihre oauth_signature wird viel länger sein.

Hinweise zum Basisstring:

  • Der Abfrageparameter orderby=starttime wird zusammen mit den anderen oauth_*-Parametern in lexikografischer Byte-Wert-Reihenfolge sortiert.
  • Dieser String enthält auch kein Fragezeichen.
  • Der base-http-request-url-Teil enthält nur die URL-codierte Basis-URL: http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull.
  • oauth_token ist doppelt URL-codiert.

Hinweise zum Authorization-Header:

  • Die Reihenfolge der oauth_*-Parameter im Authorization-Header spielt keine Rolle.
  • Der Header enthält nicht orderby=starttime wie der Basisstring. Dieser Abfrageparameter wird als Teil der Anfrage-URL beibehalten.

Weitere Informationen zum Signieren von Anfragen mit OAuth finden Sie unter OAuth-Anfragen signieren.

Unterschied zu AuthSub
Zum Vergleich hier dasselbe Beispiel mit sicherem AuthSub:

Format des Basis-Strings base_string = http-method http-request-URL timestamp nonce
Beispiel für einen Basisstring 
GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d
Beispiel für eine HTTP-Anfrage 
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: AuthSub token="GD32CMCL25aZ-v____8B" data="GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 137131200 4572616e48616d6d" sig="MCwCFrV93K4agg==..." sigalg="rsa-sha1"

Weitere Informationen zum Signieren von Anfragen mit AuthSub finden Sie unter AuthSub-Anfragen signieren.

OAuth Playground-Tool

Zweck

Einige Nutzer haben angemerkt, dass OAuth eine hohe Lernkurve hat. Im Vergleich zu anderen Authentifizierungs-APIs von Google stimme ich zu. Der Vorteil von OAuth wird deutlich, wenn Sie Ihre App so erweitern, dass sie andere (nicht von Google stammende) Dienste verwendet. Einen einzigen Authentifizierungscode zu schreiben, der für verschiedene Dienstanbieter und ihre APIs funktioniert, klingt für mich ziemlich gut. Sie werden es sich später danken, wenn Sie das Protokoll jetzt lernen.

Der OAuth Playground ist ein Tool, das ich erstellt habe, um Entwicklern bei ihren OAuth-Problemen zu helfen. Mit dem Playground können Sie Probleme beheben, Ihre eigene Implementierung prüfen oder mit den Google Data APIs experimentieren.

Welche Funktionen sind enthalten?

  1. Hier wird der OAuth-Authentifizierungsvorgang veranschaulicht: Abrufen eines Anfragetokens, Autorisieren des Tokens und Aktualisieren des Tokens zu einem Zugriffstoken.
  2. Zeigt für jede Anfrage den richtigen Signaturbasisstring an.
  3. Zeigt für jede Anfrage den richtigen Authorization-Header an.
  4. Hier wird gezeigt, wie Sie mit einem oauth_token mit einem authentifizierten Google-Datenfeed interagieren. Sie können Daten für GET/POST/PUT/DELETE abrufen.
  5. Authentifizierte Feeds direkt im Browser ansehen
  6. Damit können Sie Ihre eigene oauth_consumer_key (Ihre registrierte Domain) und Ihren privaten Schlüssel testen.
  7. Hier erfahren Sie, welche Google-Dienste für Datenfeeds für Ihr oauth_token verfügbar sind.

Demolauf

Schritt 1: Bereiche auswählen

Legen Sie zuerst fest, welche APIs Sie verwenden möchten, indem Sie einen oder mehrere Bereiche auswählen. In dieser Demonstration fordere ich ein Token an, das mit Blogger und Google Kontakte funktioniert.

Ähnlichkeit zu AuthSub
Auch bei AuthSub ist der Parameter scope erforderlich, um den Bereich der Daten zu steuern, auf die ein Token zugreifen kann. Google hat diesen Parameter wie in der OAuth-Spezifikation vorgeschlagen implementiert.

Schritt 2: OAuth-Parameter und -Einstellungen ändern

Ändern Sie vorerst keine Einstellungen im Feld „OAuth-Parameter ändern“. Später können Sie mit Ihrem eigenen privaten Schlüssel testen, indem Sie oauth_consumer_key in Ihre registrierte Domain ändern und Ihren privaten Schlüssel eingeben, indem Sie auf „Eigenen privaten Schlüssel verwenden“ klicken. Verwenden Sie nur einen TEST-Schlüssel.

Hinweis: Nur die Felder oauth_signature_method und oauth_consumer_key können hier bearbeitet werden. Die oauth_timestamp, oauth_nonce und oauth_token werden automatisch für Sie generiert.

Zusätzlich zu RSA-SHA1 können Sie für die oauth_signature_method auch HMAC-SHA1 verwenden. In diesem Fall werden im Playground zusätzliche Felder angezeigt, in die Sie Ihr eigenes oauth_consumer_key und Consumer-Secret eingeben müssen. Diese Werte finden Sie für Ihre registrierte Domain auf der Seite https://www.google.com/accounts/ManageDomains.

Unterschied zu AuthSub
Bei Secure AuthSub gibt es keinen Parameter, um einen Domainnamen explizit festzulegen. Die Domain ist im URL-Parameter next enthalten. Einen solchen Parameter gibt es in OAuth: oauth_consumer_key. Legen Sie sie auf Ihre registrierte Domain fest.

Schritte 3 bis 5: Zugriffstoken abrufen

Es gibt drei Schritte, um ein OAuth-Zugriffstoken zu erhalten. Der erste Schritt besteht darin, ein Anfragetoken abzurufen. Dadurch erfährt Google, dass Ihre Anwendung den OAuth-Ablauf startet.

Klicken Sie zuerst im Feld „Token abrufen“ auf die Schaltfläche „Token anfordern“.

Bestimmte Felder werden mit Daten gefüllt.

  • Im Feld „Signaturbasisstring“ wird die richtige Form des Basisstrings angezeigt, der zum Erstellen des Parameters oauth_signature verwendet wird.
  • Im „Autorisierungs-Header“ wird der entsprechende Authorization-Header für die Anfrage angezeigt.
  • Das Feld „OAuth-Parameter ändern“ ist mit den Werten oauth_nonce und oauth_timestamp ausgefüllt, die in der Anfrage gesendet wurden.
  • Die Eingabe oauth_token wurde mit dem entsprechenden Wert aus dem Antworttext gefüllt. Im Playground wird auch angezeigt, welche Art von oauth_token wir derzeit haben. Derzeit ist es ein Anfragetoken.

Klicken Sie als Nächstes im Feld „Token abrufen“ auf die Schaltfläche „Autorisieren“.

Klicken Sie auf dieser Autorisierungsseite auf die Schaltfläche „Zugriff gewähren“, um das Anfragetoken zu autorisieren und zum OAuth Playground zurückgeleitet zu werden.

Ähnlichkeit zu AuthSub
Diese Autorisierungsseite ist für AuthSub identisch.

Unterschied zu AuthSub:
Der next-URL-Parameter von AuthSub entspricht dem oauth_callback-Parameter. Der Unterschied besteht darin, dass die oauth_callback in OAuth optional ist. Nachdem der Nutzer auf die Schaltfläche „Zugriff gewähren“ geklickt hat, wird das Anforderungstoken autorisiert und das Token-Upgrade auf https://www.google.com/accounts/OAuthGetAccessToken kann asynchron durchgeführt werden.

Tipp: Wenn Sie eine Webanwendung schreiben, sollten Sie eine oauth_callback-URL angeben, da dies die Nutzerfreundlichkeit verbessert.

Klicken Sie abschließend im Feld „Get the Token“ (Token abrufen) auf die Schaltfläche „Access token“ (Zugriffstoken).

Dadurch wird das autorisierte Anfragetoken aktualisiert (siehe rotes Label „Zugriffstoken“).

Wenn Sie ein neues Token abrufen möchten, klicken Sie auf „Von vorn beginnen“, um den OAuth-Ablauf neu zu starten.

Jetzt können wir etwas Interessantes tun.

Zugriffstoken verwenden

Jetzt können Sie Feeds abfragen, Daten einfügen, aktualisieren oder löschen. Seien Sie bei diesen letzten drei HTTP-Methoden vorsichtig, da Sie mit Ihren echten Daten arbeiten.

Tipp: Wenn Sie herausfinden möchten, welche Feeds für Ihr Zugriffstoken verfügbar sind, klicken Sie auf die Schaltfläche „Verfügbare Feeds“.

Hier eine Beispielabfrage: GET http://www.blogger.com/feeds/1982051675575479214/posts/default?max-results=3

In diesem Beispiel werden maximal drei Beiträge in einem bestimmten Blog zurückgegeben. Sie können den zurückgegebenen Feed bzw. Eintrag auch direkt in Ihrem Browser aufrufen. Klicken Sie dazu unter dem Bereich mit der hervorgehobenen Syntax auf den Link „Im Browser ansehen“.

Beispiel: Beitrag aktualisieren

  1. Suchen Sie im Beitrag, den Sie aktualisieren möchten, nach dem <link>-Element mit einem rel="edit". Er sollte etwa folgendermaßen aussehen: 
    <link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>

    Fügen Sie die href-URL in die Eingabe „Google-Datenfeed eingeben“ ein.

  2. Kopieren Sie das XML des vorhandenen Eintrags, indem Sie oben im Bereich mit der Syntaxhervorhebung auf „view plain“ (Als Nur-Text anzeigen) klicken. Kopieren Sie nur den Antworttext, nicht die Header.
  3. Ändern Sie die Drop-down-Liste für die HTTP-Methode zu PUT.
  4. Klicken Sie unter diesem Drop-down-Menü auf „Beitragsdaten eingeben“ und fügen Sie die <entry>-XML-Datei in das Pop-up-Fenster ein.
  5. Klicken Sie auf die Schaltfläche „Ausführen“.

Der Server antwortet mit 200 OK.

Tipp: Anstatt den edit-Link manuell zu kopieren, können Sie das Kästchen „Syntax Highlight?“ deaktivieren. Nach einer Anfrage können Sie auf die Links im XML-Antworttext klicken.

Fazit

Technologien wie das AtomPub-/Atom Publishing Protocol (zugrunde liegendes Protokoll der Google Data APIs) und OAuth tragen zur Weiterentwicklung des Webs bei. Je mehr Websites diese Standards unterstützen, desto besser für uns Entwickler. Das Erstellen einer Killer-App wird dadurch plötzlich weniger entmutigend.

Wenn Sie Fragen oder Anmerkungen zum OAuth Playground oder zur Verwendung von OAuth mit Google APIs haben, besuchen Sie uns im G Suite APIs and Marketplace APIs Support Forum.

Ressourcen