OAuth mit den Google Data APIs verwenden

Eric Bidelman, Google Data APIs-Team
September 2008

Einführung

Es ist eine spannende Zeit für Entwickler. Es gibt eine Reihe von offenen Standards, die im Web eingeführt werden. Google ist schon immer ein großer Fan von Standards und fördert die Open-Source-Community.

In letzter Zeit haben alle Google Data APIs die Unterstützung von OAuth unterstützt, einem offenen Protokoll, mit dem der Zugriff auf private Daten von Desktop- und Webanwendungen standardisiert werden soll. OAuth bietet eine Möglichkeit zur standardmäßigen und sicheren API-Authentifizierung. Als Programmierer sollten wir nach Möglichkeit Code verwenden. Mit OAuth können Entwickler weniger Code schreiben und so einfacher Tools erstellen, 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 vertraut sind. Wenn Sie gerade erst anfangen oder sich nur für OAuth interessieren, ist dies eine gute Alternative. In diesem Artikel werden die wichtigsten Grundlagen vorgestellt. Außerdem gehe ich auf die Details der OAuth-Implementierung von Google ein.

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

Terminologie

Bei OAuth geht es um die Terminologie. Die OAuth-Spezifikation und die OAuth-Authentifizierung für Webanwendungen von Google basieren stark auf bestimmten Definitionen. Daher möchten wir erklären, was die einzelnen Begriffe im Kontext der OAuth-Implementierung von Google bedeuten.

  1. „OAuth-Tanz“

    Meine inoffizielle Bezeichnung zur Beschreibung des vollständigen OAuth-Authentifizierungs-/-Autorisierungsprozesses.

  2. OAuth-Anfragetoken

    Ein anfängliches Token, das Google mitteilt, dass Ihre Anwendung Zugriff auf eine der Google Data APIs anfordert. Im zweiten Schritt des OAuth-Tanzes 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 des Tanzes wird das autorisierte Anfragetoken gegen ein Zugriffstoken ausgetauscht. Sobald Ihre Anwendung dieses Token hat, muss der Nutzer den OAuth-Tanz nicht noch einmal durchlaufen, es sei denn, das Token wird widerrufen.

    Ähnlichkeit mit AuthSub:
    Ein OAuth-Zugriffstoken ist mit einem sicheren AuthSub-Sitzungstoken identisch.

  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-Vorgangs. Die OAuth-Endpunkte von Google sind:

    Rufen Sie ein Anfragetoken ab:https://www.google.com/accounts/OAuthGetRequestToken
    Autorisieren Sie das Anfragetoken:https://www.google.com/accounts/OAuthAuthorizeToken
    Führen Sie ein Upgrade auf ein Zugriffstoken aus:https://www.google.com/accounts/OAuthGetAccessToken

    Ähnlichkeit mit AuthSub:
    Der Austausch eines autorisierten Anfrage-Tokens gegen ein Zugriffstoken ist mit dem Upgrade eines einmaligen AuthSub-Tokens auf ein langlebiges Sitzungstoken auf https://www.google.com/accounts/AuthSubRequestToken bzw. https://www.google.com/accounts/AuthSubSessionToken vergleichbar. Der Unterschied besteht darin, dass AuthSub nicht das Konzept eines ersten Anfragetokens hat. Stattdessen startet der Nutzer den Tokenprozess auf der Autorisierungsseite von AuthSubRequestToken.

  5. (OAuth)-Dienstanbieter

    Bei den Google Data APIs ist das der Google-Anbieter. Im Allgemeinen wird der Dienstanbieter verwendet, um die Website oder den Webdienst zu beschreiben, von dem die OAuth-Endpunkte bereitgestellt werden. Ein weiteres Beispiel für einen OAuth-Dienstanbieter ist MySpace.

  6. (OAuth)-Nutzer

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

Hinweis: Obwohl das OAuth-Protokoll den Anwendungsfall „Desktop“/„Installierte Anwendung“ unterstützt, unterstützt Google nur OAuth für Webanwendungen.

Erste Schritte

Anmeldung

Bevor Sie OAuth mit den Google Data APIs verwenden können, müssen Sie nur noch wenige Einstellungen vornehmen. Da alle OAuth-Anfragen digital signiert sein 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 mit registriertem Modus generieren.

Signieranfragen

Sobald Ihre Domain registriert ist, können Sie mit dem Signieren von Anfragen beginnen. Eines der schwierigsten Konzepte von OAuth ist die ordnungsgemäße Konstruktion von oauth_signature sowie das Konzept des Signatur-Basisstrings. Der Basisstring ist die Daten, die Sie mit Ihrem privaten Schlüssel (mit RSA_SHA1) signieren. Das Ergebnis ist der Wert, den Sie für oauth_signature festgelegt haben.

Beispielanfrage

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

Basisstringformat 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
HTTP-Beispielanfrage 
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: Dieser Schritt ist nur zu sehen. Deine oauth_signature ist viel länger.

Hinweise zum Basisstring:

  • Der orderby=starttime-Abfrageparameter wird zusammen mit den restlichen oauth_*-Parametern in lexikografischer Bytewertreihenfolge sortiert.
  • Dieser String enthält außerdem kein „?“-Zeichen.
  • Der Abschnitt base-http-request-url 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 Header Authorization:

  • Die Reihenfolge der oauth_*-Parameter spielt im Header Authorization keine Rolle.
  • Der Header enthält nicht den 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 zwischen AuthSub:
Zum Vergleich: Hier sehen Sie dasselbe Beispiel mit dem sicheren AuthSub:

Basisstringformat 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
HTTP-Beispielanfrage 
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 festgestellt, dass OAuth eine hohe Lernkurve aufweist. Im Vergleich zu anderen Authentifizierungs-APIs von Google stimme ich zu. Die Vorteile von OAuth werden deutlich, wenn Sie Ihre Anwendung für die Verwendung anderer Dienste (nicht von Google) erweitern. Das Schreiben eines einzelnen Authentifizierungscodes, der bei verschiedenen Dienstanbietern und deren APIs funktioniert, klingt gut. Sie werden sich später bei Ihnen dafür bedanken, dass Sie das Protokoll jetzt gelernt haben.

OAuth Playground ist ein Tool, das ich entwickelt habe, um Entwickler bei der Heilung ihrer OAuth-Probleme zu unterstützen. Mit Playground können Sie Probleme beheben, Ihre eigene Implementierung prüfen oder mit den Google Data APIs experimentieren.

Was passiert, wenn ich die Option nutze?

  1. Veranschaulicht den OAuth-Authentifizierungsvorgang: Abrufen eines Anfragetokens, Autorisieren des Tokens und Aktualisieren des Tokens auf ein Zugriffstoken.
  2. Zeigt für jede Anfrage den korrekten Signaturbasestring an.
  3. Zeigt für jede Anfrage den richtigen Authorization-Header an.
  4. Veranschaulicht die Verwendung eines oauth_token für die Interaktion mit einem authentifizierten Google-Datenfeed. Sie können Daten vom Typ GET/POST/PUT/DELETE abrufen.
  5. Authentifizierten Feed direkt im Browser ansehen
  6. Ermöglicht es Ihnen, Ihre oauth_consumer_key (Ihre registrierte Domain) und Ihren privaten Schlüssel zu testen.
  7. Erfahren Sie, welche Google-Daten-Feed-Dienste für oauth_token verfügbar sind.

Demo ausführen

Schritt 1: Umfang(e) auswählen

Entscheiden Sie zuerst, 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 mit AuthSub:
AuthSub erfordert auch den Parameter scope, um den Datenbereich zu steuern, auf den 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. Bitte verwende nur den privaten Schlüssel TEST.

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

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

Unterschied zu AuthSub:
In der sicheren AuthSub-Domain gibt es keinen Parameter, der einen Domainnamen explizit festlegt. Die Domain ist Teil des URL-Parameters next. In OAuth gibt es einen solchen Parameter: oauth_consumer_key. Legen Sie dafür Ihre registrierte Domain fest.

Schritt 3–5: Zugriffstoken abrufen

Zum Abrufen eines OAuth-Zugriffstokens sind drei Schritte erforderlich. Der erste Schritt ist das Abrufen eines Anfragetokens. So weiß Google, dass Ihre Anwendung den OAuth-Dance startet.

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

Bestimmte Felder werden mit Daten gefüllt.

  • Unter „Basisstring für Signatur“ sehen Sie die korrekte Form des Basisstrings, der zum Erstellen des Parameters oauth_signature verwendet wird.
  • Im Autorisierungsheader wird der entsprechende Authorization-Header für die Anfrage angezeigt.
  • Das Feld „OAuth-Parameter ändern“ mit den Werten oauth_nonce und oauth_timestamp in der Anfrage.
  • Die Eingabe oauth_token wurde mit dem entsprechenden Wert im Antworttext ausgefüllt. In Playground wird auch angezeigt, welche Art von oauth_token wir aktuell haben. Im Moment ist es ein Anfragetoken.

Klicken Sie dann im Feld „Token anfordern“ auf die Schaltfläche „Autorisieren“.

Klicken Sie auf dieser Autorisierungsseite auf die Schaltfläche „Zugriff erlauben“, um das Anfragetoken zu autorisieren und zurück zum OAuth Playground zu gelangen.

Ähnlichkeit mit AuthSub:
Diese Autorisierungsseite ist für AuthSub identisch.

Unterschied zum AuthSub-Objekt:
Der URL-Parameter next von AuthSub entspricht dem Parameter oauth_callback. Der Unterschied besteht darin, dass oauth_callback in OAuth optional ist. Nachdem der Nutzer auf die Schaltfläche „Zugriff erlauben“ geklickt hat, wird das Anfragetoken autorisiert und das Tokenupgrade 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 sie eine bessere Nutzererfahrung bietet.

Klicken Sie dann im Feld „Token anfordern“ auf die Schaltfläche „Zugriffstoken“.

Durch diese Aktion wird das autorisierte Anfrage-Token aktualisiert (siehe rotes Zugriffstoken).

Wenn Sie ein neues Token abrufen möchten, klicken Sie auf „Neu beginnen“, um den OAuth-Tanz 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 vorsichtig, wenn Sie die letzten drei HTTP-Methoden ausführen, während Sie mit Ihren echten Daten arbeiten.

Tipp: Klicken Sie auf die Schaltfläche „Verfügbare Feeds“, um Feeds zu finden, die für Ihr Zugriffstoken verfügbar sind.

Hier ein Beispiel für eine Abfrage: GET http://www.blogger.com/feeds/1982051675575479214/posts/default?max-results=3

In diesem Beispiel werden maximal drei Posts pro Blog zurückgegeben. Sie können den zurückgegebenen Feed/Eintrag auch direkt in Ihrem Browser anzeigen. Klicken Sie dazu unter dem hervorgehobenen Bereich auf die Schaltfläche „Im Browser ansehen“.

Beispiel: Beitrag aktualisieren

  1. Suchen Sie im Beitrag, den Sie aktualisieren möchten, nach dem Element <link> mit einer rel="edit". Das sollte ungefähr so 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 den XML-Code des vorhandenen Eintrags, indem Sie oben im hervorgehobenen Feld auf „Nur Ebene anzeigen“ klicken. Kopieren Sie nur den Antworttext, nicht die Header.
  3. Ändern Sie das Drop-down-Menü für die HTTP-Methode in PUT.
  4. Klicken Sie unter diesem Drop-down-Menü auf „Beitragsdaten eingeben“ und fügen Sie die XML-Datei <entry> in das Pop-up-Fenster ein.
  5. Klicken Sie auf die Schaltfläche „Ausführen“.

Der Server antwortet mit 200 OK.

Tipp: Entfernen Sie das Häkchen im Kästchen „Syntaxhervorhebung?“, anstatt den Link edit manuell zu kopieren. Nach einer Abfrage können Sie auf die Links in den XML-Antworttexten klicken.

Fazit

Technologien wie das AtomPub/Atom Publishing Protocol (untergeordnetes Protokoll der Google Data APIs) und OAuth helfen dabei, das Web voranzutreiben. Da immer mehr Websites diese Standards akzeptieren, sind unsere Entwickler die Gewinner. Das Erstellen einer genialen App wird plötzlich weniger schwierig.

Wenn Sie Fragen oder Kommentare zu OAuth Playground haben oder OAuth mit Google APIs verwenden, besuchen Sie das Supportforum für G Suite APIs und Marketplace APIs.

Ressourcen