Nutzerauthentifizierung

Webauthentifizierungsprotokolle nutzen HTTP-Funktionen, aber Chrome-Apps werden im App-Container 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: getAuthToken für Nutzer, die in ihrem Google-Konto angemeldet sind, und launchWebAuthFlow für Nutzer, die in einem Nicht-Google-Konto angemeldet sind. Wenn Ihre Anwendung einen eigenen Server zur Authentifizierung von Nutzern verwendet, müssen Sie den zweiten Server verwenden.

Funktionsweise

Chrome Apps-Nutzer 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.

Apps, die die Authentifizierung über Identitätsanbieter von Drittanbietern ausführen möchten, müssen launchWebAuthFlow aufrufen. Bei dieser Methode werden die Anbieterseiten in einem Browser-Pop-up angezeigt und Weiterleitungen zu den jeweiligen URL-Mustern erfasst. Die Weiterleitungs-URLs werden an die App übergeben und die App extrahiert das Token aus der URL.

Google-Kontoauthentifizierung

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

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

Berechtigungen hinzufügen und App hochladen

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

"permissions": [
  "identity"
]

Schlüssel in das Manifest kopieren

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

Damit die App-ID konstant bleibt, müssen Sie den Schlüssel in der installierten manifest.json in Ihr Quellmanifest kopieren. Das ist nicht die eleganteste Aufgabe, aber so gehts:

  1. Rufen Sie Ihr Nutzerdatenverzeichnis auf. Beispiel für macOS: ~/Library/Application\ Support/Google/Chrome/Default/Extensions
  2. Listen Sie die installierten Apps und Erweiterungen auf und gleichen Sie die App-ID auf der Seite „Apps und Erweiterungen verwalten“ mit derselben ID hier ab.
  3. Rufe das Verzeichnis der installierten Apps auf. Dies ist eine Version in der App-ID. Öffnen Sie die installierte manifest.json. Mit „pico“ können Sie die Datei schnell öffnen.
  4. Kopieren Sie den „Schlüssel“ aus dem installierten manifest.json und fügen Sie ihn in die Quellmanifestdatei Ihrer Anwendung ein.

OAuth2-Client-ID abrufen

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

  1. Melden Sie sich mit demselben Google-Konto in der Google APIs Console an, mit dem Sie Ihre App in den Chrome Web Store hochgeladen haben.
  2. Erstellen Sie ein neues Projekt, indem Sie das Drop-down-Menü oben links maximieren und den Menüpunkt Erstellen… auswählen.
  3. Wechseln Sie nach dem Erstellen und Benennen zum Navigationsmenüpunkt „Dienste“ und aktivieren Sie alle Google-Dienste, die Ihre App benötigt.
  4. Gehen Sie zum Navigationsmenü "API-Zugriff" und klicken Sie auf die blaue Schaltfläche OAuth 2.0-Client-ID erstellen....
  5. Geben Sie die erforderlichen Markeninformationen ein und wählen Sie als Typ Installierte App aus.
  6. Wählen Sie Chrome-Anwendung aus und geben Sie die Anwendungs-ID ein (diese ID wird auch auf der Seite „Apps und Erweiterungen verwalten“ angezeigt).

Manifest mit OAuth2-Client-ID und Gültigkeitsbereichen aktualisieren

Sie müssen Ihr Manifest so aktualisieren, dass es die Client-ID und die Bereiche enthält. Hier sehen Sie das Beispiel "oauth2" für das gdrive-Beispiel:

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

Zugriffstokens abrufen

Sie können jetzt das Authentifizierungstoken abrufen, indem Sie identity.getAuthToken aufrufen.

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

Nutzerinteraktion

Beim Aufrufen von getAuthToken können Sie ein Flag ('interactive': true im Beispiel oben) übergeben, um anzugeben, ob die API im interaktiven oder im stillen Modus aufgerufen werden soll. Wenn Sie die API im interaktiven Modus aufrufen, wird dem Nutzer bei Bedarf eine Anmelde- und/oder Genehmigungs-UI angezeigt, wie im folgenden Screenshot dargestellt:

Screenshot der Benutzeroberfläche, wenn eine App die Identity API verwendet, um ein Google-Konto zu authentifizieren

Wenn Sie die API im Modus „Silent“ aufrufen, gibt die API nur dann ein Token zurück, wenn es möglich ist, ein Token zu generieren, ohne eine Benutzeroberfläche anzuzeigen. Das ist beispielsweise nützlich, wenn eine App den Ablauf beim Start der App ausführt, oder allgemein in Fällen, in denen keine Nutzergeste erforderlich ist.

Als Best Practice empfehlen wir, den Lautlos-Modus zu verwenden, wenn keine Nutzergeste beteiligt ist, und den interaktiven Modus zu verwenden, wenn eine Nutzergeste verwendet wird (z. B. wenn der Nutzer auf die Anmeldeschaltfläche in deiner App geklickt hat). Wir setzen keine Gesten voraus.

Caching

Chrome verfügt über einen speicherinternen Cache mit Zugriffstokens, sodass du jederzeit getAuthToken aufrufen kannst, wenn du ein Token verwenden möchtest. Der Ablauf des Tokens wird automatisch vom Cache verwaltet.

Den aktuellen Status des Token-Caches findest du unter chrome://identity-internals.

In einigen Fällen, z. B. wenn der Nutzer sein Passwort ändert, funktionieren nicht abgelaufene Zugriffstokens nicht mehr. API-Aufrufe mit dem Token werden dann mit dem HTTP-Statuscode 401 zurückgegeben. Wenn du feststellst, dass dies der Fall ist, kannst du das ungültige Token aus dem Chrome-Cache entfernen, indem du identity.removeCachedAuthToken aufrufst.

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

Authentifizierung von Drittanbieterkonten

Führen Sie dazu die folgenden drei Schritte aus:

  1. Registrieren Sie sich beim Anbieter.
  2. Fügen Sie Berechtigungen für Anbieterressourcen hinzu, auf die Ihre App zugreift.
  3. Rufe das Authentifizierungstoken ab.

Beim Anbieter registrieren

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

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

Berechtigungen für den Anbieter hinzufügen

Wenn Sie XHRs von unterschiedlichen Ursprüngen an die API-Endpunkte des Anbieters senden 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, über die sich der Anbieter von einer Website authentifizieren soll. Angenommen, Sie führen einen OAuth2-Ablauf mit einem Anbieter durch und haben Ihre App mit der Client-ID 123456789012345 registriert. Sie möchten auf die Fotos der Nutzer auf der Website des Anbieters 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 die Anmelde- und/oder Genehmigungs-UI an. Sie werden dann zu https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb#authToken=<auth-token> weitergeleitet.

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

Interaktiver und lautloser Modus

Beim Aufrufen von launchWebAuthFlow können Sie ein Flag ('interactive': true im Beispiel oben) übergeben, um anzugeben, ob die API im interaktiven Modus (auch als „Lautlosmodus“ bezeichnet) aufgerufen werden soll oder nicht. Wenn Sie die API im interaktiven Modus aufrufen, wird dem Nutzer gegebenenfalls eine Benutzeroberfläche angezeigt, über die er das Token abrufen kann (Anmelde- und/oder Genehmigungsoberfläche oder eine beliebige andere anbieterspezifische Oberfläche).

Wenn Sie die API im Modus „Lautlos“ aufrufen, gibt die API nur dann ein Token zurück, wenn der Anbieter ein Token bereitstellen kann, ohne eine Benutzeroberfläche anzuzeigen. Das ist beispielsweise nützlich, wenn eine App den Ablauf beim Starten der App ausführt, oder allgemein in Fällen, in denen keine Nutzergeste erforderlich ist.

Wir empfehlen, den Modus „Lautlos“ zu verwenden, wenn keine Nutzergeste erfolgt, und den interaktiven Modus, wenn eine Nutzergeste erfolgt (z. B. wenn der Nutzer in Ihrer App auf die Schaltfläche „Anmelden“ geklickt hat). Die Gestenfunktion ist nicht zwingend erforderlich.