Controllo degli accessi alle API HTTP con provider di autorizzazioni JWT in Gateway API

È possibile utilizzare JSON Web Tokens (JWT) come parte di framework OpenID Connect (OIDC) e OAuth 2.0 per limitare l'accesso client alle API.

Se si configura un autorizzatore JWT per una route dell'API, API Gateway convalida i JWT inviati dai client con le richieste API. API Gateway consente o nega le richieste in base alla convalida dei token e, facoltativamente, gli ambiti nel token. Se si configurano gli ambiti per un percorso, il token deve includere almeno uno degli ambiti del percorso.

È possibile configurare autorizzazioni distinte per ogni percorso di un'API o utilizzare lo stesso autorizzatore per più route.

Nota

Non esiste un meccanismo standard per differenziare i token di accesso JWT da altri tipi di JWT come token ID OpenID Connect. A meno che non si richiedano token ID per l'autorizzazione API, si consiglia di configurare le route per richiedere gli ambiti di autorizzazione. È inoltre possibile configurare gli autorizzatori JWT per richiedere emittenti o gruppi di destinatari che il provider di identità utilizza solo quando si emettono token di accesso JWT.

Autorizzazione delle richieste API con un provider di autorizzazioni JWT

API Gateway utilizza il seguente flusso di lavoro generale per autorizzare le richieste alle route configurate per l'utilizzo di un'autorizzazione JWT.

1. Controllare la presenza di identitySource per un token. Il identitySource può includere solo il token o il token con il prefisso Bearer.

2. Decodifica del token.

3. Controlla l'algoritmo e la firma del token utilizzando la chiave pubblica recuperata dal dell'emittent jwks_uri. Attualmente sono supportati solo gli algoritmi basati su RSA. Gateway Amazon API può memorizzare la chiave pubblica nella cache per due ore. Come best practice, quando si esegue la rotazione delle chiavi, definire un periodo di tolleranza durante il quale sia la vecchia che la nuova chiave sono valide.

4. Convalida delle richieste. API Gateway valuta le seguenti richieste dei token:

   • kid: il token deve presentare una richiesta di intestazione che corrisponde alla chiave nel jwks_uri che ha firmato il token.

   • iss: deve corrispondere all'issuer configurato per l'autorizzazione.

   • aud o client_id: devono corrispondere a una delle voci audience configurate per l'autorizzazione. Gateway API convalida client_id solo se aud non è presente. Quando aud e client_id sono entrambi presenti, Gateway API valuta aud.

   • exp – deve essere successivo all'ora corrente in UTC.

   • nbf – deve essere precedente all'ora corrente in UTC.

   • iat – deve essere precedente all'ora corrente in UTC.

   • scope o scp: il token deve includere almeno uno degli ambiti negli authorizationScopes della route.

Se uno di questi passaggi non riesce, API Gateway nega la richiesta API.

Dopo aver convalidato il JWT, API Gateway passa le registrazioni nel token all'integrazione della route API. Le risorse di back-end, come le funzioni Lambda, possono accedere alle attestazioni JWT. Ad esempio, se JWT include un'attestazione di identità emailID, è disponibile per un'integrazione Lambda in $event.requestContext.authorizer.jwt.claims.emailID. Per ulteriori informazioni sul payload che API Gateway invia alle integrazioni Lambda, consulta Creazione delle integrazioni proxy AWS Lambda per API HTTP in Gateway API.

Creazione di un'autorizzazione JWT

Prima di creare un autorizzatore JWT, è necessario registrare un'applicazione client con un provider di identità. È anche necessario aver creato un'API HTTP. Per esempi di creazione di un'API HTTP, consultare Creazione di un'API HTTP.

Creazione di un provider di autorizzazioni JWT tramite la console

Nei seguenti passaggi viene illustrato come creare un provider di autorizzazioni JWT utilizzando la console.

Per creare un provider di autorizzazioni JWT tramite la console

1. Accedere alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.

2. Scegliere un'API HTTP.

3. Nel pannello di navigazione principale, scegli Autorizzazione.

4. Seleziona la scheda Gestisci provider di autorizzazioni.

5. Scegli Create (Crea).

6. Per Tipo di autorizzazione scegli JWT.

7. Configurare il provider di autorizzazioni JWT e specificare una Origine identità che definisca l'origine del token.

8. Scegli Create (Crea).

Creazione di un provider di autorizzazioni JWT tramite AWS CLI

Il comando AWS CLI seguente crea un'autorizzazione JWT. Per jwt-configuration, specificare Audience e Issuer per il provider di identità. Se si utilizza Amazon Cognito come provider di identità, IssuerUrl è https://cognito-idp.us-east-2.amazonaws.com/userPoolID.

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

Creazione di un provider di autorizzazioni JWT tramite AWS CloudFormation

Il modello AWS CloudFormation seguente crea un'API HTTP con un provider di autorizzazioni JWT che utilizza Amazon Cognito come provider di identità.

L'output del modello AWS CloudFormation è un URL per un'interfaccia utente ospitata in Amazon Cognito in cui i client possono registrarsi e accedere per ottenere un provider di autorizzazioni JWT. Dopo l'accesso, il client viene reindirizzato all'API HTTP con un token di accesso nell'URL. Per invocare l'API con il token di accesso, modifica # nell'URL in ? per utilizzare il token come parametro della stringa di query.

Modello AWS CloudFormation di esempio

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

Aggiornamento di un instradamento per utilizzare un provider di autorizzazioni JWT

È possibile utilizzare la console, AWS CLI un AWS SDK per aggiornare un instradamento in modo da utilizzare un provider di autorizzazioni JWT.

Aggiornamento di un instradamento per utilizzare un provider di autorizzazioni JWT tramite la console

Nei seguenti passaggi viene illustrato come aggiornare un instradamento per utilizzare un provider di autorizzazioni JWT utilizzando la console.

Per creare un provider di autorizzazioni JWT tramite la console

1. Accedere alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.

2. Scegliere un'API HTTP.

3. Nel pannello di navigazione principale, scegli Autorizzazione.

4. Scegli un metodo, quindi seleziona il provider di autorizzazioni dal menu a discesa e scegli Collega provider di autorizzazioni.

Aggiornamento di un instradamento per utilizzare un provider di autorizzazioni JWT tramite AWS CLI

Il comando seguente aggiorna un instradamento per utilizzare un provider di autorizzazioni JWT tramite 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