Steuern des Zugriffs auf HTTP-APIs mit JWT-Genehmigern - Amazon API Gateway

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Steuern des Zugriffs auf HTTP-APIs mit JWT-Genehmigern

Sie können JSON Web Tokens (JWTs) als Teil der Frameworks OpenID Connect (OIDC) und OAuth 2.0 verwenden, um den Clientzugriff auf Ihre APIs einzuschränken.

Wenn Sie einen JWT-Genehmiger für eine Route Ihrer API konfigurieren, validiert API Gateway die JWTs, die Clients mit API-Anfragen übermitteln. API Gateway genehmigt oder lehnt Anfragen basierend auf der Token-Validierung und optional Bereichen im Token ab. Wenn Sie Bereiche für eine Route konfigurieren, muss das Token mindestens einen der Bereiche der Route enthalten.

Sie können unterschiedliche Genehmiger für jede Route einer API konfigurieren oder denselben Genehmiger für mehrere Routen verwenden.

Anmerkung

Es gibt keinen Standardmechanismus, um JWT-Zugriffstoken von anderen Arten von JWTs wie beispielsweise OpenID Connect ID-Token zu unterscheiden. Wir empfehlen, Ihre Routen so zu konfigurieren, dass Autorisierungsbereiche erforderlich sind, es sei denn, Sie benötigen ID-Token für die API-Autorisierung Sie können Ihre JWT-Genehmiger auch so konfigurieren, dass Aussteller oder Zielgruppen erforderlich sind, die Ihr Identitätsanbieter nur bei der Ausgabe von JWT-Zugriffstoken verwendet.

Autorisieren von API-Anfragen mit einem JWT-Autorisierer

API Gateway verwendet den folgenden allgemeinen Workflow, um Anfragen an Routen zu autorisieren, die für die Verwendung eines JWT-Genehmigers konfiguriert sind.

  1. Überprüfen Sie die identitySource auf ein Token. Der identitySource kann nur das Token oder das Token mit dem Präfix Bearer enthalten.

  2. Decodieren Sie das Token.

  3. Überprüfen Sie den Algorithmus und die Signatur des Tokens mit dem vom des Ausstellers abgerufenen öffentlichen Schlüsse jwks_uri. Derzeit werden nur RSA-basierte Algorithmen unterstützt. API Gateway kann den öffentlichen Schlüssel zwei Stunden lang zwischenspeichern. Es hat sich bewährt, beim Wechseln von Schlüsseln eine bestimmte Frist einzuräumen, während der sowohl der alte als auch der neue Schlüssel gültig sind.

  4. Validieren Sie die Ansprüche. API Gateway evaluiert die folgenden Token-Ansprüche:

    • kid – Das Token muss einen Header-Anspruch haben, der mit dem Schlüssel in dem jwks_uri übereinstimmt, der das Token signiert hat.

    • iss – Muss mit dem für den Genehmiger konfigurierten issuer übereinstimmen.

    • aud oder client_id – Muss mit einem der für den Genehmiger konfigurierten audience-Einträge übereinstimmen. API Gateway validiert client_id nur, wenn aud es nicht vorhanden ist. Wenn beide aud und vorhanden client_id sind, bewertet aud API Gateway.

    • exp – Muss nach der aktuellen Uhrzeit in UTC liegen.

    • nbf – muss vor der aktuellen Uhrzeit in UTC liegen.

    • iat – Muss vor der aktuellen Uhrzeit in UTC liegen.

    • scope oder scp – Das Token muss mindestens einen der Bereiche in den authorizationScopes der Route enthalten.

Wenn einer dieser Schritte fehlschlägt, lehnt API Gateway die API-Anfrage ab.

Nach der Validierung des JWT übergibt API Gateway die Ansprüche im Token an die Integration der API-Route. Backend-Ressourcen, wie beispielsweise Lambda-Funktionen, können auf die JWT-Ansprüche zugreifen. Wenn das JWT beispielsweise den Identitätsanspruch emailID enthält, ist er für eine Lambda-Integration in $event.requestContext.authorizer.jwt.claims.emailID verfügbar. Weitere Informationen zur Nutzlast, die API Gateway an Lambda-Integrationen sendet, finden Sie unter Arbeiten mit AWS Lambda Proxy-Integrationen für HTTP-APIs.

Erstellen eines JWT-Genehmigers

Bevor Sie einen JWT-Genehmiger erstellen, müssen Sie eine Clientanwendung bei einem Identitätsanbieter registrieren. Sie müssen darüber hinaus eine HTTP-API erstellt haben. Beispiele zum Erstellen einer HTTP-API finden Sie unter Erstellen einer HTTP-API.

Erstellen Sie mithilfe der Konsole einen JWT-Autorisierer

Die folgenden Schritte zeigen, wie Sie einen JWT-Autorisierer mithilfe der Konsole erstellen.

Um einen JWT-Autorisierer mit der Konsole zu erstellen
  1. Melden Sie sich bei der API-Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

  2. Wählen Sie eine HTTP-API.

  3. Wählen Sie im Hauptnavigationsbereich die Option Autorisierung aus.

  4. Wählen Sie die Registerkarte Autorisatoren verwalten.

  5. Wählen Sie Erstellen.

  6. Wählen Sie als Autorisierungstyp die Option JWT aus.

  7. Konfigurieren Sie Ihren JWT-Autorisierer und geben Sie eine Identitätsquelle an, die die Quelle des Tokens definiert.

  8. Wählen Sie Erstellen.

Erstellen Sie einen JWT-Autorisierer mit dem AWS CLI

Der folgende AWS CLI Befehl erstellt einen JWT-Autorisierer. Bei jwt-configuration geben Sie das Audience und Issuer als Ihren Identitätsanbieter an. Wenn Sie Amazon Cognito als Identitätsanbieter verwenden, IssuerUrl ist https://cognito-idp.us-east-2.amazonaws.com/userPoolID dies der Fall.

aws apigatewayv2 create-authorizer \ --name authorizer-name \ --api-id api-id \ --authorizer-type JWT \ --identity-source '$request.header.Authorization' \ --jwt-configuration Audience=audience,Issuer=IssuerUrl
Erstellen Sie einen JWT-Autorisierer mit AWS CloudFormation

Die folgende AWS CloudFormation Vorlage erstellt eine HTTP-API mit einem JWT-Autorisierer, der Amazon Cognito als Identitätsanbieter verwendet.

Die Ausgabe der AWS CloudFormation Vorlage ist eine URL für eine von Amazon Cognito gehostete Benutzeroberfläche, über die sich Kunden registrieren und anmelden können, um ein JWT zu erhalten. Nachdem sich ein Client angemeldet hat, wird der Client mit einem Zugriffstoken in der URL zu Ihrer HTTP-API umgeleitet. Um die API mit dem Zugriffstoken aufzurufen, ändern Sie das # in der URL in a, ? um das Token als Abfragezeichenfolgenparameter zu verwenden.

AWSTemplateFormatVersion: '2010-09-09' Description: | Example HTTP API with a JWT authorizer. This template includes an Amazon Cognito user pool as the issuer for the JWT authorizer and an Amazon Cognito app client as the audience for the authorizer. The outputs include a URL for an Amazon Cognito hosted UI where clients can sign up and sign in to receive a JWT. After a client signs in, the client is redirected to your HTTP API with an access token in the URL. To invoke the API with the access token, change the '#' in the URL to a '?' to use the token as a query string parameter. Resources: MyAPI: Type: AWS::ApiGatewayV2::Api Properties: Description: Example HTTP API Name: api-with-auth ProtocolType: HTTP Target: !GetAtt MyLambdaFunction.Arn DefaultRouteOverrides: Type: AWS::ApiGatewayV2::ApiGatewayManagedOverrides Properties: ApiId: !Ref MyAPI Route: AuthorizationType: JWT AuthorizerId: !Ref JWTAuthorizer JWTAuthorizer: Type: AWS::ApiGatewayV2::Authorizer Properties: ApiId: !Ref MyAPI AuthorizerType: JWT IdentitySource: - '$request.querystring.access_token' JwtConfiguration: Audience: - !Ref AppClient Issuer: !Sub https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPool} Name: test-jwt-authorizer MyLambdaFunction: Type: AWS::Lambda::Function Properties: Runtime: nodejs18.x Role: !GetAtt FunctionExecutionRole.Arn Handler: index.handler Code: ZipFile: | exports.handler = async (event) => { const response = { statusCode: 200, body: JSON.stringify('Hello from the ' + event.routeKey + ' route!'), }; return response; }; APIInvokeLambdaPermission: Type: AWS::Lambda::Permission Properties: FunctionName: !Ref MyLambdaFunction Action: lambda:InvokeFunction Principal: apigateway.amazonaws.com SourceArn: !Sub arn:${AWS::Partition}:execute-api:${AWS::Region}:${AWS::AccountId}:${MyAPI}/$default/$default FunctionExecutionRole: Type: AWS::IAM::Role Properties: AssumeRolePolicyDocument: Version: '2012-10-17' Statement: - Effect: Allow Principal: Service: - lambda.amazonaws.com Action: - 'sts:AssumeRole' ManagedPolicyArns: - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole UserPool: Type: AWS::Cognito::UserPool Properties: UserPoolName: http-api-user-pool AutoVerifiedAttributes: - email Schema: - Name: name AttributeDataType: String Mutable: true Required: true - Name: email AttributeDataType: String Mutable: false Required: true AppClient: Type: AWS::Cognito::UserPoolClient Properties: AllowedOAuthFlows: - implicit AllowedOAuthScopes: - aws.cognito.signin.user.admin - email - openid - profile AllowedOAuthFlowsUserPoolClient: true ClientName: api-app-client CallbackURLs: - !Sub https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com ExplicitAuthFlows: - ALLOW_USER_PASSWORD_AUTH - ALLOW_REFRESH_TOKEN_AUTH UserPoolId: !Ref UserPool SupportedIdentityProviders: - COGNITO HostedUI: Type: AWS::Cognito::UserPoolDomain Properties: Domain: !Join - '-' - - !Ref MyAPI - !Ref AppClient UserPoolId: !Ref UserPool Outputs: SignupURL: Value: !Sub https://${HostedUI}.auth.${AWS::Region}.amazoncognito.com/login?client_id=${AppClient}&response_type=token&scope=email+profile&redirect_uri=https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com

Aktualisieren Sie eine Route, um einen JWT-Autorisierer zu verwenden

Sie können die Konsole, das oder ein AWS SDK verwenden AWS CLI, um eine Route so zu aktualisieren, dass sie einen JWT-Autorisierer verwendet.

Aktualisieren Sie eine Route mithilfe der Konsole, um einen JWT-Autorisierer zu verwenden

Die folgenden Schritte zeigen, wie Sie eine Route für die Verwendung des JWT-Autorisierers mithilfe der Konsole aktualisieren.

Um einen JWT-Autorisierer mit der Konsole zu erstellen
  1. Melden Sie sich bei der API-Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

  2. Wählen Sie eine HTTP-API.

  3. Wählen Sie im Hauptnavigationsbereich die Option Autorisierung aus.

  4. Wählen Sie eine Methode aus, wählen Sie dann Ihren Autorisierer aus dem Drop-down-Menü aus und wählen Sie Autorisierer anhängen aus.

Aktualisieren Sie eine Route, um einen JWT-Autorisierer zu verwenden, indem Sie AWS CLI

Der folgende Befehl aktualisiert eine Route für die Verwendung eines JWT-Autorisierers mithilfe von. AWS CLI

aws apigatewayv2 update-route \ --api-id api-id \ --route-id route-id \ --authorization-type JWT \ --authorizer-id authorizer-id \ --authorization-scopes user.email