Users API für gebündelte Legacy-Dienste

Die Users API ermöglicht einer Anwendung Folgendes:

• Ermitteln, ob der aktuelle Nutzer angemeldet ist
• Nutzer zur Anmeldung an die entsprechende Anmeldeseite weiterleiten
• Anwendungsnutzer zur Erstellung eines neuen Google-Kontos auffordern, sofern sie noch keines haben

Diese API wird für Laufzeiten der ersten Generation unterstützt und kann beim Upgrade auf entsprechende Laufzeiten der zweiten Generation verwendet werden. Wenn Sie auf die App Engine Java 11/17-Laufzeit aktualisieren möchten, erfahren Sie in der Migrationsanleitung mehr über Ihre Migrationsoptionen für gebündelte Legacy-Dienste.

Wenn ein Nutzer angemeldet ist, kann die Anwendung auf seine E-Mail-Adresse zugreifen. Die Anwendung kann auch erkennen, ob der aktuelle Nutzer ein Administrator ist. Dadurch wird die Implementierung von nur für Administratoren vorgesehenen Bereichen der Anwendung vereinfacht.

Hinweis: Ein Administrator ist ein Nutzer, der die Rolle „Betrachter“, „Bearbeiter“, „Inhaber“ oder „App Engine-Administrator“ hat. Weitere Informationen zum Festlegen von Nutzerrollen finden Sie unter Rollen mit Zugriffsberechtigung für App Engine.

Nutzerauthentifizierung in Java 8

Im folgenden Beispiel wird ein Nutzer, der sich bei der Anwendung angemeldet hat, mit einer personalisierten Nachricht und einem Link für die Abmeldung begrüßt. Wenn der Nutzer nicht angemeldet ist, zeigt die Anwendung einen Link zur Anmeldeseite für Google-Konten an.

In der Standard Servlet API können Sie mit der Methode getUserPrincipal() des Anfrageobjekts testen, ob ein Nutzer angemeldet ist, und die E-Mail-Adresse des Nutzers abrufen. Zum Generieren von An- und Abmelde-URLs können Sie die User Service API verwenden.

package com.example.appengine.users;

import com.google.appengine.api.users.UserService;
import com.google.appengine.api.users.UserServiceFactory;
import java.io.IOException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

// With @WebServlet annotation the webapp/WEB-INF/web.xml is no longer required.
@WebServlet(
    name = "UserAPI",
    description = "UserAPI: Login / Logout with UserService",
    urlPatterns = "/userapi"
)
public class UsersServlet extends HttpServlet {

  @Override
  public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    UserService userService = UserServiceFactory.getUserService();

    String thisUrl = req.getRequestURI();

    resp.setContentType("text/html");
    if (req.getUserPrincipal() != null) {
      resp.getWriter()
          .println(
              "<p>Hello, "
                  + req.getUserPrincipal().getName()
                  + "!  You can <a href=\""
                  + userService.createLogoutURL(thisUrl)
                  + "\">sign out</a>.</p>");
    } else {
      resp.getWriter()
          .println(
              "<p>Please <a href=\"" + userService.createLoginURL(thisUrl) + "\">sign in</a>.</p>");
    }
  }
}

Die Informationen des aktuellen Nutzers können von der User Service API als "User"-Objekt zurückgegeben werden. "User"-Objekte können zwar als Attributwert im Datenspeicher gespeichert werden, es wird jedoch dringend empfohlen, dies zu vermeiden, weil sie auch die E-Mail-Adresse und die eindeutige ID des Nutzers enthalten. Wenn ein Nutzer seine E-Mail-Adresse ändert und Sie den alten gespeicherten Wert User mit dem neuen Wert User vergleichen, stimmen diese nicht überein. Stattdessen sollten Sie den Nutzer-ID-Wert von User als stabile eindeutige Kennung des Nutzers verwenden.

Anmeldung und Administratorzugriff mit web.xml durchsetzen

Wenn es Seiten gibt, auf die nur angemeldete Nutzer Zugriff haben sollen, können Sie für diese Seiten eine Sicherheitsbeschränkung im Deployment-Deskriptor (die Datei web.xml) einrichten. Sobald ein Nutzer eine URL mit einer Sicherheitsbeschränkung aufruft und nicht angemeldet ist, leitet App Engine den Nutzer automatisch zur Anmeldeseite weiter (für Google-Konten oder die Google Workspace-Authentifizierung) und nach der erfolgreichen Anmeldung oder Registrierung wieder zur URL zurück.

Bei einer Sicherheitsbeschränkung kann es auch erforderlich sein, dass der Nutzer ein registrierter Administrator für die Anwendung ist. Das heißt, der Nutzer muss die Rolle „Betrachter“, „Bearbeiter“, „Inhaber“ oder „App Engine-Administrator“ haben. So können einfach Websitebereiche erstellt werden, die nur für Administratoren zugänglich sind, ohne dass ein separater Autorisierungsmechanismus implementiert werden muss.

Weitere Informationen zum Festlegen von Sicherheitsbeschränkungen für URLs finden Sie unter Deployment-Deskriptor: Sicherheit und Authentifizierung für web.xml.

Authentifizierungsoptionen

Nutzer können von der Anwendung über eine der folgenden Optionen authentifiziert werden:

• Google-Konto
• Konto in Ihrer Google Workspace-Domain

Authentifizierungsoption auswählen

Nachdem Sie die Anwendung erstellt haben, können Sie die gewünschte Authentifizierungsoption auswählen. Standardmäßig verwendet Ihre Anwendung für die Authentifizierung Google-Konten. Wenn Sie eine andere Option auswählen möchten, z. B. die Google Workspace-Domain, rufen Sie in der Google Cloud Console die Seite Einstellungen Ihres Projekts auf und klicken Sie auf Bearbeiten. Wählen Sie im Drop-down-Menü Google-Authentifizierung den gewünschten Authentifizierungstyp aus und klicken Sie dann auf Speichern.

An- und Abmelden

Eine Anwendung kann erkennen, ob sich ein Nutzer mit der für die Anwendung ausgewählten Authentifizierungsoption angemeldet hat. Wenn der Nutzer nicht angemeldet ist, kann die Anwendung den Nutzer zur Seite für Google-Konten weiterleiten, wo er sich anmelden oder ein neues Google-Konto erstellen kann. Die Anwendung ruft die URL für die Anmeldeseite ab, indem sie eine Methode der Users API aufruft. Die Anwendung kann diese URL als Link anzeigen oder eine HTTP-Weiterleitung zur URL ausgeben, wenn Nutzer eine Seite besuchen, für die eine Authentifizierung erforderlich ist.

Verwendet Ihre Anwendung Google-Konten oder Google Workspace für die Authentifizierung, wird der Name der Anwendung auf der Anmeldeseite angezeigt, wenn sich der Nutzer bei dieser Anwendung anmeldet. Der angezeigte Name ist der Anwendungsname, den Sie bei der Registrierung der Anwendung angegeben haben. Sie können diesen Namen in der Google Cloud Console auf der Seite Anmeldedaten im Feld Anwendungsname ändern.

Sobald Nutzer sich angemeldet oder ein Google-Konto erstellt haben, werden sie zurück zur Anwendung geleitet. Die Anwendung stellt die Weiterleitungs-URL für die Methode bereit, mit der die Anmelde-URL generiert wird.

Die Users API verfügt auch über eine Methode für die Generierung einer URL zur Abmeldung von der Anwendung. Mit der Abmelde-URL wird die Authentifizierung von Nutzern für die Anwendung rückgängig gemacht und sie werden zur Anwendungs-URL weitergeleitet, ohne dass etwas angezeigt wird.

Nutzer werden erst dann bei der Anwendung angemeldet, wenn sie von der Anwendung dazu aufgefordert werden und die E-Mail-Adresse sowie das Passwort ihres Kontos eingeben. Das gilt auch dann, wenn sich Nutzer mit ihrem Google-Konto bei anderen Anwendungen angemeldet haben.

Kontoinformationen abrufen

Wenn ein Nutzer bei einer Anwendung angemeldet ist, kann diese bei jeder Nutzeranfrage an die Anwendung auf die E-Mail-Adresse des Kontos zugreifen. Die Anwendung kann auch auf eine Nutzer-ID zugreifen, um den Nutzer auch dann eindeutig zu identifizieren, wenn sich die E-Mail-Adresse seines Kontos geändert hat.

Die Anwendung kann auch erkennen, ob der aktuelle Nutzer ein Administrator der Anwendung ist. Ein Administrator ist ein Nutzer, der die Rolle „Betrachter“, „Bearbeiter“, „Inhaber“ oder „App Engine-Administrator“ hat. Sie können dieses Feature zum Erstellen administrativer Features für die Anwendung verwenden, auch wenn Sie keine anderen Nutzer authentifizieren. Mit den APIs für Go, Java, PHP und Python können Sie URLs „nur für Administratoren“ konfigurieren.

Hinweis: Jeder Nutzer hat bei allen App Engine-Anwendungen dieselbe Nutzer-ID. Wenn die Anwendung die Nutzer-ID in öffentlichen Daten verwendet und sie etwa in einen URL-Parameter einfügt, sollten Sie einen Hash-Algorithmus mit zusätzlichem Salt-Wert verwenden, um die ID zu tarnen. Durch die Offenlegung einer unverschlüsselten ID könnten Dritte die Aktivitäten eines Nutzers in einer Anwendung mit Aktivitäten in einer anderen verknüpfen oder den Nutzer dazu bringen, sich bei einer anderen Anwendung anzumelden, und so seine E-Mail-Adresse erhalten.

Nutzer und der Datenspeicher

Die Informationen des aktuellen Nutzers können von der User Service API als "User"-Objekt zurückgegeben werden. "User"-Objekte können zwar als Attributwert im Datenspeicher gespeichert werden, es wird jedoch dringend empfohlen, dies zu vermeiden, weil sie auch die E-Mail-Adresse und die eindeutige ID des Nutzers enthalten. Wenn ein Nutzer seine E-Mail-Adresse ändert und Sie den alten gespeicherten Wert User mit dem neuen Wert User vergleichen, stimmen diese nicht überein. Stattdessen sollten Sie den Nutzer-ID-Wert von User als stabile eindeutige Kennung des Nutzers verwenden.

Google-Konten und der Entwicklungsserver

Der Entwicklungsserver simuliert das Google-Kontensystem mit einem unechten Anmeldebildschirm. Wenn die Anwendung die Users API aufruft, um die URL für den Anmeldebildschirm zu erhalten, gibt die API eine spezielle URL für den Entwicklungsserver zurück, mit der eine E-Mail-Adresse, jedoch kein Passwort angefordert wird. Sie können bei dieser Aufforderung eine beliebige E-Mail-Adresse eingeben. Die Anwendung verhält sich so, als seien Sie mit einem Konto angemeldet, zu dem diese Adresse gehört.

Der fiktive Anmeldebildschirm enthält auch ein Kästchen, mit dem festgelegt werden kann, dass das fiktive Konto ein Administratorkonto ist, also die Rolle „Betrachter“, „Bearbeiter“, „Inhaber“ oder „App Engine-Administrator“ hat. Wenn Sie dieses Kästchen anklicken, verhält sich die Anwendung so, als seien Sie mit einem Administratorkonto angemeldet.

Entsprechend gibt die Users API eine Abmelde-URL zurück, mit der die unechte Anmeldung abgebrochen wird.