Nutzerauthentifizierung

Webauthentifizierungsprotokolle nutzen HTTP-Funktionen, aber Chrome-Apps werden innerhalb des App-Containers ausgeführt. Sie werden nicht über HTTP geladen und können keine Weiterleitungen ausführen oder Cookies setzen.

Verwenden Sie die Chrome Identity API, um Nutzer zu authentifizieren: die getAuthToken für Nutzer, die in ihrem Google-Konto angemeldet sind, und die launchWebAuthFlow für Nutzer, die nicht in einem Google-Konto angemeldet sind. Wenn Ihre Anwendung einen eigenen Server zum Authentifizieren von Nutzern verwendet, müssen Sie Letzteres verwenden.

Funktionsweise

Nutzer von Chrome-Apps haben ein Google-Konto, das mit ihrem Profil verknüpft ist. Apps können OAuth2-Tokens für diese Nutzer über die getAuthToken API abrufen.

Anwendungen, die eine Authentifizierung mit Identitätsanbietern außerhalb von Google durchführen möchten, müssen launchWebAuthFlow aufrufen. Bei dieser Methode werden in einem Browser-Pop-up die Anbieterseiten angezeigt und Weiterleitungen zu den spezifischen URL-Mustern erfasst. Die Weiterleitungs-URLs werden an die Anwendung übergeben und die Anwendung extrahiert das Token aus der URL.

Google-Kontoauthentifizierung

Führen Sie dazu die folgenden fünf Schritte aus:

  1. Füge deinem Manifest Berechtigungen hinzu und lade deine App hoch.
  2. Kopieren Sie den Schlüssel aus der installierten manifest.json in Ihr Quellmanifest, damit die Anwendungs-ID während der Entwicklung konstant bleibt.
  3. Rufen Sie eine OAuth2-Client-ID für Ihre Chrome-App ab.
  4. Aktualisieren Sie das Manifest, um die Client-ID und Bereiche anzugeben.
  5. Authentifizierungstoken abrufen.

Berechtigungen hinzufügen und App hochladen

Die Berechtigung zur Identitätsbestätigung muss in Ihrem Manifest enthalten sein. Anschließend können Sie Ihre Anwendung auf die Verwaltungsseite für Apps und Erweiterungen hochladen (siehe Veröffentlichen).

"permissions": [
  "identity"
]

Schlüssel in Manifest kopieren

Wenn Sie Ihre Anwendung in der Google OAuth-Konsole registrieren, geben Sie die ID Ihrer Anwendung an. Diese wird bei Tokenanfragen überprüft. Daher ist es wichtig, während der Entwicklung eine konsistente Anwendungs-ID zu haben.

Damit die App-ID konstant bleibt, müssen Sie den Schlüssel im installierten manifest.json in Ihr Quellmanifest kopieren. Das ist zwar nicht die hübscheste Aufgabe, aber so läuft es:

  1. Gehen Sie zu Ihrem Nutzerdatenverzeichnis. Beispiel unter macOS: ~/Library/Application\ Support/Google/Chrome/Default/Extensions
  2. Listen Sie die installierten Apps und Erweiterungen auf und gleichen Sie hier die App-ID auf der Verwaltungsseite für Apps und Erweiterungen mit dieser ID ab.
  3. Rufen Sie das Verzeichnis der installierten App auf. Dabei handelt es sich um eine Version innerhalb der App-ID. Öffnen Sie die installierte Datei manifest.json. Mit Pico können Sie die Datei schnell öffnen.
  4. Kopiere den „Schlüssel“ im installierten manifest.json und füge ihn in die Quelldatei deines App-Manifests ein.

OAuth2-Client-ID abrufen

Sie müssen Ihre Anwendung in der Google APIs-Konsole registrieren, um die Client-ID zu erhalten:

  1. Melden Sie sich in der Google APIs-Konsole mit demselben Google-Konto an, das Sie zum Hochladen Ihrer Anwendung in den Chrome Web Store verwendet haben.
  2. Erstellen Sie ein neues Projekt, indem Sie das Drop-down-Menü oben links maximieren und den Menüpunkt Create... (Erstellen) auswählen.
  3. Nachdem Sie die Anwendung erstellt und benannt haben, rufen Sie das Navigationsmenü „Dienste“ auf und aktivieren Sie alle Google-Dienste, die für die Anwendung erforderlich sind.
  4. Gehen Sie zum Menüpunkt "API Access" (API-Zugriff) und klicken Sie auf die blaue Schaltfläche Create an OAuth 2.0 client ID... (OAuth 2.0-Client-ID erstellen...).
  5. Geben Sie die erforderlichen Markeninformationen ein und wählen Sie den Typ Installierte App aus.
  6. Wählen Sie Chrome-Anwendung aus und geben Sie Ihre Anwendungs-ID ein. Dieselbe ID wird auf der Verwaltungsseite für Apps und Erweiterungen angezeigt.

Manifest mit OAuth2-Client-ID und Bereichen aktualisieren

Aktualisiere dein Manifest, um die Client-ID und Bereiche anzugeben. Hier sehen Sie das "oauth2"-Beispiel für das gdrive-Beispiel:

"oauth2": {
    "client_id": "665859454684.apps.googleusercontent.com",
    "scopes": [
      "https://www.googleapis.com/auth/drive"
    ]
  }

Zugriffstokens abrufen

Jetzt können Sie das Authentifizierungstoken durch Aufrufen von identity.getAuthToken abrufen.

chrome.identity.getAuthToken({ 'interactive': true }, function(token) {
  // Use the token.
});

Nutzerinteraktion

Beim Aufrufen von getAuthToken können Sie ein Flag ('interactive': true im obigen Beispiel) übergeben, das angibt, ob die API im interaktiven Modus oder im Lautlos-Modus aufgerufen werden soll. Wenn Sie die API im interaktiven Modus aufrufen, wird dem Nutzer bei Bedarf eine Anmelde- und/oder Genehmigungsoberfläche angezeigt, wie im folgenden Screenshot dargestellt:

Screenshot der Benutzeroberfläche, wenn eine Anwendung die Identity API zum Authentifizieren eines Google-Kontos verwendet

Wenn Sie die API im Lautlos-Modus aufrufen, gibt die API nur dann ein Token zurück, wenn ein Token erstellt werden kann, ohne dass eine Benutzeroberfläche angezeigt wird. Dies ist nützlich, wenn eine App den Ablauf beim Start der Anwendung ausführt, oder allgemein in Fällen, in denen keine Nutzergeste beteiligt ist.

Wir empfehlen, den Lautlos-Modus zu verwenden, wenn keine Nutzergeste erforderlich ist, und den interaktiven Modus, wenn eine Nutzer-Geste vorhanden ist (z. B. wenn der Nutzer auf die Anmeldeschaltfläche in Ihrer App geklickt hat). Beachten Sie, dass keine Gestenanforderung erzwungen wird.

Caching

Chrome verfügt über einen speicherinternen Cache mit Zugriffstokens, sodass Sie getAuthToken jederzeit aufrufen können, wenn Sie ein Token verwenden müssen. Der Ablauf des Tokens wird vom Cache automatisch gesteuert.

Sie können den aktuellen Status des Token-Cache unter chrome://identity-internals sehen.

In einigen Fällen funktionieren nicht abgelaufene Zugriffstokens nicht mehr, z. B. wenn der Nutzer sein Passwort ändert. API-Aufrufe, die das Token verwenden, geben den HTTP-Statuscode 401 zurück. Sollte dies der Fall sein, können Sie das ungültige Token aus dem Cache von Chrome entfernen. Rufen Sie dazu identity.removeCachedAuthToken auf.

Beispiel für die Verwendung von removeCachedAuthToken:

// callback = function (error, httpStatus, responseText);
function authenticatedXhr(method, url, callback) {
  var retry = true;
  function getTokenAndXhr() {
    chrome.identity.getAuthToken({/* details */},
                                 function (access_token) {
      if (chrome.runtime.lastError) {
        callback(chrome.runtime.lastError);
        return;
      }

      var xhr = new XMLHttpRequest();
      xhr.open(method, url);
      xhr.setRequestHeader('Authorization',
                           'Bearer ' + access_token);

      xhr.onload = function () {
        if (this.status === 401 && retry) {
          // This status may indicate that the cached
          // access token was invalid. Retry once with
          // a fresh token.
          retry = false;
          chrome.identity.removeCachedAuthToken(
              { 'token': access_token },
              getTokenAndXhr);
          return;
        }

        callback(null, this.status, this.responseText);
      }
    });
  }
}

Nicht-Google-Kontoauthentifizierung

Führen Sie dazu die folgenden drei Schritte aus:

  1. Registrieren Sie sich beim Anbieter.
  2. Füge Berechtigungen für Anbieterressourcen hinzu, auf die deine App zugreift.
  3. Authentifizierungstoken abrufen.

Beim Anbieter registrieren

Sie müssen beim Anbieter eine OAuth2-Client-ID registrieren und die Client-ID als Website konfigurieren. Verwenden Sie für den Weiterleitungs-URI, der bei der Registrierung eingegeben wird, die URL im folgenden Format: https://<extension-id>.chromiumapp.org/<anything-here>

Wenn die Anwendungs-ID beispielsweise abcdefghijklmnopqrstuvwxyzabcdef lautet und Sie provider_cb als Pfad verwenden möchten, sollten Sie Folgendes verwenden, um sie mit Weiterleitungs-URIs von anderen Anbietern zu unterscheiden: https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb

Berechtigungen für Anbieter hinzufügen

Wenn Sie ursprungsübergreifende XHRs zu den API-Endpunkten des Anbieters erstellen möchten, müssen Sie die entsprechenden Muster in den Berechtigungen auf die Zulassungsliste setzen:

"permissions": [
  ...
  "https://www.website-of-provider-with-user-photos.com/photos/*"
]

Token abrufen

So rufen Sie das Token ab:

chrome.identity.launchWebAuthFlow(
  {'url': '<url-to-do-auth>', 'interactive': true},
  function(redirect_url) { /* Extract token from redirect_url */ });

Die <url-to-do-auth> ist die URL, mit der die Authentifizierung von einer Website beim Anbieter durchgeführt wird. Angenommen, Sie führen einen OAuth2-Vorgang bei einem Anbieter durch, haben Ihre Anwendung mit der Client-ID 123456789012345 registriert und möchten auf der Website des Anbieters auf die Fotos des Nutzers zugreifen: https://www.website-of-provider-with-user-photos.com/dialog/oauth?client_id=123456789012345& redirect_uri=https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb&response_type=token&scope=user_photos

Der Anbieter führt die Authentifizierung durch und zeigt dem Nutzer gegebenenfalls eine UI für die Anmeldung und/oder Genehmigung an. Sie werden dann zu https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb#authToken=<auth-token> weitergeleitet.

Chrome erfasst dies und ruft den Callback der App mit der vollständigen Weiterleitungs-URL auf. Die Anwendung sollte das Token aus der URL extrahieren.

Interaktiver und Lautlos-Modus

Beim Aufrufen von launchWebAuthFlow können Sie ein Flag ('interactive': true im Beispiel oben) übergeben, das angibt, ob die API im interaktiven Modus aufgerufen werden soll oder nicht (im Lautlos-Modus). Wenn Sie die API im interaktiven Modus aufrufen, wird dem Nutzer gegebenenfalls die Benutzeroberfläche angezeigt, um das Token abzurufen (Anmelde- und/oder Genehmigungs-UI oder in diesem Fall eine anbieterspezifische UI).

Wenn Sie die API im Lautlos-Modus aufrufen, gibt die API nur dann ein Token zurück, wenn der Anbieter ein Token bereitstellen kann, ohne eine Benutzeroberfläche anzuzeigen. Dies ist nützlich, wenn eine App den Ablauf z. B. beim Start der Anwendung ausführt, oder im Allgemeinen in Fällen, in denen keine Nutzergeste beteiligt ist.

Wir empfehlen, den Lautlos-Modus zu verwenden, wenn keine Nutzergeste erforderlich ist, und den interaktiven Modus, wenn eine Nutzer-Geste vorhanden ist (z. B. wenn der Nutzer auf die Anmeldeschaltfläche in Ihrer App geklickt hat). Beachten Sie, dass wir keine Gestenanforderung erzwingen.