OAuth 2.0 für clientseitige Webanwendungen

OAuth 2.0-Endpunkte

Generieren Sie eine URL, um Zugriff über den OAuth 2.0-Endpunkt von Google unter https://accounts.google.com/o/oauth2/v2/auth anzufordern. Auf diesen Endpunkt kann über HTTPS zugegriffen werden. Normale HTTP-Verbindungen werden abgelehnt.

Der Google-Autorisierungsserver unterstützt die folgenden Suchstringparameter für Webanwendungsserver:

Beispiel für eine Weiterleitung zum Autorisierungsserver von Google

Unten sehen Sie eine Beispiel-URL mit Zeilenumbrüchen und Leerzeichen für eine bessere Lesbarkeit.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

Nachdem du die Anfrage-URL erstellt hast, leite den Nutzer dorthin weiter.

JavaScript-Beispielcode

Im folgenden JavaScript-Snippet wird gezeigt, wie der Autorisierungsablauf in JavaScript ohne Verwendung der Clientbibliothek für JavaScript von Google APIs gestartet wird. Da dieser OAuth 2.0-Endpunkt keine CORS-Unterstützung (Cross-Origin Resource Sharing) bietet, wird mit dem Snippet ein Formular erstellt, über das die Anfrage an diesen Endpunkt geöffnet wird.

/*
 * Create form to request access token from Google's OAuth 2.0 server.
 */
function oauthSignIn() {
  // Google's OAuth 2.0 endpoint for requesting an access token
  var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

  // Create <form> element to submit parameters to OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'GET'); // Send as a GET request.
  form.setAttribute('action', oauth2Endpoint);

  // Parameters to pass to OAuth 2.0 endpoint.
  var params = {'client_id': 'YOUR_CLIENT_ID',
                'redirect_uri': 'YOUR_REDIRECT_URI',
                'response_type': 'token',
                'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly',
                'include_granted_scopes': 'true',
                'state': 'pass-through value'};

  // Add form parameters as hidden input values.
  for (var p in params) {
    var input = document.createElement('input');
    input.setAttribute('type', 'hidden');
    input.setAttribute('name', p);
    input.setAttribute('value', params[p]);
    form.appendChild(input);
  }

  // Add form to page and submit it to open the OAuth 2.0 endpoint.
  document.body.appendChild(form);
  form.submit();
}

OAuth 2.0-Endpunkte

Der OAuth 2.0-Server sendet eine Antwort an die in Ihrer Zugriffstokenanfrage angegebene redirect_uri.

Wenn der Nutzer die Anfrage genehmigt, enthält die Antwort ein Zugriffstoken. Wenn der Nutzer die Anfrage nicht genehmigt, enthält die Antwort eine Fehlermeldung. Das Zugriffstoken oder die Fehlermeldung wird im Hash-Fragment des Weiterleitungs-URIs zurückgegeben, wie unten dargestellt:

• Eine Antwort mit einem Zugriffstoken:

  https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600

  Neben dem Parameter access_token enthält der Fragment-String auch den Parameter token_type, der immer auf Bearer festgelegt ist, und den Parameter expires_in, der die Gültigkeitsdauer des Tokens in Sekunden angibt. Wenn der Parameter state in der Zugriffstokenanfrage angegeben wurde, ist sein Wert auch in der Antwort enthalten.

• Eine Fehlerantwort:

  https://oauth2.example.com/callback#error=access_denied

Beispiel für eine OAuth 2.0-Serverantwort

Sie können diesen Ablauf testen, indem Sie auf die folgende Beispiel-URL klicken. Dabei wird schreibgeschützter Zugriff angefordert, um Metadaten für Dateien in Google Drive aufzurufen, und schreibgeschützter Zugriff, um Ihre Google Kalender-Termine aufzurufen:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

Nach Abschluss des OAuth 2.0-Vorgangs wirst du zu http://localhost/oauth2callback weitergeleitet. Diese URL führt zu einem 404 NOT FOUND-Fehler, es sei denn, auf Ihrem lokalen Computer wird zufällig eine Datei an dieser Adresse bereitgestellt. Im nächsten Schritt erfahren Sie mehr über die Informationen, die im URI zurückgegeben werden, wenn der Nutzer zu Ihrer Anwendung zurückgeleitet wird.

OAuth 2.0-Endpunkte

Ob der Nutzer Ihrer Anwendung Zugriff auf einen bestimmten Bereich gewährt hat, sehen Sie im Feld scope in der Antwort des Zugriffstokens. Die Zugriffsbereiche, die durch das access_token gewährt werden, als Liste von durch Leerzeichen getrennten Strings, die zwischen Groß- und Kleinschreibung unterscheiden.

In der folgenden Beispielantwort für ein Zugriffstoken ist beispielsweise zu sehen, dass der Nutzer Ihrer Anwendung Lesezugriff auf Drive-Aktivitäten und Kalendertermine gewährt hat:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

OAuth 2.0-Endpunkte

Nachdem Ihre Anwendung ein Zugriffstoken erhalten hat, können Sie damit im Namen eines bestimmten Nutzerkontos eine Google API aufrufen, sofern die von der API erforderlichen Zugriffsbereiche gewährt wurden. Dazu fügen Sie das Zugriffstoken in eine Anfrage an die API ein, indem Sie entweder einen access_token-Abfrageparameter oder einen Authorization-HTTP-Header-Bearer-Wert angeben. Wenn möglich, ist der HTTP-Header vorzuziehen, da Suchstrings in Serverprotokollen in der Regel sichtbar sind. In den meisten Fällen können Sie mit einer Clientbibliothek Aufrufe von Google APIs einrichten, z. B. beim Aufrufen der Drive Files API.

Im OAuth 2.0 Playground können Sie alle Google APIs ausprobieren und sich ihre Bereiche ansehen.

Beispiele für HTTP-GET

Ein Aufruf des Endpunkts drive.files (Drive Files API) mit dem HTTP-Header Authorization: Bearer könnte so aussehen: Sie müssen Ihr eigenes Zugriffstoken angeben:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Hier ist ein Aufruf derselben API für den authentifizierten Nutzer mit dem Abfragestringparameter access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Beispiele für curl

Sie können diese Befehle mit der Befehlszeilenanwendung curl testen. Hier ein Beispiel, in dem die HTTP-Header-Option verwendet wird (bevorzugt):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Alternativ können Sie auch die Option „Abfragestringparameter“ verwenden:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

JavaScript-Beispielcode

Im folgenden Code-Snippet wird gezeigt, wie Sie mit CORS (Cross-Origin Resource Sharing) eine Anfrage an eine Google API senden. In diesem Beispiel wird die Google APIs-Clientbibliothek für JavaScript nicht verwendet. Auch wenn Sie die Clientbibliothek nicht verwenden, hilft Ihnen der Leitfaden zur CORS-Unterstützung in der Dokumentation dieser Bibliothek wahrscheinlich, diese Anfragen besser zu verstehen.

In diesem Code-Snippet steht die Variable access_token für das Token, das Sie erhalten haben, um im Namen des autorisierten Nutzers API-Anfragen zu senden. Im vollständigen Beispiel wird gezeigt, wie dieses Token im lokalen Speicher des Browsers gespeichert und bei einer API-Anfrage abgerufen wird.

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/drive/v3/about?fields=user&' +
    'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
  console.log(xhr.response);
};
xhr.send(null);

OAuth 2.0-Endpunkte

In diesem Codebeispiel wird gezeigt, wie der OAuth 2.0-Ablauf in JavaScript abgeschlossen wird, ohne die Google APIs-Clientbibliothek für JavaScript zu verwenden. Der Code ist für eine HTML-Seite mit einer Schaltfläche zum Testen einer API-Anfrage. Wenn Sie auf die Schaltfläche klicken, wird im Code geprüft, ob die Seite ein API-Zugriffstoken im lokalen Speicher Ihres Browsers gespeichert hat. Andernfalls wird die API-Anfrage ausgeführt. Andernfalls wird der OAuth 2.0-Vorgang gestartet.

Für den OAuth 2.0-Vorgang werden auf der Seite die folgenden Schritte ausgeführt:

1. Der Nutzer wird zum OAuth 2.0-Server von Google weitergeleitet, der Zugriff auf die Bereiche https://www.googleapis.com/auth/drive.metadata.readonly und https://www.googleapis.com/auth/calendar.readonly anfordert.
2. Nachdem der Nutzer einem oder mehreren angeforderten Bereichen Zugriff gewährt oder diesen abgelehnt hat, wird er zur ursprünglichen Seite weitergeleitet, auf der das Zugriffstoken aus dem String der Fragment-ID geparst wird.
3. Auf der Seite wird geprüft, für welche Bereiche der Nutzer der Anwendung Zugriff gewährt hat.

4. Wenn der Nutzer Zugriff auf die angeforderten Bereiche gewährt hat, wird auf der Seite das Zugriffstoken verwendet, um die Beispiel-API-Anfrage zu senden.

   In der API-Anfrage wird die Methode about.get der Drive API aufgerufen, um Informationen zum Google Drive-Konto des autorisierten Nutzers abzurufen.

5. Wenn die Anfrage erfolgreich ausgeführt wird, wird die API-Antwort in der Debug-Konsole des Browsers protokolliert.

Sie können den Zugriff auf die App über die Seite Berechtigungen für Ihr Google-Konto widerrufen. Die App wird als OAuth 2.0-Demo für Google API Docs aufgeführt.

Wenn Sie diesen Code lokal ausführen möchten, müssen Sie Werte für die Variablen YOUR_CLIENT_ID und YOUR_REDIRECT_URI festlegen, die Ihren Anmeldedaten entsprechen. Die Variable YOUR_REDIRECT_URI sollte auf dieselbe URL festgelegt sein, über die die Seite ausgeliefert wird. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, die Sie in der konfiguriert haben. Wenn dieser Wert nicht mit einem autorisierten URI übereinstimmt, wird der Fehler redirect_uri_mismatch ausgegeben. Außerdem muss für Ihr Projekt die entsprechende API für diese Anfrage aktiviert sein.

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';

  // Parse query string to see if page request is coming from OAuth 2.0 server.
  var fragmentString = location.hash.substring(1);
  var params = {};
  var regex = /([^&=]+)=([^&]*)/g, m;
  while (m = regex.exec(fragmentString)) {
    params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
  }
  if (Object.keys(params).length > 0 && params['state']) {
    if (params['state'] == localStorage.getItem('state')) {
      localStorage.setItem('oauth2-test-params', JSON.stringify(params) );

      trySampleRequest();
    } else {
      console.log('State mismatch. Possible CSRF attack');
    }
  }

  // Function to generate a random state value
  function generateCryptoRandomState() {
    const randomValues = new Uint32Array(2);
    window.crypto.getRandomValues(randomValues);

    // Encode as UTF-8
    const utf8Encoder = new TextEncoder();
    const utf8Array = utf8Encoder.encode(
      String.fromCharCode.apply(null, randomValues)
    );

    // Base64 encode the UTF-8 data
    return btoa(String.fromCharCode.apply(null, utf8Array))
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=+$/, '');
  }

  // If there's an access token, try an API request.
  // Otherwise, start OAuth 2.0 flow.
  function trySampleRequest() {
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    if (params && params['access_token']) { 
      // User authorized the request. Now, check which scopes were granted.
      if (params['scope'].includes('https://www.googleapis.com/auth/drive.metadata.readonly')) {
        // User authorized read-only Drive activity permission.
        // Calling the APIs, etc.
        var xhr = new XMLHttpRequest();
        xhr.open('GET',
          'https://www.googleapis.com/drive/v3/about?fields=user&' +
          'access_token=' + params['access_token']);
        xhr.onreadystatechange = function (e) {
          if (xhr.readyState === 4 && xhr.status === 200) {
            console.log(xhr.response);
          } else if (xhr.readyState === 4 && xhr.status === 401) {
            // Token invalid, so prompt for user permission.
            oauth2SignIn();
          }
        };
        xhr.send(null);
      }
      else {
        // User didn't authorize read-only Drive activity permission.
        // Update UX and application accordingly
        console.log('User did not authorize read-only Drive activity permission.');
      }

      // Check if user authorized Calendar read permission.
      if (params['scope'].includes('https://www.googleapis.com/auth/calendar.readonly')) {
        // User authorized Calendar read permission.
        // Calling the APIs, etc.
        console.log('User authorized Calendar read permission.');
      }
      else {
        // User didn't authorize Calendar read permission.
        // Update UX and application accordingly
        console.log('User did not authorize Calendar read permission.');
      } 
    } else {
      oauth2SignIn();
    }
  }

  /*
   * Create form to request access token from Google's OAuth 2.0 server.
   */
  function oauth2SignIn() {
    // create random state value and store in local storage
    var state = generateCryptoRandomState();
    localStorage.setItem('state', state);

    // Google's OAuth 2.0 endpoint for requesting an access token
    var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

    // Create element to open OAuth 2.0 endpoint in new window.
    var form = document.createElement('form');
    form.setAttribute('method', 'GET'); // Send as a GET request.
    form.setAttribute('action', oauth2Endpoint);

    // Parameters to pass to OAuth 2.0 endpoint.
    var params = {'client_id': YOUR_CLIENT_ID,
                  'redirect_uri': YOUR_REDIRECT_URI,
                  'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly',
                  'state': state,
                  'include_granted_scopes': 'true',
                  'response_type': 'token'};

    // Add form parameters as hidden input values.
    for (var p in params) {
      var input = document.createElement('input');
      input.setAttribute('type', 'hidden');
      input.setAttribute('name', p);
      input.setAttribute('value', params[p]);
      form.appendChild(input);
    }

    // Add form to page and submit it to open the OAuth 2.0 endpoint.
    document.body.appendChild(form);
    form.submit();
  }
</script>

<button onclick="trySampleRequest();">Try sample request</button>
</body></html>

OAuth 2.0-Endpunkte

Wenn Sie einem vorhandenen Zugriffstoken Bereiche hinzufügen möchten, fügen Sie den Parameter include_granted_scopes in Ihre Anfrage an den OAuth 2.0-Server von Google ein.

Das folgende Code-Snippet zeigt, wie das geht. Im Snippet wird davon ausgegangen, dass Sie die Bereiche, für die Ihr Zugriffstoken gültig ist, im lokalen Speicher des Browsers gespeichert haben. Im vollständigen Beispiel wird eine Liste der Zugriffsbereiche gespeichert, für die das Zugriffstoken gültig ist. Dazu wird die Property oauth2-test-params.scope im lokalen Speicher des Browsers festgelegt.

Im Snippet werden die Bereiche, für die das Zugriffstoken gültig ist, mit dem Bereich verglichen, den Sie für eine bestimmte Abfrage verwenden möchten. Wenn der Zugriffsbereich nicht durch das Zugriffstoken abgedeckt ist, wird der OAuth 2.0-Ablauf gestartet. Hier ist die oauth2SignIn-Funktion dieselbe wie in Schritt 2 (und wird später im vollständigen Beispiel verwendet).

var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));

var current_scope_granted = false;
if (params.hasOwnProperty('scope')) {
  var scopes = params['scope'].split(' ');
  for (var s = 0; s < scopes.length; s++) {
    if (SCOPE == scopes[s]) {
      current_scope_granted = true;
    }
  }
}

if (!current_scope_granted) {
  oauth2SignIn(); // This function is defined elsewhere in this document.
} else {
  // Since you already have access, you can proceed with the API request.
}

OAuth 2.0-Endpunkte

Wenn Sie ein Token programmatisch widerrufen möchten, sendet Ihre Anwendung eine Anfrage an https://oauth2.googleapis.com/revoke und fügt das Token als Parameter hinzu:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Das Token kann ein Zugriffs- oder Aktualisierungstoken sein. Wenn es sich bei dem Token um ein Zugriffstoken handelt und es ein entsprechendes Aktualisierungstoken hat, wird auch das Aktualisierungstoken widerrufen.

Wenn der Widerruf erfolgreich verarbeitet wurde, lautet der HTTP-Statuscode der Antwort 200. Bei Fehlerbedingungen wird der HTTP-Statuscode 400 zusammen mit einem Fehlercode zurückgegeben.

Im folgenden JavaScript-Snippet wird gezeigt, wie ein Token in JavaScript widerrufen wird, ohne die Clientbibliothek für Google APIs für JavaScript zu verwenden. Da der OAuth 2.0-Endpunkt von Google zum Widerrufen von Tokens keine CORS-Unterstützung (Cross-Origin Resource Sharing) bietet, wird im Code ein Formular erstellt und an den Endpunkt gesendet, anstatt die Anfrage mit der XMLHttpRequest()-Methode zu senden.

function revokeAccess(accessToken) {
  // Google's OAuth 2.0 endpoint for revoking access tokens.
  var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';

  // Create <form> element to use to POST data to the OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'post');
  form.setAttribute('action', revokeTokenEndpoint);

  // Add access token to the form so it is set as value of 'token' parameter.
  // This corresponds to the sample curl request, where the URL is:
  //      https://oauth2.googleapis.com/revoke?token={token}
  var tokenField = document.createElement('input');
  tokenField.setAttribute('type', 'hidden');
  tokenField.setAttribute('name', 'token');
  tokenField.setAttribute('value', accessToken);
  form.appendChild(tokenField);

  // Add form to page and submit it to actually revoke the token.
  document.body.appendChild(form);
  form.submit();
}