Nutzer mit JWT authentifizieren

Auf dieser Seite wird beschrieben, wie die Nutzerauthentifizierung in API Gateway unterstützt wird.

Um einen Nutzer zu authentifizieren, muss eine Clientanwendung im Autorisierungsheader der HTTP-Anfrage ein JSON-Webtoken (JWT) an Ihre Back-End-API senden. API Gateway validiert das Token im Namen Ihrer API, sodass Sie keinen Code in die API einfügen müssen, um die Authentifizierung zu verarbeiten. Sie müssen jedoch die API-Konfiguration für Ihr Gateway so konfigurieren, dass die ausgewählten Authentifizierungsmethoden unterstützt werden.

API Gateway validiert ein JWT leistungsstark mithilfe des JSON Web Key Set (JWKS) des JWT-Ausstellers. Der Speicherort des JWKS wird im Feld x-google-jwks_uri der API-Konfiguration des Gateways angegeben. API Gateway speichert den JWKS fünf Minuten lang im Cache und aktualisiert ihn alle fünf Minuten.

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)

API Gateway für die Clientauthentifizierung konfigurieren

Die API-Konfiguration für API Gateway muss ein Objekt für Sicherheitsanforderungen und ein Objekt für Sicherheitsdefinitionen enthalten, damit die Anforderungen im signierten JWT validiert werden können.

So unterstützen Sie die JWT-Authentifizierung:

  1. Fügen Sie der Sicherheitsdefinition in Ihrer API-Konfiguration Folgendes hinzu, die dem OpenAPI 2.0-Sicherheitsschema folgt:

     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 in der API-Konfiguration mehrere Sicherheitsdefinitionen festlegen, 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. API Gateway 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 kommagetrennter Werte im Feld x-google-audiences angeben. API Gateway akzeptiert dann die JWTs mit einer der angegebenen Client-IDs in der aud-Anforderung.

Das Feld x-google-jwks_uri ist ein Pflichtfeld. API Gateway 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.

Authentifizierten Aufruf an eine API Gateway API senden

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

curl --request POST \
  --header "Authorization: Bearer ${TOKEN}" \
  "${GATEWAY_URL}/echo"

Hier sind GATEWAY_URL und TOKEN Umgebungsvariablen, die die bereitgestellte Gateway-URL bzw. das Authentifizierungstoken enthalten. Unter Authentifizierte Anfrage an eine API Gateway API stellen 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 "${GATEWAY_URL}/echo?access_token=${TOKEN}"

Authentifizierte Ergebnisse in Ihrer API empfangen

API Gateway leitet in der Regel alle empfangenen Header weiter. Der ESP überschreibt aber möglicherweise den ursprünglichen Authorization-Header, wenn die Backend-Adresse in der API-Konfiguration durch x-google-backend angegeben ist

API Gateway sendet das Authentifizierungsergebnis in X-Apigateway-Api-Userinfo an die Backend-API. Es wird empfohlen, diesen Header anstelle des ursprünglichen Authorization-Headers zu verwenden. Dieser Header ist base64url-codiert und enthält die JWT-Nutzlast.

Nächste Schritte