OAuth 2.0 für JavaScript-Webanwendungen verwenden

OAuth 2.0-Endpunkte

Generieren Sie eine URL, um Zugriff vom OAuth 2.0-Endpunkt von Google unter https://accounts.google.com/o/oauth2/v2/auth anzufordern. Dieser Endpunkt ist über HTTPS zugänglich. Einfache HTTP-Verbindungen werden abgelehnt.

Der Google-Autorisierungsserver unterstützt die folgenden Abfragestringparameter für Webserveranwendungen:

Beispiel für eine Weiterleitung an den Google-Autorisierungsserver

In der Beispiel-URL unten wird der Offlinezugriff (access_type=offline) auf einen Bereich angefordert, der den Zugriff auf das YouTube-Konto des Nutzers ermöglicht. Dabei wird die inkrementelle Autorisierung verwendet, um sicherzustellen, dass das neue Zugriffstoken alle Bereiche abdeckt, auf die der Nutzer der Anwendung zuvor Zugriff gewährt hat. In der URL werden auch Werte für die erforderlichen Parameter redirect_uri, response_type und client_id sowie für den Parameter state festgelegt. Die URL enthält Zeilenumbrüche und Leerzeichen für eine bessere Lesbarkeit.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 client_id=client_id

Nachdem Sie die Anfrage-URL erstellt haben, leiten Sie den Nutzer dorthin weiter.

JavaScript-Beispielcode

Im folgenden JavaScript-Snippet wird gezeigt, wie der Autorisierungsablauf in JavaScript initiiert wird, ohne die Google API-Clientbibliothek für JavaScript zu verwenden. Da dieser OAuth 2.0-Endpunkt kein Cross-Origin Resource Sharing (CORS) unterstützt, wird im Snippet ein Formular erstellt, mit dem 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/youtube.force-ssl',
                '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 den redirect_uri, der in Ihrer Zugriffstokenanfrage angegeben ist.

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-URI 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

  Zusätzlich zum 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, mit der schreibgeschützter Zugriff zum Anzeigen von Metadaten für Dateien in Ihrem Google Drive und schreibgeschützter Zugriff zum Anzeigen Ihrer Google Kalender-Termine angefordert wird:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 client_id=client_id

Nach Abschluss des OAuth 2.0-Vorgangs werden Sie zu http://localhost/oauth2callback weitergeleitet. Diese URL führt zu einem 404 NOT FOUND-Fehler, sofern auf Ihrem lokalen Computer keine Datei unter dieser Adresse bereitgestellt wird. Im nächsten Schritt finden Sie weitere Informationen zu den Informationen, die im URI zurückgegeben werden, wenn der Nutzer zu Ihrer Anwendung zurückgeleitet wird.

OAuth 2.0-Endpunkte

Wenn Sie prüfen möchten, ob der Nutzer Ihrer Anwendung Zugriff auf einen bestimmten Bereich gewährt hat, sehen Sie sich das Feld scope in der Antwort des Zugriffstokens an. Die Zugriffsbereiche, die durch das access_token gewährt werden, ausgedrückt als Liste von durch Leerzeichen getrennten, case-sensitiven Strings.

Die folgende Beispielantwort für ein Zugriffstoken gibt beispielsweise an, dass der Nutzer Ihrer Anwendung die Berechtigung erteilt hat, die YouTube-Videos, ‑Bewertungen, ‑Kommentare und ‑Untertitel des Nutzers anzusehen, zu bearbeiten und dauerhaft zu löschen:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

OAuth 2.0-Endpunkte

Nachdem Ihre Anwendung ein Zugriffstoken erhalten hat, können Sie das Token verwenden, um im Namen eines bestimmten Nutzerkontos Aufrufe an eine Google API zu senden, sofern die von der API erforderlichen Zugriffsbereiche gewährt wurden. Dazu müssen Sie das Zugriffstoken in eine Anfrage an die API einfügen. Verwenden Sie dazu entweder den Abfrageparameter access_token oder den HTTP-Header Authorization mit dem Wert Bearer. Wenn möglich, ist der HTTP-Header vorzuziehen, da Abfragestrings in der Regel in Serverlogs sichtbar sind. In den meisten Fällen können Sie eine Clientbibliothek verwenden, um Ihre Aufrufe von Google APIs einzurichten, z. B. beim Aufrufen der YouTube Data API.

Hinweis: Die YouTube Data API unterstützt Dienstkonten nur für YouTube-Rechteinhaber, die mehrere YouTube-Kanäle besitzen und verwalten, z. B. Musiklabels und Filmstudios.

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

Beispiele für HTTP GET

Ein Aufruf des Endpunkts youtube.channels (YouTube Data API) mit dem HTTP-Header Authorization: Bearer könnte so aussehen: Sie müssen Ihr eigenes Zugriffstoken angeben:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Hier ist ein Aufruf derselben API für den authentifizierten Nutzer mit dem Query-String-Parameter access_token:

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

Beispiele für curl

Sie können diese Befehle mit der curl-Befehlszeilenanwendung testen. Hier ein Beispiel mit der HTTP-Header-Option (bevorzugt):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

Alternativ können Sie auch die Option für den Abfragestringparameter verwenden:

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

JavaScript-Beispielcode

Das folgende Code-Snippet zeigt, wie Sie CORS (Cross-Origin Resource Sharing) verwenden, um eine Anfrage an eine Google API zu senden. In diesem Beispiel wird die Google APIs-Clientbibliothek für JavaScript nicht verwendet. Auch wenn Sie die Clientbibliothek nicht verwenden, kann Ihnen der Leitfaden zur CORS-Unterstützung in der Dokumentation der Bibliothek helfen, diese Anfragen besser zu verstehen.

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

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true&' +
    '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 Sie den OAuth 2.0-Ablauf in JavaScript abschließen, ohne die Google APIs-Clientbibliothek für JavaScript zu verwenden. Der Code ist für eine HTML-Seite, auf der eine Schaltfläche zum Ausführen einer API-Anfrage angezeigt wird. Wenn Sie auf die Schaltfläche klicken, wird geprüft, ob auf der Seite ein API-Zugriffstoken im lokalen Speicher Ihres Browsers gespeichert ist. Wenn ja, 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, auf dem Zugriff auf den Bereich https://www.googleapis.com/auth/youtube.force-ssl angefordert wird.
2. Nachdem der Nutzer den Zugriff auf einen oder mehrere angeforderte Bereiche gewährt (oder verweigert) hat, wird er zur ursprünglichen Seite weitergeleitet, die das Zugriffstoken aus dem Fragment-ID-String parst.
3. Auf der Seite wird geprüft, auf welche Bereiche der Nutzer der Anwendung Zugriff gewährt hat.

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

   Mit dieser API-Anfrage wird die Methode channels.list der YouTube Data API aufgerufen, um Daten zum YouTube-Kanal des autorisierten Nutzers abzurufen.

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

Sie können den Zugriff auf die App über die Seite Berechtigungen Ihres Google-Kontos widerrufen. Die App wird als OAuth 2.0-Demo für Google API-Dokumente 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 Autorisierungsanmeldedaten entsprechen. Die Variable YOUR_REDIRECT_URI sollte auf dieselbe URL festgelegt werden, über die die Seite bereitgestellt wird. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie in der konfiguriert haben. Wenn dieser Wert nicht mit einem autorisierten URI übereinstimmt, erhalten Sie einen redirect_uri_mismatch-Fehler. In Ihrem Projekt muss auch 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']) { 
      var xhr = new XMLHttpRequest();
      xhr.open('GET',
          'https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true&' +
          '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 {
      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/youtube.force-ssl',
                  '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

In diesem Beispiel fordert die aufrufende Anwendung Zugriff an, um die YouTube Analytics-Daten des Nutzers abzurufen. Dies gilt zusätzlich zu allen anderen Zugriffsberechtigungen, die der Nutzer der Anwendung bereits erteilt hat.

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 Beispielcode wird eine Liste der Zugriffsbereiche gespeichert, für die das Zugriffstoken gültig ist. Dazu wird die Eigenschaft 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 Anfrage verwenden möchten. Wenn das Zugriffstoken diesen Bereich nicht abdeckt, wird der OAuth 2.0-Ablauf gestartet. Die Funktion oauth2SignIn ist dieselbe wie in Schritt 2 (und später im vollständigen Beispiel).

var SCOPE = 'https://www.googleapis.com/auth/youtube.force-ssl';
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 ein:

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 ein Aktualisierungstoken sein. Wenn es sich bei dem Token um ein Zugriffstoken handelt und es ein entsprechendes Aktualisierungstoken gibt, wird auch das Aktualisierungstoken widerrufen.

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

Das folgende JavaScript-Snippet zeigt, wie ein Token in JavaScript widerrufen wird, ohne die Google APIs Client Library for JavaScript zu verwenden. Da der OAuth 2.0-Endpunkt von Google zum Widerrufen von Tokens kein Cross-Origin Resource Sharing (CORS) unterstützt, wird im Code ein Formular erstellt und an den Endpunkt gesendet, anstatt die XMLHttpRequest()-Methode zum Senden der Anfrage zu verwenden.

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();
}