Definição de sua função do Lambda Criar um autorizador de capacidade Testar seus autorizadores Gerenciar autorizadores personalizados

Criação e gerenciamento de autorizadores personalizados

AWS IoT Core implementa esquemas personalizados de autenticação e autorização usando recursos do autorizador. 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. Para obter mais informações sobre a criação de funções do Lambda, consulte o Guia do desenvolvedor do Lambda.

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.

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 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 Lambda) é definido quando a conexão é estabelecida. Esse valor não pode ser modificado durante as invocações subsequentes do Lambda de 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.


{
"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": [
      {
        "Version": "2012-10-17",
        "Statement": [
           {
              "Action": "iot:Publish",
              "Effect": "Allow",
              "Resource": "arn:aws:iot:us-east-1:<your_aws_account_id>:topic/customauthtesting"
            }
         ]
       }
    ]
}

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, consulteAWS IoT Core políticas. 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. O exemplo a seguir descreve o comando.


aws iot create-authorizer
--authorizer-name MyAuthorizer
--authorizer-function-arn arn:aws:lambda:us-west-2:<account_id>: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 <value>]
[--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.

aws lambda add-permission --function-name <lambda_function_name> --principal iot.amazonaws.com --source-arn <authorizer_arn> --statement-id Id-123 --action "lambda:InvokeFunction"

Testar seus autorizadores

Você pode usar a API TestInvokeAuthorizer 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.

O valor do parâmetro token-signature é o token assinado. Para saber como obter esse valor, consulte Assinatura do token.

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.

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 as seguintes APIs.

ListAuthorizers: mostre todos os autorizadores em sua conta.
DescribeAuthorizer: exibe as propriedades do autorizador especificado. Esses valores incluem data de criação, data da última modificação e outros atributos.
SetDefaultAutorizador: especifica o autorizador padrão para seus AWS IoT Core endpoints de 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, consulteAutenticação de cliente.
UpdateAuthorizer: altera o status, o nome da chave do token ou as chaves públicas do autorizador especificado.
DeleteAuthorizer: 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.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Entender o fluxo de trabalho de autenticação personalizada

AWS IoT Core Conectando-se usando autenticação personalizada