Usar os autorizadores do API Gateway Lambda
Use um autorizador do Lambda (anteriormente conhecido como autorizador personalizado) para controlar o acesso à API. Quando um cliente solicita o método da API, o API Gateway chama o autorizador do Lambda. O autorizador do Lambda usa a identidade do chamador como entrada e retorna uma política do IAM como saída.
Use um autorizador do Lambda para implementar um esquema de autorização personalizado. O esquema pode usar parâmetros de solicitação para determinar a identidade do chamador ou usar uma estratégia de autenticação de token de portador, como OAuth ou SAML. Crie um autorizador do Lambda no console da API REST do API Gateway, usando a AWS CLI ou um SDK da AWS.
Fluxo de trabalho de autorização do autorizador do Lambda
O diagrama a seguir mostra o fluxo de trabalho de autorização referente a um autorizador do Lambda.
Fluxo de trabalho de autorização do Lambda do API Gateway
-
O cliente chama um método em uma API do API Gateway, passando um token de portador ou parâmetros de solicitação.
-
O API Gateway confere se a solicitação do método está configurada com um autorizador do Lambda. Se estiver, o API Gateway chama a função do Lambda.
-
A função do Lambda autentica o chamador. A função pode fazer a autenticação das seguintes maneiras:
-
Chamando um provedor OAuth para receber um token de acesso OAuth.
-
Chamando um provedor SAML para receber uma declaração SAML.
-
Gerando uma política do IAM com base nos valores do parâmetro de solicitação.
-
Recuperando as credenciais de um banco de dados.
-
-
A função do Lambda retorna uma política do IAM e um identificador de entidade principal. Se a função do Lambda não retornar essas informações, a chamada falhará.
-
O API Gateway avalia a política do IAM.
-
Se o acesso for negado, o API Gateway retornará um código de status HTTP, por exemplo,
403 ACCESS_DENIED
. -
Se o acesso for permitido, o API Gateway invocará o método.
Se você habilitar o armazenamento em cache da autorização, o API Gateway armazenará a política em cache para que a função do autorizador do Lamba não seja invocada novamente.
-
É possível personalizar as respostas 403
ACCESS_DENIED
ou 401 UNAUTHORIZED
do gateway. Para saber mais, consulte Respostas do gateway para APIs REST no API Gateway.
Como escolher um tipo de autorizador do Lambda
Existem dois tipos de autorizadores do Lambda:
- Solicitar um autorizador do Lambda baseado em parâmetros (autorizador
REQUEST
) -
Um autorizador
REQUEST
recebe a identidade do chamador em uma combinação de cabeçalhos, parâmetros de strings de consulta, stageVariables e variáveis $context. É possível usar um autorizadorREQUEST
para criar políticas refinadas com base nas informações de várias fontes de identidade, como as variáveis de contexto$context.path
e$context.httpMethod
.Se você ativar o armazenamento em cache de autorização para um autorizador
REQUEST
, o API Gateway verificará se todas as fontes de identidade especificadas estão presentes na solicitação. Se uma fonte de identidade especificada estiver ausente, for nula ou estiver vazia, o API Gateway retornará uma resposta HTTP401 Unauthorized
sem chamar a função do autorizador do Lambda. Quando há várias fontes de identidade definidas, todas são usadas para derivar a chave de cache do autorizador, preservando a ordem. É possível definir uma chave de cache refinada usando várias fontes de identidade.Se você alterar qualquer parte da chave do cache e reimplantar a API, o autorizador descartará o documento da política em cache e gerará outro.
Se você desativar o armazenamento em cache de autorização para um autorizador
REQUEST
, o API Gateway passará a solicitação diretamente à função do Lambda. - Autorizador do Lambda com base em token (autorizador
TOKEN
) -
Um autorizador
TOKEN
recebe a identidade do chamador em um token de portador, como um JSON Web Token (JWT) ou um token OAuth.Se você ativar o armazenamento em cache de autorização para um autorizador
TOKEN
, o nome do cabeçalho especificado na origem do token será a chave do cache.Além disso, é possível usar a validação de token para inserir uma instrução RegEx. O API Gateway executa a validação inicial do token de entrada em relação a essa expressão e invoca a função do autorizador do Lambda mediante a validação com êxito. Isso ajuda a reduzir as chamadas para a API.
A propriedade
IdentityValidationExpression
é compatível somente com autorizadoresTOKEN
. Para ter mais informações, consulte Objeto x-amazon-apigateway-authorizer.
nota
Recomendamos que você use um autorizador REQUEST
para controlar o acesso à API. É possível controlar o acesso à API com base em várias fontes de identidade ao usar um autorizador REQUEST
, em comparação com uma única fonte de identidade ao usar um autorizador TOKEN
. Além disso, você pode separar as chaves de cache usando várias fontes de identidade para um autorizador REQUEST
.
Exemplo de função do Lambda do autorizador REQUEST
O código de exemplo a seguir criará uma função do autorizador do Lambda que permite uma solicitação se o cabeçalho HeaderAuth1
, o parâmetro de consulta QueryString1
e a variável de estágio de StageVar1
fornecidos pelo cliente corresponderem aos valores especificados de headerValue1
, queryValue1
e stageValue1
, respectivamente.
Neste exemplo, a função do autorizador do Lambda verifica os parâmetros de entrada e age da seguinte forma:
-
Se todos os valores de parâmetro necessários corresponderem aos valores esperados, a função do autorizador retornará uma resposta HTTP
200 OK
e uma política do IAM que é semelhante ao seguinte, e a solicitação de método será bem-sucedida:{ "Version": "2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Allow", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] }
-
Caso contrário, a função do autorizador retornará uma resposta HTTP
401 Unauthorized
e ocorrerá uma falha na solicitação do método.
Além de retornar uma política do IAM, a função de autorizador do Lambda também deve retornar o identificador principal do autor da chamada. Opcionalmente, ela pode retornar um objeto context
com informações adicionais que podem ser passadas ao back-end de integração. Para ter mais informações, consulte Saída de um autorizador do Lambda para o API Gateway.
No código de produção, talvez seja necessário autenticar o usuário antes de conceder a autorização. É possível adicionar a lógica de autenticação à função do Lambda chamando um provedor de autenticação conforme indicado na documentação desse provedor.
Exemplo de função do Lambda do autorizador TOKEN
O código de exemplo a seguir cria uma função do Lambda do autorizador TOKEN
que permite que um chamador invoque um método caso o valor do token fornecido pelo cliente seja allow
. O chamador não tem permissão para invocar a solicitação caso o valor do token seja deny
. Se o valor do token for unauthorized
ou uma string vazia, a função do autorizador retornará uma resposta 401 UNAUTHORIZED
.
Neste exemplo, quando a API recebe uma solicitação de método, o API Gateway repassa o token de origem para essa função do autorizador do Lambda no atributo event.authorizationToken
. A função do autorizador do Lambda lê o token e age da seguinte forma:
-
Se o valor do token for
allow
, a função do autorizador retornará uma resposta HTTP200 OK
e uma política do IAM que é semelhante ao seguinte, e a solicitação de método será bem-sucedida:{ "Version": "2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Allow", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] }
-
Se o valor do token for
deny
, a função do autorizador retornará uma resposta HTTP200 OK
e uma política do IAMDeny
que é semelhante ao seguinte, e ocorrerá uma falha na solicitação de método:{ "Version": "2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Deny", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] }
nota
Fora do ambiente de teste, o API Gateway retorna uma resposta HTTP
403 Forbidden
e ocorre uma falha na solicitação do método. -
Se o valor do token for
unauthorized
, a função do autorizador retornará uma resposta HTTP401 Unauthorized
, e ocorrerá uma falha na chamada de método. -
Se o valor do token for diferente, o cliente receberá uma resposta
500 Invalid token
, e ocorrerá uma falha na chamada de método.
Além de retornar uma política do IAM, a função de autorizador do Lambda também deve retornar o identificador principal do autor da chamada. Opcionalmente, ela pode retornar um objeto context
com informações adicionais que podem ser passadas ao back-end de integração. Para ter mais informações, consulte Saída de um autorizador do Lambda para o API Gateway.
No código de produção, talvez seja necessário autenticar o usuário antes de conceder a autorização. É possível adicionar a lógica de autenticação à função do Lambda chamando um provedor de autenticação conforme indicado na documentação desse provedor.
Exemplos adicionais de funções do autorizador do Lambda
A lista a seguir mostra exemplos adicionais de funções do autorizador do Lambda. É possível criar uma função do Lambda na mesma conta em que você criou a API ou em uma conta diferente.
No exemplo anterior de funções do Lambda, é possível usar a função integrada AWSLambdaBasicExecutionRole, já que essas funções não chamam outros serviços da AWS. Se a função do Lambda chamar outros serviços da AWS, será necessário atribuir um perfil de execução do IAM à função do Lambda. Para criar a função, siga as instruções na Função de execução AWS Lambda.
Exemplos adicionais de funções do autorizador do Lambda
-
Para ver um exemplo de aplicação, consulte Open Banking Brasil: amostras de autorizações
no GitHub. -
Para obter mais exemplos de funções do Lambda, consulte aws-apigateway-lambda-authorizer-blueprints
no GitHub. -
É possível criar um autorizador do Lambda que autentica usuários usando grupos de usuários do Amazon Cognito e autoriza chamadores com base em um armazenamento de políticas usando o Verified Permissions. Para ter mais informações, consulte Controlar o acesso com base nos atributos de uma identidade com o Verified Permissions.
-
O console do Lambda fornece um esquema Python, que você pode usar ao selecionar Use a blueprint (Usar um esquema) e selecionar o esquema api-gateway-authorizer-python.