Nutzer mit benutzerdefinierten Methoden authentifizieren

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

Zur Authentifizierung eines Nutzers muss eine Clientanwendung ein JSON-Webtoken (JWT) im Autorisierungs-Header der HTTP-Anfrage 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 Autorisierungs-Header 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 validieren kann.

So aktivieren Sie benutzerdefinierte Authentifizierung:

OpenAPI 2.0

  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: []

OpenAPI 3.x

  1. Fügen Sie der Sicherheitsdefinition in Ihrem OpenAPI-Dokument Folgendes hinzu: 
    components:
  securitySchemes:
    your_custom_auth_id:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: ""
          scopes: {}
      x-google-auth:
        issuer: "issuer of the token"
        jwksUri: "url to the public key"
        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 oder audiences ist nicht erforderlich. ESP akzeptiert alle JWTs mit dem Back-End-Dienstnamen im Format https://SERVICE_NAME im Anspruch aud. Damit zusätzliche Client-IDs auf den Back-End-Dienst zugreifen können, können Sie die zulässigen Client-IDs im Feld x-google-audiences oder audiences durch kommagetrennte Werte 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-Erweiterungen x-google-jwks_uri und jwksUri definiert werden:

  • JWK-Satz-Format Beispiel:

    OpenAPI 2.0

    x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"

    OpenAPI 3.x

    x-google-auth:
  jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  • X509. Beispiel:

    OpenAPI 2.0

    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

    OpenAPI 3.x

    x-google-auth:
  jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

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

Wenn Sie x-google-jwks_uri oder jwksUri 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 oder jwksUri 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-Erweiterungen hinzufügen. Weitere Informationen finden Sie unter OpenAPI 2.0-Erweiterungen oder OpenAPI 3.x-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 <var>TOKEN</var>" "<var>ENDPOINTS_HOST</var>/echo"

Ersetzen Sie die Variablen ENDPOINTS_HOST und TOKEN durch den Hostnamen Ihrer API bzw. das Authentifizierungstoken. 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 beim Senden der Anfrage nicht verwenden können, können Sie das Authentifizierungstoken in einen Abfrageparameter namens access_token einfügen.

curl "<var>ENDPOINTS_HOST</var>/echo?access_token=<var>TOKEN</var>"

Authentifizierte Ergebnisse in Ihrer API empfangen

Der ESP leitet in der Regel alle empfangenen Header weiter. Der ESP überschreibt aber möglicherweise den ursprünglichen Authorization-Header, wenn die Back-End-Adresse in der OpenAPI-Spezifikation durch x-google-backend oder in der gRPC-Dienstkonfiguration mit BackendRule angegeben wird.

Der ESP sendet das Authentifizierungsergebnis in 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, in den 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 ESP verwendet das JSON-Objekt andere Feldnamen und die ursprüngliche JWT-Nutzlast wird im Feld claims platziert. Weitere Informationen zum Format finden Sie unter JWTs im Back-End-Dienst verarbeiten.

Nächste Schritte