Usar os autorizadores do API Gateway Lambda - Amazon API Gateway

Usar os autorizadores do API Gateway Lambda

Um autorizador do Lambda (anteriormente conhecido como autorizador personalizado) é um recurso do API Gateway que usa uma função do Lambda para controlar o acesso à sua API.

Um autorizador do Lambda é útil se você deseja implementar um esquema de autorização personalizado que usa uma estratégia de autenticação de token de portador, como OAuth ou SAML, ou que usa parâmetros de solicitação para determinar a identidade do autor da chamada.

Quando um cliente faz uma solicitação para um dos métodos da sua API, o API Gateway chama o autorizador do Lambda, que assume a identidade do autor da chamada como uma entrada e retorna uma política do IAM como uma saída.

Existem dois tipos de autorizadores do Lambda:

  • Um autorizador baseado em token do Lambda (também chamado de autorizador TOKEN) recebe a identidade do autor da chamada em um token de portador, como token de web JSON (JWT) ou um token OAuth. Para ver um exemplo de aplicação, consulte Open Banking Brasil: amostras de autorizações no GitHub.

  • Um autorizador do Lambda baseado em parâmetro de solicitação (também chamado de autorizador REQUEST) recebe a identidade do autor da chamada em uma combinação de cabeçalhos, parâmetros de strings de consulta, stageVariables e variáveis $context.

    Para APIs WebSocket, apenas autorizadores de solicitação baseados em parâmetro são compatíveis.

É possível usar uma função AWS Lambda de uma conta da AWS diferente daquela em que você criou sua API. Para obter mais informações, consulte Configurar um autorizador do Lambda entre contas.

Para obter funções do Lambda, consulte aws-apigateway-lambda-authorizer-blueprints no GitHub.

Fluxo de trabalho Auth do autorizador do Lambda

O diagrama a seguir ilustra o fluxo de autorização para autorizadores do Lambda.


                Fluxo de trabalho de autorização do Lambda do API Gateway

Fluxo de trabalho de autorização do Lambda do API Gateway

  1. O cliente chama um método em um método de API do API Gateway, repassando um token de portador ou parâmetros de solicitação.

  2. O API Gateway verifica se um autorizador do Lambda está configurado para o método. Se estiver, o API Gateway chama a função do Lambda.

  3. A função do Lambda autentica o autor da chamada por meios como os seguintes:

    • Chamada para um provedor OAuth para obter um token de acesso OAuth.

    • Chamada para um provedor SAML para obter uma declaração do SAML.

    • Geração de uma política do IAM com base nos valores de parâmetro de solicitação.

    • Recuperação de credenciais de um banco de dados.

  4. Se a chamada for bem-sucedida, a função do Lambda concederá acesso retornando um objeto de saída que contém, pelo menos, um identificador principal e uma política do IAM.

  5. O API Gateway avalia a política.

    • 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 executará o método. Se o armazenamento em cache estiver habilitado nas configurações do autorizador, o API Gateway também armazenará em cache a política para que a função do autorizador do Lambda não precise ser invocada novamente.

Etapas para criar um autorizador do Lambda do API Gateway

Para criar o autorizador do Lambda, você precisa executar as seguintes tarefas:

  1. Crie a função de autorização do Lambda no console do Lambda conforme descrito em Criar uma função de autorização do Lambda do API Gateway no console do Lambda. Você pode usar um dos exemplos de esquema como ponto de partida e personalizar a entrada e a saída conforme desejado.

  2. Configure a função do Lambda como um autorizador do API Gateway e configure um método de API para exigi-la, conforme descrito em Configurar um autorizador do Lambda usando o console do API Gateway. Como alternativa, se você precisa de um autorizador do Lambda entre contas, consulte Configurar um autorizador do Lambda entre contas.

    nota

    Você também pode configurar um autorizador usando a AWS CLI ou um AWS SDK.

  3. Teste seu autorizador usando Postman conforme descrito em Chamar uma API com os autorizadores do Lambda do API Gateway.

Criar uma função de autorização do Lambda do API Gateway no console do Lambda

Antes de configurar um autorizador do Lambda, você deve criar a função do Lambda que implementa a lógica para autorizar e, se necessário, para autenticar o autor da chamada. 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. Caso contrário, você precisará usar um dos esquemas no repositório GitHub awslabs como ponto de partida.

Para o exemplo de funções do autorizador do Lambda nesta seção, que não chamam outros serviços, você pode usar o integrado AWSLambdaBasicExecutionRole. Ao criar a função do Lambda para seu próprio autorizador do Lambda do API Gateway, você precisará atribuir uma função de execução do IAM à função do Lambda se ela chamar outros serviços da AWS. Para criar a função, siga as instruções na Função de execução AWS Lambda.

Para obter mais exemplos de funções do Lambda, consulte aws-apigateway-lambda-authorizer-blueprints no GitHub. Para ver um exemplo de aplicação, consulte Open Banking Brasil: amostras de autorizações no GitHub.

EXEMPLO: Criar uma função do autorizador do Lambda com base em token

Para criar uma função de autorizador do Lambda com base em token, insira o seguinte código Node.js no console do Lambda e teste-o no console do API Gateway da maneira indicada a seguir.

  1. No console do Lambda, escolha Create function (Criar função).

  2. Escolha Author from scratch (Criar do zero).

  3. Insira um nome para a função.

  4. Escolha Create function (Criar função).

  5. Copie/cole o código a seguir no editor de código.

    // A simple token-based authorizer example to demonstrate how to use an authorization token // to allow or deny a request. In this example, the caller named 'user' is allowed to invoke // a request if the client-supplied token value is 'allow'. The caller is not allowed to invoke // the request if the token value is 'deny'. If the token value is 'unauthorized' or an empty // string, the authorizer function returns an HTTP 401 status code. For any other token value, // the authorizer returns an HTTP 500 status code. // Note that token values are case-sensitive. exports.handler = function(event, context, callback) { var token = event.authorizationToken; switch (token) { case 'allow': callback(null, generatePolicy('user', 'Allow', event.methodArn)); break; case 'deny': callback(null, generatePolicy('user', 'Deny', event.methodArn)); break; case 'unauthorized': callback("Unauthorized"); // Return a 401 Unauthorized response break; default: callback("Error: Invalid token"); // Return a 500 Invalid token response } }; // Help function to generate an IAM policy var generatePolicy = function(principalId, effect, resource) { var authResponse = {}; authResponse.principalId = principalId; if (effect && resource) { var policyDocument = {}; policyDocument.Version = '2012-10-17'; policyDocument.Statement = []; var statementOne = {}; statementOne.Action = 'execute-api:Invoke'; statementOne.Effect = effect; statementOne.Resource = resource; policyDocument.Statement[0] = statementOne; authResponse.policyDocument = policyDocument; } // Optional output with custom properties of the String, Number or Boolean type. authResponse.context = { "stringKey": "stringval", "numberKey": 123, "booleanKey": true }; return authResponse; }
  6. Escolha Deploy (Implantar).

  7. No console do API Gateway, crie uma API simples se você ainda não tiver uma.

  8. Selecione sua API na lista de APIs.

  9. Selecione Authorizers (Autorizadores).

  10. Selecione Create New Authorizer (Criar novo autorizador).

  11. Insira um nome para o autorizador.

  12. Para Type (Tipo), escolha Lambda.

  13. Em Lambda Function (Função do Lambda), selecione a região na qual você criou sua função do autorizador do Lambda e selecione o nome da função na lista suspensa.

  14. Deixe o campo Lambda Invoke Role (Função de chamada do Lambda) em branco.

  15. Para Lambda Event Payload (Carga de evento do Lambda), escolha Token.

  16. Em Token Source (Origem do token), insira authorizationToken.

  17. Selecione Create (Criar) e Grant & Create (Conceder e criar).

  18. Escolha Test (Testar).

  19. Para o valor authorizationToken insira allow.

  20. Escolha Test (Testar).

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 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/" } ] }
  • Se o valor do token for 'deny', a função do autorizador retornará uma resposta HTTP 403 Forbidden e uma política do IAM Deny 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/" } ] }
  • Se o valor do token for 'unauthorized', a função do autorizador retornará uma resposta HTTP 401 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.

nota

No código de produção, talvez seja necessário autenticar o usuário antes de conceder a autorização. Se esse for o caso, você também poderá adicionar a lógica de autenticação à função do Lambda e chamar um provedor de autenticação conforme indicado na documentação para esse provedor.

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 também pode retornar um objeto context com informações adicionais que podem ser repassadas para o backend de integração. Para obter mais informações, consulte Saída de um autorizador do Lambda do Amazon API Gateway.

EXEMPLO: Criar uma função do autorizador do Lambda com base em solicitação

Para criar uma função de autorizador do Lambda com base em solicitação, insira o seguinte código Node.js no console do Lambda e teste-o no console do API Gateway da maneira indicada a seguir.

  1. No console do Lambda, escolha Create function (Criar função).

  2. Escolha Author from scratch (Criar do zero).

  3. Insira um nome para a função.

  4. Escolha Create function (Criar função).

  5. Copie/cole o código a seguir no editor de código.

    exports.handler = function(event, context, callback) { console.log('Received event:', JSON.stringify(event, null, 2)); // A simple request-based authorizer example to demonstrate how to use request // parameters to allow or deny a request. In this example, a request is // authorized if the client-supplied headerauth1 header, QueryString1 // query parameter, and stage variable of StageVar1 all match // specified values of 'headerValue1', 'queryValue1', and 'stageValue1', // respectively. // Retrieve request parameters from the Lambda function input: var headers = event.headers; var queryStringParameters = event.queryStringParameters; var pathParameters = event.pathParameters; var stageVariables = event.stageVariables; // Parse the input for the parameter values var tmp = event.methodArn.split(':'); var apiGatewayArnTmp = tmp[5].split('/'); var awsAccountId = tmp[4]; var region = tmp[3]; var restApiId = apiGatewayArnTmp[0]; var stage = apiGatewayArnTmp[1]; var method = apiGatewayArnTmp[2]; var resource = '/'; // root resource if (apiGatewayArnTmp[3]) { resource += apiGatewayArnTmp[3]; } // Perform authorization to return the Allow policy for correct parameters and // the 'Unauthorized' error, otherwise. var authResponse = {}; var condition = {}; condition.IpAddress = {}; if (headers.headerauth1 === "headerValue1" && queryStringParameters.QueryString1 === "queryValue1" && stageVariables.StageVar1 === "stageValue1") { callback(null, generateAllow('me', event.methodArn)); } else { callback("Unauthorized"); } } // Help function to generate an IAM policy var generatePolicy = function(principalId, effect, resource) { // Required output: var authResponse = {}; authResponse.principalId = principalId; if (effect && resource) { var policyDocument = {}; policyDocument.Version = '2012-10-17'; // default version policyDocument.Statement = []; var statementOne = {}; statementOne.Action = 'execute-api:Invoke'; // default action statementOne.Effect = effect; statementOne.Resource = resource; policyDocument.Statement[0] = statementOne; authResponse.policyDocument = policyDocument; } // Optional output with custom properties of the String, Number or Boolean type. authResponse.context = { "stringKey": "stringval", "numberKey": 123, "booleanKey": true }; return authResponse; } var generateAllow = function(principalId, resource) { return generatePolicy(principalId, 'Allow', resource); } var generateDeny = function(principalId, resource) { return generatePolicy(principalId, 'Deny', resource); }
  6. Escolha Deploy (Implantar).

  7. No console do API Gateway, crie uma API simples se você ainda não tiver uma.

  8. Selecione sua API na lista de APIs.

  9. Selecione Authorizers (Autorizadores).

  10. Selecione Create New Authorizer (Criar novo autorizador).

  11. Insira um nome para o autorizador.

  12. Para Type (Tipo), escolha Lambda.

  13. Em Lambda Function (Função do Lambda), selecione a região na qual você criou sua função do autorizador do Lambda e selecione o nome da função na lista suspensa.

  14. Deixe o campo Lambda Invoke Role (Função de chamada do Lambda) em branco.

  15. Para Lambda Event Payload (Carga de Evento do Lambda), escolha Request (Solicitar).

  16. Em Identity Sources (Origens de identidade), adicione um Header (Cabeçalho) chamado headerauth1, uma Query String (String de consulta) chamada QueryString1 e uma Stage Variable (Variável de estágio) chamada StageVar1.

  17. Selecione Create (Criar) e Grant & Create (Conceder e criar).

  18. Escolha Test (Testar).

  19. Em headerauth1, insira headerValue1. Em QueryString1, insira queryValue1. Em StageVar1, insira stageValue1.

  20. Escolha Test (Testar).

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 chamada de método.

nota

No código de produção, talvez seja necessário autenticar o usuário antes de conceder a autorização. Se esse for o caso, você também poderá adicionar a lógica de autenticação à função do Lambda e chamar um provedor de autenticação conforme indicado na documentação para esse provedor.

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 também pode retornar um objeto context com informações adicionais que podem ser repassadas para o backend de integração. Para obter mais informações, consulte Saída de um autorizador do Lambda do Amazon API Gateway.