Controlar o acesso a APIs HTTP com autorizadores JWT no API Gateway - Amazon API Gateway

Controlar o acesso a APIs HTTP com autorizadores JWT no API Gateway

O JSON Web Tokens (JWTs) pode ser usado como parte das estruturas OpenID Connect (OIDC) e OAuth 2.0 para que você possa restringir o acesso do cliente às suas APIs.

Se você configurar um autorizador JWT para uma rota da sua API, o API Gateway valida os JWTs enviados pelos clientes com solicitações de API. O API Gateway aceita ou rejeita solicitações com base na validação de tokens e, opcionalmente, escopos no token. Se você configurar escopos para uma rota, o token deverá incluir pelo menos um dos escopos da rota.

Você pode configurar autorizadores distintos para cada rota de uma API ou usar o mesmo autorizador para várias rotas.

nota

Não existe nenhum mecanismo padrão para diferenciar tokens de acesso JWT de outros tipos de JWTs, como os tokens OpenID e Connect ID. Exceto se precisar de tokens de ID para autorização de API, recomendamos que você configure suas rotas para exigir escopos de autorização. Você também pode configurar seus autorizadores do JWT para exigir emissores ou públicos que seu provedor de identidade usa somente ao emitir tokens de acesso do JWT.

Autorização de solicitações de API com um autorizador JWT

O API Gateway usa o fluxo de trabalho geral a seguir para autorizar solicitações para rotas configuradas para usar um autorizador JWT.

  1. Verifique se há um token em identitySource. O identitySource pode incluir apenas o token ou o token com o prefixo Bearer.

  2. Decodifique o token.

  3. Verifique o algoritmo e a assinatura do token usando a chave pública obtida do do emisso jwks_uri. No momento, somente algoritmos baseados em RSA são compatíveis. O API Gateway pode armazenar a chave pública em cache por duas horas. Como prática recomendada, ao alternar as chaves, aguarde um período de carência durante o qual as chaves antigas e novas sejam válidas.

  4. Valide reivindicações. O API Gateway avalia as seguintes reivindicações de token:

    • kid: o token deve ter uma reivindicação de cabeçalho que corresponda à chave no jwks_uri que assinou o token.

    • iss: deve corresponder ao issuer configurado para o autorizador.

    • aud ou client_id: deve corresponder a uma das entradas audience configuradas para o autorizador. O API Gateway valida client_id somente se aud não estiver presente. Quando aud e client_id estão presentes, o API Gateway avalia aud.

    • exp – deve ser após a hora atual em UTC.

    • nbf – deve ser antes da hora atual em UTC.

    • iat – deve ser antes da hora atual em UTC.

    • scope ou scp: o token deve incluir pelo menos um dos escopos em authorizationScopes da rota.

Se qualquer uma dessas etapas falhar, o API Gateway negará a solicitação de API.

Depois de validar o JWT, o API Gateway passa as alegações no token para a integração da rota da API. Recursos de backend, como as funções do Lambda, podem acessar as alegações de JWT. Por exemplo, se o JWT incluiu um emailID de alegação de identidade, ele estará disponível para uma integração do Lambda em $event.requestContext.authorizer.jwt.claims.emailID. Para obter mais informações sobre a carga útil que o API Gateway envia para integrações do Lambda, consulte Criar integrações de proxy AWS Lambda para APIs HTTP no API Gateway.

Criar um autorizador de JWT

Antes de criar um autorizador de JWT, você deve registrar um aplicativo cliente com um provedor de identidade. Também deve ter criado uma API HTTP. Para obter exemplos de criação de uma API HTTP, consulte Criar uma API HTTP.

Criar um autorizador JWT usando o console

As etapas a seguir mostram como criar o autorizador JWT usando o console.

Criar um autorizador JWT usando o console
  1. Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway.

  2. Selecione uma API HTTP.

  3. No painel de navegação principal, selecione Autorização.

  4. Escolha a guia Gerenciar autorizadores.

  5. Escolha Criar.

  6. Em Tipo de autorizador, escolha JWT.

  7. Configure o autorizador JWT e especifique uma Origem da identidade que defina a origem do token.

  8. Escolha Criar.

Criar um autorizador JWT usando a AWS CLI

O comando AWS CLI a seguir cria um autorizador do JWT. Para jwt-configuration, especifique o Audience e o Issuer para seu provedor de identidades. Se você usa o Amazon Cognito como provedor de identidade, o 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
Criar um autorizador de AWS CloudFormation

O modelo AWS CloudFormation a seguir cria uma API HTTP com um autorizador JWT usando o Amazon Cognito como provedor de identidade.

A saída do modelo AWS CloudFormation é um URL para uma interface de usuário hospedada no Amazon Cognito, na qual os clientes podem se inscrever e fazer login para receber um JWT. Depois que o cliente faz login, é redirecionado para sua API HTTP com um token de acesso no URL. Para invocar a API com o token de acesso, altere o # no URL para um ? para usar o token como um parâmetro de string de consulta.

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

Atualizar uma rota para usar um autorizador JWT

Você pode usar o console, a AWS CLI ou um AWS SDK para atualizar uma rota para usar um autorizador JWT.

Atualizar uma rota para usar um autorizador JWT com o console

As etapas a seguir mostram como atualizar uma rota para usar o autorizador JWT com o console.

Para criar um autorizador JWT usando o console
  1. Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway.

  2. Selecione uma API HTTP.

  3. No painel de navegação principal, selecione Autorização.

  4. Escolha um método, selecione o autorizador no menu suspenso e escolha Anexar autorizador.

Atualizar uma rota para usar um autorizador JWT com a AWS CLI

O comando a seguir atualiza uma rota para usar um autorizador JWT com a 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