Authentifizierte Anfrage von einer JavaScript-Anwendung aus senden

Auf dieser Seite wird beschrieben, wie Sie von einer lokal ausgeführten JavaScript-Anwendung aus eine authentifizierte Anfrage an eine REST API senden, die mit Cloud Endpoints Frameworks erstellt wurde. In der JavaScript-Anwendung wird demonstriert, wie Sie Google Log-in verwenden und in der Anfrage ein Google-ID-Token zur Authentifizierung des Nutzers senden. Wenn die JavaScript-Anwendung die Anfrage sendet, authentifiziert Endpoints Frameworks diesen Nutzer und übergibt die Anfrage dann an den Back-End-Code, der in der App Engine-Standardumgebung ausgeführt wird.

Vorbereitung

So führen Sie die JavaScript-Beispielanwendung aus:

  • Suchen Sie die Google Cloud-Projekt-ID, die Sie für die Beispiel-API erstellt haben, da Sie sie zum JavaScript-Beispielcode hinzufügen müssen. Hilfe bei der Suche nach der Projekt-ID erhalten Sie unter Projekte auflisten.

  • Sie benötigen auf Ihrem lokalen Computer einen Webserver, um die Beispieldatei index.html bereitzustellen, die den JavaScript-Code enthält. Auf dieser Seite werden die Schritte zum Ausführen eines einfachen Servers mit Python beschrieben. Sie können aber jeden Webserver verwenden.

JavaScript-Clientcodebeispiel herunterladen

  1. Klonen Sie den Beispielcode auf Ihren lokalen Rechner:

    git clone https://github.com/GoogleCloudPlatform/web-docs-samples

  2. Wechseln Sie in das Verzeichnis, das den JavaScript-Client enthält:

    cd web-docs-samples/endpoints-frameworks

OAuth 2.0-Client-IDs erstellen

Damit die Beispielanwendung authentifiziert werden kann, müssen Sie im JavaScript-Beispielcode und im Back-End-Code eine OAuth 2.0-Client-ID konfigurieren. Die JavaScript-Anwendung ruft mithilfe der Client-ID ein Google-ID-Token vom OAuth 2.0-Server von Google ab und sendet dieses in der Anfrage. Endpoints Frameworks verwendet die Client-ID, um das ID-Token zu authentifizieren, das die JavaScript-Anwendung in der Anfrage gesendet hat.

So erstellen Sie eine Client-ID:

  1. Rufen Sie in der Google Cloud Console die Seite „Anmeldedaten“ auf.

    Zur Seite „Domainbestätigung“

  2. Wählen Sie aus der Projektliste das Projekt aus, das Sie für die Beispiel-API erstellt haben.

  3. Klicken Sie auf die Schaltfläche Anmeldedaten erstellen und wählen Sie OAuth-Client-ID aus. Wenn Sie zum ersten Mal eine Client-ID in diesem Projekt erstellen, folgen Sie den Unterschritten, um einen Produktnamen auf dem Zustimmungsbildschirm festzulegen. Andernfalls können Sie mit dem nächsten Schritt fortfahren.

    1. Klicken Sie auf die Schaltfläche Zustimmungsbildschirm konfigurieren.
    2. Geben Sie im Feld Name der Anwendung einen Namen ein.
    3. Klicken Sie auf Speichern.

  4. Wählen Sie unter Anwendungstyp die Option Webanwendung aus.

  5. Geben Sie im Feld Autorisierte JavaScript-Quellen Folgendes ein:

    http://localhost:8080

  6. Klicken Sie auf Erstellen.

  7. Kopiere deine Client-ID. Ihre vollständige Client-ID ähnelt der folgenden, ist aber eindeutig für die Webanwendung in Ihrem Projekt.

    271473851874-mtll5dk2vultovbtilt31hakqbinpuvd.apps.googleusercontent.com

Weitere Informationen zum Erstellen von Client-IDs finden Sie unter OAuth 2.0 einrichten.

Back-End-Code konfigurieren und noch einmal bereitstellen

Damit Cloud Endpoints Frameworks die von der JavaScript-Anwendung gesendete Anfrage authentifizieren kann, müssen Sie die soeben erstellte Client-ID in den Beispielcode einfügen und das aktualisierte OpenAPI-Dokument sowie den Back-End-Code der Anwendung noch einmal bereitstellen.

Bei den folgenden Arbeitsschritten wird davon ausgegangen, dass Sie die Beispiel-API aus der Anleitung Erste Schritte mit Endpoints Frameworks in App Engine bereits bereitgestellt haben. Prüfen Sie, ob Sie eine erfolgreiche Antwort erhalten, wenn Sie eine Anfrage an die API senden wie unter Anfrage an die API senden beschrieben. Beginnen Sie erst dann mit der nachfolgenden Anleitung.

So konfigurieren Sie den Back-End-Code und stellen ihn noch einmal bereit:

  1. Wechseln Sie innerhalb des Verzeichnisses, in das Sie das Repository java-docs-samples geklont haben, in das Verzeichnis, das das JavaScript-Beispiel enthält:

    cd YOUR_WORKING_DIRECTORY/java-docs-samples/appengine-java8/endpoints-v2-backend

  2. Öffnen Sie die Datei src/main/java/com/example/echo/Echo.java in einem Texteditor.

  3. Ersetzen Sie in der Annotation @ApiMethod der Methode getUserEmail die YOUR_OAUTH_CLIENT_ID in den Attributen audiences und clientIds durch die Client-ID, die Sie erstellt haben.

    appengine-java8/endpoints-v2-backend/src/main/java/com/example/echo/Echo.java 
    @ApiMethod(
    httpMethod = ApiMethod.HttpMethod.GET,
    authenticators = {EspAuthenticator.class},
    audiences = {"YOUR_OAUTH_CLIENT_ID"},
    clientIds = {"YOUR_OAUTH_CLIENT_ID"}
)
public Email getUserEmail(User user) throws UnauthorizedException {
  if (user == null) {
    throw new UnauthorizedException("Invalid credentials");
  }

  Email response = new Email();
  response.setEmail(user.getEmail());
  return response;
}

  4. Speichern Sie die Datei Echo.java.

  5. Bereinigen Sie Ihr Projekt und erstellen Sie dann die API:

    Maven

    mvn clean package

    Gradle

          gradle clean
      gradle build

  6. Erstellen Sie das OpenAPI-Dokument openapi.json noch einmal, damit es die Client-ID enthält.

    Maven

    mvn endpoints-framework:openApiDocs

    Gradle

    gradle endpointsOpenApiDocs

  7. Achten Sie darauf, dass die Google Cloud-Befehlszeile (gcloud) Zugriff auf Ihre Daten und Dienste in Google Cloud hat:

    gcloud auth login

  8. Das Standardprojekt für die Google Cloud-Befehlszeile festlegen. Ersetzen Sie dabei YOUR_PROJECT_ID durch die ID des Projekts, das Sie für die Beispiel-API erstellt haben:

    gcloud config set project YOUR_PROJECT_ID

  9. Stellen Sie das aktualisierte OpenAPI-Dokument bereit:

    gcloud endpoints services deploy target/openapi-docs/openapi.json

  10. Warten Sie, bis der Befehl abgeschlossen ist, und stellen Sie dann die Anwendung noch einmal bereit:

    Maven

    mvn appengine:deploy

    Gradle

    gradle appengineDeploy

JavaScript-Code konfigurieren

So konfigurieren Sie den JavaScript-Code:

  1. Öffnen Sie die Datei main.js im Verzeichnis web-docs-samples/endpoints-frameworks in einem Texteditor.

  2. Ersetzen Sie in der Funktion initGoogleAuth YOUR_CLIENT_ID durch die von Ihnen erstellte Client-ID.

    endpoints-frameworks/main.js 
    function initGoogleAuth (clientId = 'YOUR_CLIENT_ID') {
  gapi.auth2.init({
    client_id: clientId,
    scope: 'https://www.googleapis.com/auth/userinfo.email'
  }).then(() => {
    document.getElementById('sign-in-btn').disabled = false;
  }).catch(err => {
    console.log(err);
  });
}

  3. Ersetzen Sie in der Funktion sendSampleRequest YOUR_PROJECT_ID durch die ID des Projekts, das Sie für die Beispiel API erstellt haben:

    endpoints-frameworks/main.js 
    function sendSampleRequest (projectId = 'YOUR_PROJECT_ID') {
  var user = gapi.auth2.getAuthInstance().currentUser.get();
  var idToken = user.getAuthResponse().id_token;
  var endpoint = `https://${projectId}.appspot.com/_ah/api/echo/v1/email`;
  var xhr = new XMLHttpRequest();
  xhr.open('GET', endpoint + '?access_token=' + encodeURIComponent(idToken));
  xhr.onreadystatechange = function () {
    if (this.readyState === XMLHttpRequest.DONE && this.status === 200) {
      window.alert(xhr.responseText);
    }
  };
  xhr.send();
}

Authentifizierte Anfrage senden

  1. Wechseln Sie innerhalb des Verzeichnisses, in das Sie das Repository web-docs-samples geklont haben, in das Verzeichnis, das das JavaScript-Beispiel enthält:

    cd YOUR_WORKING_DIRECTORY/web-docs-samples/endpoints-frameworks

  2. Starten Sie Ihren Webserver für die Bereitstellung von index.html auf Port 8080. Im folgenden Beispiel wird der einfache Server von Python verwendet:

    python -m http.server 8080

  3. Geben Sie in Ihrem Browser localhost:8080 ein.

    Die JavaScript-Anwendung zeigt zwei Schaltflächen an:

    Anmelden

  4. Klicken Sie auf Sign In (Anmelden). Die Seite Über Google anmelden wird angezeigt.

  5. Klicken Sie nach der Anmeldung auf die Schaltfläche Send sample request (Beispielanfrage senden). Beim ersten Senden einer Anfrage kann es zu einer Verzögerung von etwa 20 Sekunden kommen, da App Engine gestartet wird. Endpoints Frameworks fängt die Anfragen ab und verwendet die im Back-End-Code konfigurierte Client-ID, um die Anfrage zu authentifizieren. Wenn die Authentifizierung erfolgreich ist, geschieht Folgendes:

    1. Endpoints Frameworks übergibt die Anfrage an das in App Engine ausgeführte Beispiel-Back-End.

    2. Die Methode getUserEmail aus dem Back-End-Code gibt die E-Mail-Adresse des Nutzerkontos zurück, das Sie bei der Anmeldung verwendet haben.

    3. Der JavaScript-Client zeigt ein Dialogfeld mit der E-Mail-Adresse an.

Überblick über den JavaScript-Client

Der JavaScript-Client verwendet Google Log-in zum Verwalten des OAuth 2.0-Ablaufs. In diesem Abschnitt erhalten Sie eine kurze Übersicht über den Code des JavaScript-Clients.

Auth einrichten

  1. Laden Sie die Plattformbibliothek der Google APIs, um das gapi-Objekt zu erstellen:

    endpoints-frameworks/index.html 
      <script src="https://apis.google.com/js/platform.js?onload=loadAuthClient" async defer></script>
</head>

  2. Laden Sie danach die Bibliothek auth2:

    endpoints-frameworks/main.js 
    function loadAuthClient () {
  gapi.load('auth2', initGoogleAuth);
}

  3. Initialisieren Sie das GoogleAuth-Objekt.

    endpoints-frameworks/main.js 
    function initGoogleAuth (clientId = 'YOUR_CLIENT_ID') {
  gapi.auth2.init({
    client_id: clientId,
    scope: 'https://www.googleapis.com/auth/userinfo.email'
  }).then(() => {
    document.getElementById('sign-in-btn').disabled = false;
  }).catch(err => {
    console.log(err);
  });
}

Beim Initialisieren des GoogleAuth-Objekts konfigurieren Sie dieses mit Ihrer OAuth 2.0-Client-ID und den zusätzlichen Optionen, die Sie angeben möchten. Es ist üblich, den Zugriffsbereich anzugeben. Mithilfe von Bereichen wird ermöglicht, dass eine Anwendung nur für benötigte Ressourcen den Zugriff anfordern kann, während Nutzer wiederum steuern können, wie viel Zugriff sie der Anwendung gewähren. Bevor Sie mit der Implementierung der OAuth 2.0-Autorisierung beginnen, sollten Sie also die Bereiche identifizieren, für die Ihre Anwendung eine Zugriffsberechtigung benötigt. Im obigen Beispiel wird der Zugriff auf den Bereich https://www.googleapis.com/auth/userinfo.email angefordert, wodurch das Aufrufen der E-Mail-Adresse des Nutzers ermöglicht wird.

Anmelden

Nachdem Sie das GoogleAuth-Objekt initialisiert haben, können Sie den Nutzer zum Anmelden auffordern. Dazu rufen Sie die signIn-Funktion des GoogleAuth-Objekts auf:

endpoints-frameworks/main.js 
function signIn () {
  gapi.auth2.getAuthInstance().signIn().then(() => {
    document.getElementById('sign-in-btn').hidden = true;
    document.getElementById('sign-out-btn').hidden = false;
    document.getElementById('send-request-btn').disabled = false;
  }).catch(err => {
    console.log(err);
  });
}

Anfrage mit dem ID-Token stellen

Sobald der Nutzer angemeldet ist, senden Sie eine Anfrage mit einem Autorisierungsheader, der das ID-Token des Nutzers enthält:

endpoints-frameworks/main.js 
function sendSampleRequest (projectId = 'YOUR_PROJECT_ID') {
  var user = gapi.auth2.getAuthInstance().currentUser.get();
  var idToken = user.getAuthResponse().id_token;
  var endpoint = `https://${projectId}.appspot.com/_ah/api/echo/v1/email`;
  var xhr = new XMLHttpRequest();
  xhr.open('GET', endpoint + '?access_token=' + encodeURIComponent(idToken));
  xhr.onreadystatechange = function () {
    if (this.readyState === XMLHttpRequest.DONE && this.status === 200) {
      window.alert(xhr.responseText);
    }
  };
  xhr.send();
}

Weitere Informationen