As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Criação e gerenciamento de autorizadores personalizados (CLI) AWS IoT Core implementa esquemas personalizados de autenticação e autorização usando autorizadores personalizados. Um autorizador personalizado é um AWS IoT Core recurso que oferece a flexibilidade de definir e implementar as regras e políticas com base em seus requisitos específicos. Para criar um autorizador personalizado com step-by-step instruções, consulte [Tutorial: Criando um autorizador personalizado](https://docs.aws.amazon.com//iot/latest/developerguide/custom-auth-tutorial.html) para. AWS IoT Core Cada autorizador consiste nos seguintes componentes: + *Nome*: uma string exclusiva definida pelo usuário que identifica o autorizador. + *ARN da função do Lambda*: o nome do recurso da Amazon (ARN) da função do Lambda que implementa a lógica de autorização e autenticação.  + *Nome da chave do token*: o nome da chave usado para extrair o token dos cabeçalhos HTTP, dos parâmetros de consulta ou do nome de usuário do MQTT CONNECT para realizar a validação da assinatura. Esse valor será necessário se a assinatura estiver ativada em seu autorizador. + *Sinalizador de assinatura desativada (opcional)*: um valor booleano que especifica se a exigência de assinatura nas credenciais deve ser desativada. Isso é útil para cenários em que assinar as credenciais não faz sentido, como esquemas de autenticação que usam nome de usuário e senha do MQTT. O valor padrão é `false`; portanto, a assinatura é ativada por padrão. + *Chave pública de assinatura de token*: a chave pública que o AWS IoT Core usa para validar a assinatura de token. Seu comprimento mínimo é de 2.048 bits. Esse valor será necessário se a assinatura estiver ativada em seu autorizador.  O Lambda cobra pelo número de vezes que sua função do Lambda é executada e pelo tempo necessário para que o código em sua função seja executado. Para obter mais informações sobre preços do Lambda, consulte [Preços do Lambda](https://aws.amazon.com/lambda/pricing/). Para obter mais informações sobre a criação de funções do Lambda, consulte o [Guia do desenvolvedor do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/). **nota** Se você deixar a assinatura ativada, poderá evitar o acionamento excessivo do seu Lambda por clientes não reconhecidos. Considere isso antes de desativar o login no seu autorizador. **nota** O limite de tempo da função do Lambda para o autorizador personalizado é de 5 segundos. **Topics** + [Definição de sua função do Lambda](custom-auth-lambda.md) + [Criar um autorizador de capacidade](custom-auth-create-authorizer.md) + [Autorizando AWS IoT a invocação da função Lambda](custom-auth-authorize.md) + [Testar seus autorizadores](custom-auth-testing.md) + [Gerenciar autorizadores personalizados](custom-auth-manage.md) # Definição de sua função do Lambda Quando AWS IoT Core invoca seu autorizador, ele aciona o Lambda associado ao autorizador com um evento que contém o seguinte objeto JSON. O objeto JSON de exemplo contém todos os campos possíveis. Quaisquer campos que não sejam relevantes para a solicitação de conexão não estão incluídos. ``` {     "token" :"aToken",     "signatureVerified": Boolean, // Indicates whether the device gateway has validated the signature.     "protocols": ["tls", "http", "mqtt"], // Indicates which protocols to expect for the request.     "protocolData": {         "tls" : {             "serverName": "serverName" // The server name indication (SNI) host_name string.         },         "http": {             "headers": {                 "#{name}": "#{value}"             },             "queryString": "?#{name}=#{value}"         },         "mqtt": {             "username": "myUserName",             "password": "myPassword", // A base64-encoded string.             "clientId": "myClientId" // Included in the event only when the device sends the value.         }     },     "connectionMetadata": {         "id": UUID // The connection ID. You can use this for logging.     }, } ``` A função do Lambda deve usar essas informações para autenticar a conexão de entrada e decidir quais ações são permitidas na conexão. A função deve enviar uma resposta que contenha os seguintes valores. + `isAuthenticated`: um valor booliano que indica se a solicitação foi autenticada. + `principalId`: uma sequência alfanumérica que atua como um identificador para o token enviado pela solicitação de autorização personalizada. O valor deve ser uma sequência alfanumérica com pelo menos um e não mais que 128 caracteres e corresponder a este padrão de expressão regular (regex): `([a-zA-Z0-9]){1,128}`. Caracteres especiais que não sejam alfanuméricos não são permitidos para uso com a `principalId` entrada AWS IoT Core. Consulte a documentação de outros AWS serviços se caracteres especiais não alfanuméricos forem permitidos para o. `principalId` + `policyDocuments`: uma lista de documentos de AWS IoT Core políticas formatados em JSON Para obter mais informações sobre a criação AWS IoT Core de políticas, consulte. [AWS IoT Core políticas](iot-policies.md) O número máximo de documentos de política é de 10 documentos de política. Cada documento de política pode ter, no máximo, 2.048 caracteres. + `disconnectAfterInSeconds`: um número inteiro que especifica a duração máxima (em segundos) da conexão com o gateway do AWS IoT Core . O valor mínimo é de 300 segundos e o valor máximo é de 86.400 segundos. O valor padrão é 86.400. **nota** O valor de `disconnectAfterInSeconds` (retornado pela função do Lambda) é definido quando a conexão é estabelecida. Esse valor não poderá ser modificado durante as invocações do Lambda subsequentes para atualização da política. + `refreshAfterInSeconds`: um número inteiro que especifica o intervalo entre as atualizações da política. Quando esse intervalo passa, o AWS IoT Core invoca a função do Lambda para permitir atualizações de políticas. O valor mínimo é de 300 segundos e o valor máximo é de 86.400 segundos.  O objeto JSON a seguir contém um exemplo de resposta que sua função do Lambda pode enviar. **\$1 "isAuthenticated":true, //A Boolean that determines whether client can connect. "principalId": "xxxxxxxx",  //A string that identifies the connection in logs. "disconnectAfterInSeconds": 86400,  "refreshAfterInSeconds": 300,   "policyDocuments": [       \$1         "Version": "2012-10-17",         "Statement": [            \$1               "Action": "iot:Publish",               "Effect": "Allow",               "Resource": "arn:aws:iot:us-east-1::topic/customauthtesting"             \$1          ]        \$1     ] \$1** O `policyDocument` valor deve conter um documento AWS IoT Core de política válido. Para obter mais informações sobre AWS IoT Core políticas, consulte[AWS IoT Core políticas](iot-policies.md). Em MQTT sobre TLS e MQTT sobre WebSockets conexões, armazena em AWS IoT Core cache essa política para o intervalo especificado no valor do campo. `refreshAfterInSeconds` No caso de conexões HTTP, a função do Lambda é chamada para cada solicitação de autorização, a menos que seu dispositivo esteja usando conexões HTTP persistentes (também chamadas de keep-alive do HTTP ou reutilização de conexão HTTP). Você pode optar por ativar o armazenamento em cache ao configurar o autorizador. Durante esse intervalo, AWS IoT Core autoriza ações em uma conexão estabelecida com essa política em cache sem acionar sua função Lambda novamente. Se ocorrerem falhas durante a autenticação personalizada, a conexão AWS IoT Core será encerrada. AWS IoT Core também encerra a conexão se ela estiver aberta por mais tempo do que o valor especificado no `disconnectAfterInSeconds` parâmetro. A seguir JavaScript está uma amostra da função Lambda do Node.js que procura uma senha na mensagem do MQTT Connect com um valor `test` de e retorna uma política que concede permissão AWS IoT Core para se conectar com um cliente `myClientName` chamado e publicar em um tópico que contém o mesmo nome de cliente. Se a senha esperada não for encontrada, ele retornará uma política que nega essas duas ações. ``` // A simple Lambda function for an authorizer. It demonstrates // how to parse an MQTT password and generate a response. exports.handler = function(event, context, callback) {     var uname = event.protocolData.mqtt.username;     var pwd = event.protocolData.mqtt.password;     var buff = new Buffer(pwd, 'base64');     var passwd = buff.toString('ascii');     switch (passwd) {         case 'test':             callback(null, generateAuthResponse(passwd, 'Allow')); break;         default:             callback(null, generateAuthResponse(passwd, 'Deny'));       } }; // Helper function to generate the authorization response. var generateAuthResponse = function(token, effect) { var authResponse = {}; authResponse.isAuthenticated = true; authResponse.principalId = 'TEST123'; var policyDocument = {}; policyDocument.Version = '2012-10-17'; policyDocument.Statement = []; var publishStatement = {}; var connectStatement = {}; connectStatement.Action = ["iot:Connect"]; connectStatement.Effect = effect; connectStatement.Resource = ["arn:aws:iot:us-east-1:123456789012:client/myClientName"]; publishStatement.Action = ["iot:Publish"]; publishStatement.Effect = effect; publishStatement.Resource = ["arn:aws:iot:us-east-1:123456789012:topic/telemetry/myClientName"]; policyDocument.Statement[0] = connectStatement; policyDocument.Statement[1] = publishStatement; authResponse.policyDocuments = [policyDocument]; authResponse.disconnectAfterInSeconds = 3600; authResponse.refreshAfterInSeconds = 300; return authResponse; } ``` A função do Lambda anterior retorna o seguinte JSON ao receber a senha esperada de `test` na mensagem do MQTT Connect. Os valores das propriedades `password` e `principalId` serão os valores da mensagem do MQTT Connect. ``` { "password": "password", "isAuthenticated": true, "principalId": "principalId", "policyDocuments": [ { "Version": "2012-10-17", "Statement": [ { "Action": "iot:Connect", "Effect": "Allow", "Resource": "*" }, { "Action": "iot:Publish", "Effect": "Allow", "Resource": "arn:aws:iot:region:accountId:topic/telemetry/${iot:ClientId}" }, { "Action": "iot:Subscribe", "Effect": "Allow", "Resource": "arn:aws:iot:region:accountId:topicfilter/telemetry/${iot:ClientId}" }, { "Action": "iot:Receive", "Effect": "Allow", "Resource": "arn:aws:iot:region:accountId:topic/telemetry/${iot:ClientId}" } ] } ], "disconnectAfterInSeconds": 3600, "refreshAfterInSeconds": 300 } ``` # Criar um autorizador de capacidade Você pode criar um autorizador usando a [CreateAuthorizerAPI](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateAuthorizer.html). O exemplo a seguir descreve o comando. ``` aws iot create-authorizer --authorizer-name MyAuthorizer --authorizer-function-arn arn:aws:lambda:us-west-2::function:MyAuthorizerFunction  //The ARN of the Lambda function. [--token-key-name MyAuthorizerToken //The key used to extract the token from headers. [--token-signing-public-keys FirstKey= "-----BEGIN PUBLIC KEY-----   [...insert your public key here...]   -----END PUBLIC KEY-----" [--status ACTIVE] [--tags ] [--signing-disabled | --no-signing-disabled] ``` Você pode usar o parâmetro `signing-disabled` para cancelar a validação da assinatura para cada invocação do seu autorizador. É altamente recomendável que você não desative a assinatura, a menos que necessário. A validação de assinatura protege você contra invocações excessivas de sua função do Lambda de dispositivos desconhecidos. Não é possível atualizar o status `signing-disabled` de um autorizador depois de criá-lo. Para alterar esse comportamento, é necessário criar outro autorizador personalizado com um valor diferente para o parâmetro `signing-disabled`. Os valores dos parâmetros `tokenKeyName` e `tokenSigningPublicKeys` serão opcionais se você tiver desativado a assinatura. Eles são valores obrigatórios se a assinatura estiver ativada. Depois de criar sua função Lambda e o autorizador personalizado, você deve conceder explicitamente ao AWS IoT Core serviço permissão para invocar a função em seu nome. Você pode fazer isso com o comando a seguir. **nota** O endpoint de IoT padrão pode não aceitar o uso de autorizadores personalizados com funções do Lambda. Em vez disso, você pode usar configurações de domínio para definir um novo endpoint e depois especificar esse endpoint para o autorizador personalizado. ``` aws lambda add-permission --function-name --principal iot.amazonaws.com --source-arn --statement-id Id-123 --action "lambda:InvokeFunction" ``` # Autorizando AWS IoT a invocação da função Lambda Nesta seção, você concederá permissão ao recurso de autorizador personalizado que acabou de criar para executar a função do Lambda. Para conceder a permissão, você pode usar o comando da CLI [add-permission](https://docs.aws.amazon.com//cli/latest/reference/lambda/add-permission.html). **Conceda permissão para sua função Lambda usando o AWS CLI** 1. Depois de inserir os valores, digite o seguinte comando. Observe que o valor `statement-id` deve ser exclusivo. Substitua `Id-1234` pelo valor exato que você tem, caso contrário, você poderá receber um erro de `ResourceConflictException`. ``` aws lambda add-permission \ --function-name "custom-auth-function" \ --principal "iot.amazonaws.com" \ --action "lambda:InvokeFunction" \ --statement-id "Id-1234" \ --source-arn authorizerArn ``` 1. Se o comando for executado com êxito, ele retornará uma declaração de permissão, como neste exemplo. Você pode continuar na próxima seção para testar o autorizador personalizado. ``` { "Statement": "{\"Sid\":\"Id-1234\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"iot.amazonaws.com\"},\"Action\":\"lambda:InvokeFunction\",\"Resource\":\"arn:aws:lambda:Region:57EXAMPLE833:function:custom-auth-function\",\"Condition\":{\"ArnLike\":{\"AWS:SourceArn\":\"arn:aws:lambda:Region:57EXAMPLE833:function:custom-auth-function\"}}}" } ``` Se o comando não for executado com êxito, ele retornará um erro, como neste exemplo. Será necessário verificar e corrigir o erro antes de continuar. ``` An error occurred (AccessDeniedException) when calling the AddPermission operation: User: arn:aws:iam::57EXAMPLE833:user/EXAMPLE-1 is not authorized to perform: lambda:AddPer mission on resource: arn:aws:lambda:Region:57EXAMPLE833:function:custom-auth-function ``` # Testar seus autorizadores Você pode usar a [TestInvokeAuthorizer](https://docs.aws.amazon.com/iot/latest/apireference/API_TestInvokeAuthorizer.html)API para testar a invocação e os valores de retorno do seu autorizador. Essa API permite que você especifique metadados de protocolo e teste a validação da assinatura em seu autorizador. As guias a seguir mostram como usar o AWS CLI para testar seu autorizador. ------ #### [ Unix-like ] ``` aws iot test-invoke-authorizer --authorizer-name NAME_OF_AUTHORIZER \ --token TOKEN_VALUE --token-signature TOKEN_SIGNATURE ``` ------ #### [ Windows CMD ] ``` aws iot test-invoke-authorizer --authorizer-name NAME_OF_AUTHORIZER ^ --token TOKEN_VALUE --token-signature TOKEN_SIGNATURE ``` ------ #### [ Windows PowerShell ] ``` aws iot test-invoke-authorizer --authorizer-name NAME_OF_AUTHORIZER ` --token TOKEN_VALUE --token-signature TOKEN_SIGNATURE ``` ------ O valor do parâmetro `token-signature` é o token assinado. Para saber como obter esse valor, consulte [Assinatura do token](custom-auth.md#custom-auth-token-signature). Se seu autorizador usar um nome de usuário e uma senha, você poderá transmitir essas informações usando o parâmetro `--mqtt-context`. As guias a seguir mostram como usar a API `TestInvokeAuthorizer` para enviar um objeto JSON que contém nome de usuário, senha e nome de cliente para o autorizador personalizado. ------ #### [ Unix-like ] ``` aws iot test-invoke-authorizer --authorizer-name NAME_OF_AUTHORIZER \ --mqtt-context '{"username": "USER_NAME", "password": "dGVzdA==", "clientId":"CLIENT_NAME"}' ``` ------ #### [ Windows CMD ] ``` aws iot test-invoke-authorizer --authorizer-name NAME_OF_AUTHORIZER ^ --mqtt-context '{"username": "USER_NAME", "password": "dGVzdA==", "clientId":"CLIENT_NAME"}' ``` ------ #### [ Windows PowerShell ] ``` aws iot test-invoke-authorizer --authorizer-name NAME_OF_AUTHORIZER ` --mqtt-context '{"username": "USER_NAME", "password": "dGVzdA==", "clientId":"CLIENT_NAME"}' ``` ------ A senha deve ser codificada por base64. O exemplo a seguir mostra como codificar uma senha em um ambiente semelhante ao Unix. ``` echo -n PASSWORD | base64 ``` # Gerenciar autorizadores personalizados Você pode gerenciar seus autorizadores usando o seguinte APIs. + [ListAuthorizers](https://docs.aws.amazon.com/iot/latest/apireference/API_ListAuthorizers.html): mostre todos os autorizadores em sua conta. + [DescribeAuthorizer](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeAuthorizer.html): exibe as propriedades do autorizador especificado. Esses valores incluem data de criação, data da última modificação e outros atributos. + [SetDefaultAuthorizer](https://docs.aws.amazon.com/iot/latest/apireference/API_SetDefaultAuthorizer.html): especifica o autorizador padrão para seus endpoints de AWS IoT Core dados. AWS IoT Core usa esse autorizador se um dispositivo não passar AWS IoT Core credenciais e não especificar um autorizador. Para obter mais informações sobre o uso de AWS IoT Core credenciais, consulte[Autenticação de cliente](client-authentication.md). + [UpdateAuthorizer](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateAuthorizer.html): altera o status, o nome da chave do token ou as chaves públicas do autorizador especificado. + [DeleteAuthorizer](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteAuthorizer.html): exclui o autorizador especificado. **nota** Não é possível atualizar o requisito de assinatura de um autorizador. Assim, você não pode desativar a assinatura em um autorizador existente que exija isso. Você também não pode exigir a assinatura em um autorizador existente que não exija isso.