Nutzer mit benutzerdefinierten Methoden authentifizieren

Auf dieser Seite wird gezeigt, wie Sie die Nutzerauthentifizierung in Cloud Endpoints unterstützen.

Um einen Nutzer zu authentifizieren, muss eine Clientanwendung im Autorisierungsheader der HTTP-Anfrage ein JSON-Webtoken (JWT) an Ihre Back-End-API senden. Der Extensible Service Proxy (ESP) validiert das Token für Ihre API, sodass Sie der API keinen Code zur Verarbeitung der Authentifizierung hinzufügen müssen. Sie müssen Ihr OpenAPI-Dokument jedoch so konfigurieren, dass es die ausgewählten Authentifizierungsmethoden unterstützt.

Der ESP prüft ein JSON-Webtoken (JWT) effizient mithilfe der öffentlichen Schlüssel des JWT-Ausstellers. Dabei speichert der ESP die öffentlichen Schlüssel 5 Minuten lang im Cache. Darüber hinaus speichert der ESP validierte JWTs 5 Minuten lang oder bis zum Ablauf des JWT, je nachdem, was zuerst eintritt.

Hinweise

  • Fügen Sie Ihrer Clientanwendung Authentifizierungscode hinzu. Weitere Informationen hierzu finden Sie in der Dokumentation des Authentifizierungsanbieters.

  • Wenn Ihre Clientanwendung eine HTTP-Anfrage sendet, muss der Autorisierungsheader in der Anfrage die folgenden JWT-Anforderungen enthalten:
    • iss (issuer)
    • sub (subject)
    • aud (audience)
    • iat (issued at)
    • exp (expiration time)

ESP für die Clientauthentifizierung konfigurieren

Das OpenAPI-Dokument muss ein Objekt für Sicherheitsanforderungen und ein Objekt für Sicherheitsdefinitionen enthalten, damit der ESP die Anforderungen im signierten JWT prüfen kann.

So aktivieren Sie benutzerdefinierte Authentifizierung:

  1. Fügen Sie der Sicherheitsdefinition in Ihrem OpenAPI-Dokument Folgendes hinzu:

     securityDefinitions:
       your_custom_auth_id:
         authorizationUrl: ""
         flow: "implicit"
         type: "oauth2"
         # The value below should be unique
         x-google-issuer: "issuer of the token"
         x-google-jwks_uri: "url to the public key"
         # Optional. Replace YOUR-CLIENT-ID with your client ID
         x-google-audiences: "YOUR-CLIENT-ID"
    
  2. Fügen Sie den Abschnitt "security" entweder für die gesamte API auf API-Ebene oder für eine bestimmte Methode auf Methodenebene hinzu.

     security:
       - your_custom_auth_id: []
    

Sie können mehrere Sicherheitsdefinitionen im OpenAPI-Dokument angeben, allerdings muss jede Definition einen anderen Aussteller haben. Wenn Sie den Abschnitt "security" sowohl auf der API-Ebene als auch auf der Methodenebene verwenden, werden die Einstellungen auf der API-Ebene durch die Einstellungen auf der Methodenebene überschrieben.

Das Feld x-google-audiences ist nicht erforderlich. ESP akzeptiert alle JWTs mit dem Back-End-Dienstnamen in Form von https://SERVICE_NAME in der aud-Anforderung. Damit zusätzliche Client-IDs auf den Back-End-Dienst zugreifen können, können Sie die zulässigen Client-IDs mithilfe von kommagetrennten Werten im Feld x-google-audiences angeben. Der ESP akzeptiert dann die JWTs mit einer der angegebenen Client-IDs im Anspruch aud.

Der ESP unterstützt zwei asymmetrische öffentliche Schlüsselformate, die durch die OpenAPI-Erweiterung x-google-jwks_uri definiert werden:

  • JWK-Satz-Format Beispiel:
    x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
    
  • X509. Beispiel:
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"
    

Wenn Sie ein symmetrisches Schlüsselformat verwenden, legen Sie x-google-jwks_uri auf den URI einer Datei fest, die den base64url-codierten Schlüsselstring enthält.

Wenn Sie x-google-jwks_uri weglassen, folgt der ESP dem OpenID Connect Discovery-Protokoll, um den JWKS-URI für den angegebenen OpenID-Anbieter automatisch zu ermitteln. Der ESP sendet eine Anfrage an x-google-issuer/.well-known/openid-configuration, parst die JSON-Antwort und liest die JWKS-URI aus dem Feld jwks_uri der obersten Ebene.

Wenn Sie x-google-jwks_uri weglassen, führt dies zu höheren Kaltstartzeiten, da der ESP beim Start einen zusätzlichen Remote-Aufruf vornehmen muss. Daher wird empfohlen, dieses Feld nur auszulassen, wenn sich der JWKS-URI häufig ändert. Die meisten zertifizierten OpenID-Anbieter wie Google, Auth0 und Okta verfügen über stabile JWKS-URIs.

Sie können auch JWT-Standorte anpassen, indem Sie x-google-extensions hinzufügen. Weitere Informationen finden Sie unter openAPI-Erweiterungen.

Authentifizierter Aufruf an eine Endpoints API

Wenn Sie eine Anfrage mit einem Authentifizierungstoken senden, empfehlen wir aus Sicherheitsgründen, das Token in den Header Authorization:Bearer einzufügen. Beispiel:

curl -H "Authorization: Bearer ${TOKEN}" "${ENDPOINTS_HOST}/echo"

Hier sind ENDPOINTS_HOST und TOKEN Umgebungsvariablen, die den Hostnamen Ihrer API beziehungsweise das Authentifizierungstoken enthalten. Unter Authentifizierte Anfrage an eine Endpoints API senden finden Sie einen Beispielcode, der eine Anfrage mit dem Header Authorization:Bearer sendet.

Falls Sie den Header nicht verwenden können, wenn Sie die Anfrage senden, können Sie das Authentifizierungstoken in einen Abfrageparameter mit dem Namen access_token einfügen. Beispiel:

curl "${ENDPOINTS_HOST}/echo?access_token=${TOKEN}"

Authentifizierte Ergebnisse in Ihrer API empfangen

Der ESP leitet in der Regel alle empfangenen Header weiter. Allerdings wird der ursprüngliche Authorization-Header überschrieben, wenn die Back-End-Adresse durch x-google-backend in der OpenAPI-Spezifikation oder BackendRule in der gRPC-Dienstkonfiguration angegeben wird.

Der ESP sendet das Authentifizierungsergebnis im X-Endpoint-API-UserInfo an die Back-End-API. Wir empfehlen, diesen Header anstelle des ursprünglichen Authorization-Headers zu verwenden. Dieser Header ist ein String, mit dem base64url ein JSON-Objekt codiert. Das JSON-Objektformat unterscheidet sich zwischen ESPv2 und ESP. Bei ESPv2 ist das JSON-Objekt genau die ursprüngliche JWT-Nutzlast. Für den ESP verwendet das JSON-Objekt andere Feldnamen und fügt die ursprüngliche JWT-Nutzlast unter das Feld claims ein. Weitere Informationen zum Format findest du unter JWTs im Back-End-Dienst verarbeiten.

Nächste Schritte