OAuth 2.0 für clientseitige Webanwendungen

In diesem Dokument wird erläutert, wie Sie die OAuth 2.0-Autorisierung implementieren, um über eine JavaScript-Webanwendung auf Google APIs zuzugreifen. OAuth 2.0 ermöglicht Nutzern, bestimmte Daten für eine Anwendung freizugeben, während ihre Nutzernamen, Passwörter und andere Informationen privat bleiben. Eine Anwendung kann beispielsweise OAuth 2.0 verwenden, um von Nutzern die Berechtigung zum Speichern von Dateien in Google Drive zu erhalten.

Dieser OAuth 2.0-Vorgang wird als impliziter Berechtigungsvorgang bezeichnet. Sie ist für Anwendungen gedacht, die nur dann auf APIs zugreifen, wenn der Nutzer in der Anwendung aktiv ist. Diese Anwendungen können keine vertraulichen Informationen speichern.

In diesem Ablauf öffnet Ihre App eine Google-URL, die Suchparameter verwendet, um Ihre App und den Typ des API-Zugriffs zu identifizieren, den die App benötigt. Sie können die URL im aktuellen Browserfenster oder in einem Dialogfeld öffnen. Der Nutzer kann sich bei Google authentifizieren und die angeforderten Berechtigungen gewähren. Anschließend leitet Google den Nutzer zurück zu Ihrer App. Die Weiterleitung enthält ein Zugriffstoken, das von Ihrer App überprüft und dann für API-Anfragen verwendet wird.

Google APIs-Clientbibliothek und Google Identity Services

Wenn Sie die Google APIs-Clientbibliothek für JavaScript verwenden, um autorisierte Aufrufe an Google zu senden, sollten Sie die JavaScript-Bibliothek der Google Identity Services verwenden, um den Autorisierungsablauf zu verarbeiten. Wir empfehlen dringend, das Codemodell der Google Identity Services zu verwenden, das auf dem sichereren Autorisierungscode-Vorgang mit PKCE basiert.

Vorbereitung

Die APIs für Ihr Projekt aktivieren

Für jede Anwendung, die Google APIs aufruft, müssen diese APIs in der API Console aktiviert werden.

So aktivieren Sie eine API für Ihr Projekt:

1. Öffnen Sie die API-Bibliothek in der Google API Console.
2. Wählen Sie ein Projekt aus oder erstellen Sie ein neues, wenn Sie dazu aufgefordert werden.
3. In der API-Bibliothek finden Sie alle verfügbaren APIs, gruppiert nach Produktfamilie und Beliebtheit. Wenn die API, die Sie aktivieren möchten, nicht in der Liste angezeigt wird, können Sie die Suchfunktion verwenden oder in der Produktfamilie, zu der sie gehört, auf Alle ansehen klicken.
4. Wählen Sie die gewünschte API aus und klicken Sie dann auf den Button Aktivieren.
5. Aktivieren Sie die Abrechnung, wenn Sie dazu aufgefordert werden.
6. Lesen und akzeptieren Sie die Nutzungsbedingungen der API, wenn Sie dazu aufgefordert werden.

Anmeldedaten für die Autorisierung erstellen

Jede Anwendung, die OAuth 2.0 für den Zugriff auf Google APIs verwendet, muss über Autorisierungsdaten verfügen, mit denen sie sich gegenüber dem OAuth 2.0-Server von Google identifiziert. In den folgenden Schritten wird beschrieben, wie Sie Anmeldedaten für Ihr Projekt erstellen. Ihre Anwendungen können dann mit den Anmeldedaten auf APIs zugreifen, die Sie für dieses Projekt aktiviert haben.

1. Rufen Sie die Seite „Clients“ auf.
2. Klicken Sie auf Client erstellen.
3. Wählen Sie den Anwendungstyp Webanwendung aus.
4. Füllen Sie es aus. Anwendungen, die JavaScript verwenden, um autorisierte Google API-Anfragen zu stellen, müssen autorisierte JavaScript-Quellen angeben. Die Ursprünge identifizieren die Domains, von denen Ihre Anwendung Anfragen an den OAuth 2.0-Server senden kann. Diese Ursprünge müssen den Validierungsregeln von Google entsprechen.

Zugriffsbereiche identifizieren

Mit Bereichen kann Ihre Anwendung nur Zugriff auf die Ressourcen anfordern, die sie benötigt. Außerdem können Nutzer so den Umfang des Zugriffs steuern, den sie Ihrer Anwendung gewähren. Es kann also eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit geben, dass die Nutzereinwilligung erteilt wird.

Bevor Sie mit der Implementierung der OAuth 2.0-Autorisierung beginnen, sollten Sie die Bereiche ermitteln, für die Ihre App Zugriffsberechtigungen benötigt.

Das Dokument OAuth 2.0-API-Bereiche enthält eine vollständige Liste der Bereiche, die Sie für den Zugriff auf Google APIs verwenden können.

OAuth 2.0-Zugriffstokens abrufen

In den folgenden Schritten wird gezeigt, wie Ihre Anwendung mit dem OAuth 2.0-Server von Google interagiert, um die Einwilligung eines Nutzers einzuholen, eine API-Anfrage im Namen des Nutzers auszuführen. Ihre Anwendung muss diese Einwilligung einholen, bevor sie eine Google API-Anfrage ausführen kann, für die eine Nutzerautorisierung erforderlich ist.

Schritt 1: Weiterleitung zum OAuth 2.0-Server von Google

Wenn Sie die Berechtigung für den Zugriff auf die Daten eines Nutzers anfordern möchten, leiten Sie den Nutzer an den OAuth 2.0-Server von Google weiter.

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//developers.google.com/oauthplayground&
 client_id=client_id

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

Schritt 2: Google fordert den Nutzer auf, seine Einwilligung zu erteilen

In diesem Schritt entscheidet der Nutzer, ob er Ihrer Anwendung den angeforderten Zugriff gewährt. In dieser Phase zeigt Google ein Zustimmungsfenster an, in dem der Name Ihrer Anwendung und die Google API-Dienste, für die sie mit den Autorisierungsdaten des Nutzers Zugriff anfordert, sowie eine Zusammenfassung der zu gewährenden Zugriffsbereiche aufgeführt sind. Der Nutzer kann dann zustimmen, den Zugriff auf einen oder mehrere von Ihrer Anwendung angeforderte Bereiche zu gewähren, oder die Anfrage ablehnen.

Ihre Anwendung muss in dieser Phase nichts tun, während sie auf die Antwort des OAuth 2.0-Servers von Google wartet, die angibt, ob Zugriff gewährt wurde. Diese Antwort wird im folgenden Schritt erläutert.

Schritt 3: OAuth 2.0-Serverantwort verarbeiten

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//developers.google.com/oauthplayground&
 client_id=client_id

Schritt 4: Prüfen, welche Bereiche Nutzer gewährt haben

Wenn Sie mehrere Berechtigungen (Bereiche) anfordern, gewähren Nutzer Ihrer App möglicherweise nicht Zugriff auf alle. In deiner App muss geprüft werden, welche Bereiche tatsächlich gewährt wurden. Außerdem müssen Situationen, in denen einige Berechtigungen verweigert werden, ordnungsgemäß behandelt werden. In der Regel werden dazu die Funktionen deaktiviert, die auf diesen verweigerten Bereichen basieren.

Es gibt allerdings Ausnahmen. Bei Google Workspace Enterprise-Apps mit domainweiter Übertragung von Befugnissen oder Apps, die als Vertrauenswürdig gekennzeichnet sind, wird der Zustimmungsbildschirm für detaillierte Berechtigungen umgangen. Für diese Apps wird Nutzern der Bildschirm für die Einwilligung in detaillierte Berechtigungen nicht angezeigt. Stattdessen erhält Ihre App entweder alle angeforderten Bereiche oder keine.

Weitere Informationen finden Sie unter Umgang mit detaillierten Berechtigungen.

  {
    "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"
  }

Google APIs aufrufen

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

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

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

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

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

Vollständiges Beispiel

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

Validierungsregeln für JavaScript-Quellen

Google wendet die folgenden Validierungsregeln auf JavaScript-Quellen an, um Entwicklern dabei zu helfen, ihre Anwendungen zu schützen. Ihre JavaScript-Ursprünge müssen diesen Regeln entsprechen. Die Definitionen von Domain, Host und Schema, die in diesen Regeln verwendet werden, finden Sie in RFC 3986, Abschnitt 3.

Inkrementelle Autorisierung

Im OAuth 2.0-Protokoll fordert Ihre App die Autorisierung für den Zugriff auf Ressourcen an, die durch Bereiche identifiziert werden. Es gilt als Best Practice für die Nutzerfreundlichkeit, die Autorisierung für Ressourcen erst dann anzufordern, wenn sie benötigt werden. Um diese Vorgehensweise zu ermöglichen, unterstützt der Autorisierungsserver von Google die inkrementelle Autorisierung. Mit dieser Funktion können Sie Bereiche nach Bedarf anfordern. Wenn der Nutzer die Berechtigung für den neuen Bereich erteilt, wird ein Autorisierungscode zurückgegeben, der gegen ein Token eingetauscht werden kann, das alle Bereiche enthält, die der Nutzer dem Projekt gewährt hat.

Eine App, mit der Nutzer Musikstücke anhören und Mixe erstellen können, benötigt bei der Anmeldung möglicherweise nur wenige Ressourcen, vielleicht nur den Namen der Person, die sich anmeldet. Zum Speichern eines fertigen Mixes ist jedoch Zugriff auf Google Drive erforderlich. Die meisten Nutzer würden es als natürlich empfinden, wenn sie erst dann um Zugriff auf ihr Google Drive gebeten werden, wenn die App ihn tatsächlich benötigt.

In diesem Fall kann die App bei der Anmeldung die Bereiche openid und profile anfordern, um eine einfache Anmeldung durchzuführen, und dann später bei der ersten Anfrage zum Speichern eines Mixes den Bereich https://www.googleapis.com/auth/drive.file anfordern.

Für ein Zugriffstoken, das über eine inkrementelle Autorisierung abgerufen wird, gelten die folgenden Regeln:

• Das Token kann verwendet werden, um auf Ressourcen zuzugreifen, die einem der Bereiche entsprechen, die in die neue, kombinierte Autorisierung einbezogen wurden.
• Wenn Sie das Aktualisierungstoken für die kombinierte Autorisierung verwenden, um ein Zugriffstoken zu erhalten, steht das Zugriffstoken für die kombinierte Autorisierung und kann für alle in der Antwort enthaltenen scope-Werte verwendet werden.
• Die kombinierte Autorisierung umfasst alle Bereiche, die der Nutzer dem API-Projekt gewährt hat, auch wenn die Gewährungen von verschiedenen Clients angefordert wurden. Wenn ein Nutzer beispielsweise über den Desktop-Client einer Anwendung Zugriff auf einen Bereich gewährt und dann über einen mobilen Client Zugriff auf einen anderen Bereich derselben Anwendung gewährt, umfasst die kombinierte Autorisierung beide Bereiche.
• Wenn Sie ein Token widerrufen, das eine kombinierte Autorisierung darstellt, wird der Zugriff auf alle Bereiche dieser Autorisierung im Namen des zugehörigen Nutzers gleichzeitig widerrufen.

Die folgenden Codebeispiele zeigen, wie Sie einem vorhandenen Zugriffstoken Bereiche hinzufügen. So muss Ihre App nicht mehrere Zugriffstokens verwalten.

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.
}

Token-Widerruf

In einigen Fällen möchte ein Nutzer möglicherweise den Zugriff einer Anwendung widerrufen. Nutzer können den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen finden Sie im Supportdokument Drittanbieter-Websites und ‑Apps mit Zugriff auf Ihr Konto im Abschnitt „Zugriff von Websites oder Apps entfernen“.

Eine Anwendung kann den ihr gewährten Zugriff auch programmatisch widerrufen. Der programmatische Widerruf ist wichtig, wenn ein Nutzer ein Abo kündigt, eine Anwendung entfernt oder sich die von einer App benötigten API-Ressourcen erheblich geändert haben. Das bedeutet, dass ein Teil des Entfernungsprozesses eine API-Anfrage sein kann, um sicherzustellen, dass die der Anwendung zuvor gewährten Berechtigungen entfernt werden.

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

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