Nutzer mit JWT authentifizieren
Auf dieser Seite wird beschrieben, wie Sie die Nutzerauthentifizierung in API Gateway 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. API Gateway validiert das Token für Ihre API, sodass Sie der API keinen Code zur Verarbeitung der Authentifizierung hinzufügen müssen. Sie müssen die API-Konfiguration für Ihr Gateway jedoch so konfigurieren, dass sie die ausgewählten Authentifizierungsmethoden unterstützt.
API Gateway prüft ein JWT effizient mithilfe des JSON-Webschlüsselsatzes (JWKS) des JWT-Ausstellers. Der Speicherort des JWKS wird in der API-Konfiguration des Gateways angegeben. API Gateway speichert die JWKS-Datei fünf Minuten lang im Cache und aktualisiert sie alle fünf Minuten.
Hinweis
- 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)
API Gateway für die Clientauthentifizierung konfigurieren
Die API-Konfiguration für API Gateway muss einen Sicherheitsabschnitt enthalten, damit die Anforderungen im signierten JWT validiert werden können. Das Schema, mit dem die Sicherheitsmethoden definiert werden, hängt von der Version der OpenAPI-Spezifikation ab, die Sie verwenden.
So aktivieren Sie die JWT-Authentifizierung:
OpenAPI 2.0
- Fügen Sie Ihrer API-Konfiguration Folgendes hinzu:
securityDefinitions: your_custom_auth_id: authorizationUrl: "" flow: "implicit" type: "oauth2" # The issuer value should be unique x-google-issuer: "ISSUER" x-google-jwks_uri: "URL_PUBLIC_KEY" # Optional. x-google-audiences: "CLIENT_ID"
Wobei:
- ISSUER ist der Aussteller des Tokens.
- URL_PUBLIC_KEY ist die URL zum öffentlichen Schlüssel.
- CLIENT_ID ist die Client-ID.
- 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
- Fügen Sie Ihrer API-Konfiguration Folgendes hinzu:
components: securitySchemes: SCHEME_NAME: type: oauth2 flows: implicit: authorizationUrl: "" scopes: {} x-google-auth: issuer: ISSUER jwksUri: URL_PUBLIC_KEY # Optional. Replace CLIENT_ID with your client ID(s) as a list of strings. audiences: - CLIENT_ID jwtLocations: - header: Authorization valuePrefix: "Bearer "
Wobei:
- ISSUER ist der Aussteller des Tokens.
- URL_PUBLIC_KEY ist die URL zum öffentlichen Schlüssel.
- CLLIENT_ID ist eine Liste von Client-IDs als Strings.
- 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: - SCHEME_NAME: []
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 (OpenAPI 2.0) oder audiences (OpenAPI 3.x) ist nicht erforderlich. API Gateway 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 entsprechenden Feld audiences angeben. Mehrere Zielgruppen werden in OpenAPI 2.0 als durch Kommas getrennte Werte und in OpenAPI 3.x als Liste angegeben. API Gateway akzeptiert dann die JWTs mit einer der angegebenen Client-IDs im Anspruch aud.
Das Feld x-google-jwks_uri (OpenAPI 2.0) oder jwksUri (OpenAPI 3.x) ist erforderlich.
API Gateway unterstützt zwei asymmetrische öffentliche Schlüsselformate, die durch diese OpenAPI-Erweiterung 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
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
jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"
Wenn Sie ein symmetrisches Schlüsselformat verwenden, legen Sie für x-google-jwks_uri (OpenAPI 2.0) oder jwksUri (OpenAPI 3.x) den URI einer Datei mit dem base64url-codierten Schlüsselstring fest.
Authentifizierten Aufruf an eine API Gateway API senden
Wenn Sie eine Anfrage mit einem Authentifizierungstoken senden, empfehlen wir, das Token in den Header Authorization:Bearer einzufügen. Beispiel:
curl -H "Authorization: Bearer TOKEN" "GATEWAY_URL/hello"
Hier sollten GATEWAY_URL und TOKEN durch die bereitgestellte Gateway-URL bzw. das Authentifizierungstoken ersetzt werden. Unter Authentifizierte Anfrage an eine API Gateway 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 namens access_token einfügen. Beispiel:
curl "GATEWAY_URL/hello?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.