Criar e gerenciar segredos Usar segredos locais

O AWS IoT Greengrass Version 1 entrou na fase de vida útil prolongada em 30 de junho de 2023. Para obter mais informações, consulte política de manutenção do AWS IoT Greengrass V1. Após essa data, o AWS IoT Greengrass V1 não lançará atualizações que forneçam recursos, aprimoramentos, correções de erros ou patches de segurança. Os dispositivos que funcionam com o AWS IoT Greengrass V1 não serão interrompidos e continuarão operando e se conectando à nuvem. É altamente recomendável que você migre para AWS IoT Greengrass Version 2, o que adicionará novos recursos significativos e suporte para plataformas adicionais.

Como trabalhar com recursos de segredos

O AWS IoT Greengrass usa recursos de segredos para integrar segredos do AWS Secrets Manager a um grupo do Greengrass. Um recurso de segredo é uma referência a um segredo do Secrets Manager. Para ter mais informações, consulte Implantar segredos no núcleo do AWS IoT Greengrass.

No dispositivo de núcleo AWS IoT Greengrass, os conectores e as funções do Lambda podem usar o recurso de segredo para se autenticar com serviços e aplicativos, sem codificação rígida de senhas, tokens ou outras credenciais.

Criar e gerenciar segredos

Em um grupo do Greengrass, um recurso de segredo faz referência ao ARN de um segredo do Secrets Manager. Quando o recurso de segredo é implantado no núcleo, o valor do segredo é criptografado e disponibilizado para conectores e funções do Lambda afiliados. Para ter mais informações, consulte Criptografia de segredos.

Você pode usar o Secrets Manager para criar e gerenciar as versões na nuvem de seus segredos. Use o AWS IoT Greengrass para criar, gerenciar e implantar os recursos de segredos.

Importante

Recomendamos que você siga a melhor prática de alternar seus segredos no Secrets Manager. Em seguida, implante o grupo do Greengrass para atualizar as cópias locais dos seus segredos. Para ter mais informações, consulte Alternar os segredos do AWS Secrets Manager no Guia do usuário do AWS Secrets Manager.

Para disponibilizar um segredo no núcleo do Greengrass

Crie um segredo no Secrets Manager. Essa é a versão na nuvem de seu segredo, que é armazenado e gerenciado centralmente no Secrets Manager. As tarefas de gerenciamento incluem a alternância de valores de segredos e a aplicação de políticas de recursos.
Crie um recurso de segredo no AWS IoT Greengrass. Esse grupo é um tipo de recurso de grupo que faz referência ao segredo na nuvem pelo ARN. Você pode fazer referência a um segredo somente uma vez por grupo.
Configure seu conector ou sua função do Lambda. Você deve afiliar o recurso a uma função ou a um conector especificando parâmetros ou propriedades correspondentes. Isso permite que o usuário obtenha o valor do recurso de segredo implantado localmente. Para ter mais informações, consulte Usar segredos locais em conectores e funções do Lambda.
Implante o grupo do Greengrass. Durante a implantação, o AWS IoT Greengrass obtém o valor do segredo na nuvem e cria (ou atualiza) o segredo local no núcleo.

O Secrets Manager registra em log um evento no AWS CloudTrail sempre que o AWS IoT Greengrass recupera um valor de segredo. O AWS IoT Greengrass não registra em log nenhum evento relacionado à implantação ou ao uso de segredos locais. Para obter informações sobre as chamadas registradas em log pelo Secrets Manager, consulte Monitorar o uso dos seus segredos do AWS Secrets Manager no Guia do usuário do AWS Secrets Manager.

Incluir rótulos de preparação em recursos de segredos

O Secrets Manager usa rótulos de preparação para identificar versões específicas de um valor de segredo. Os rótulos de teste podem ser definidos pelo sistema ou pelo usuário. O Secrets Manager atribui o rótulo AWSCURRENT à versão mais recente do valor do segredo. Os rótulos de preparação geralmente são usados para gerenciar a alternância de segredos. Para obter mais informações sobre o versionamento de segredos do Secrets Manager, consulte Termos e conceitos importantes do AWS Secrets Manager no Guia do usuário do AWS Secrets Manager.

Os recursos de segredos sempre incluem o rótulo de preparação AWSCURRENT e podem incluir outros rótulos de preparação se necessários para uma função do Lambda ou um conector. Durante a implantação do grupo, o AWS IoT Greengrass recupera os valores dos rótulos de preparação referenciados no grupo e, em seguida, cria ou atualiza os valores correspondentes no núcleo.

Criar e gerenciar recursos de segredos (console)

Criar recursos de segredos (console)

No console do AWS IoT Greengrass, você cria e gerencia recursos de segredos na guia Segredos da página Recursos. Para obter tutoriais que criam um recurso de segredo e o adicionam a um grupo, consulte Como criar um recurso de segredo (console) e Conceitos básicos de conectores do Greengrass (console).

Um recurso de segredo na guia Segredo na página Recursos.

nota

Como alternativa, o console permite que você crie um segredo e um recurso de segredo ao configurar um conector ou uma função do Lambda. Você pode fazer isso na página Configurar parâmetros do conector ou na página Recursos da função do Lambda.

Gerenciar um recurso de segredo (console)

As tarefas de gerenciamento dos recursos de segredos em seu grupo do Greengrass incluem adicionar recursos de segredos ao grupo, remover recursos de segredos do grupo e alterar o conjunto de rótulos de preparação incluídos em um recurso de segredo.

Se você apontar para um segredo diferente do Secrets Manager, também deverá editar conectores que usem o segredo:

Na página de configuração do grupo, selecione Connectors (Conectores).
No menu de contexto do conector, selecione Edit (Editar).
A página Edit parameters (Editar parâmetros) exibe uma mensagem para informá-lo de que o ARN do segredo foi alterado. Para confirmar a alteração, selecione Save (Salvar).

Se você excluir um segredo no Secrets Manager, remova o recurso de segredode segredo correspondente do grupo e dos conectores e funções do Lambda que fazem referência a ele. Caso contrário, durante a implantação do grupo, AWS IoT Greengrass retornará um erro informando que o segredo não pode ser encontrado. Além disso, atualize o código da função do Lambda conforme necessário.

Criar e gerenciar recursos de segredos (CLI)

Criar recursos de segredos (CLI)

Na API do AWS IoT Greengrass, um segredo é um tipo de recurso de grupo. O exemplo a seguir cria uma definição de recurso com uma versão inicial que inclui um recurso de segredo chamado MySecretResource. Para obter um tutorial que cria um recurso de segredo e o adiciona a uma versão de grupo, consulte Conceitos básicos de conectores do Greengrass (CLI).

O recurso de segredo faz referência ao ARN do segredo do Secrets Manager correspondente e inclui dois rótulos de preparação, além de AWSCURRENT, que é sempre incluído.


aws greengrass create-resource-definition --name MyGreengrassResources --initial-version '{
    "Resources": [
        {
            "Id": "my-resource-id",
            "Name": "MySecretResource",
            "ResourceDataContainer": {
                "SecretsManagerSecretResourceData": {
                    "ARN": "arn:aws:secretsmanager:us-west-2:123456789012:secret:greengrass-SomeSecret-KUj89s",
                    "AdditionalStagingLabelsToDownload": [
                        "Label1",
                        "Label2"
                    ]
                }
            }
        }
    ]
}'

Gerenciar recursos de segredos (CLI)

Na API do AWS IoT Greengrass, essas alterações são implementadas usando versões.

A API do AWS IoT Greengrass usa versões para gerenciar grupos. As versões são imutáveis, portanto, para adicionar ou alterar componentes do grupo — por exemplo, os dispositivos cliente, as funções e os recursos do grupo — você deve criar versões de componentes novos ou atualizados. Em seguida, crie e implante uma versão do grupo que contenha a versão de destino de cada componente. Para saber mais sobre os grupos, consulte Grupos do AWS IoT Greengrass.

Por exemplo, para alterar o conjunto de rótulos de preparação para um recurso de segredo:

Crie uma versão de definição de recurso que contenha o recurso de segredo atualizado. O exemplo a seguir adiciona um terceiro rótulo de preparação ao recurso de segredo da seção anterior.

nota

Para adicionar mais recursos à versão, inclua-os na matriz Resources.


aws greengrass create-resource-definition --name MyGreengrassResources --initial-version '{
    "Resources": [
        {
            "Id": "my-resource-id",
            "Name": "MySecretResource",
            "ResourceDataContainer": {
                "SecretsManagerSecretResourceData": {
                    "ARN": "arn:aws:secretsmanager:us-west-2:123456789012:secret:greengrass-SomeSecret-KUj89s",
                    "AdditionalStagingLabelsToDownload": [
                        "Label1",
                        "Label2",
                        "Label3"
                    ]
                }
            }
        }
    ]
}'

Se o ID do recurso de segredo for alterado, atualize os conectores e as funções que usam o recurso de segredo. Nas novas versões, atualize o parâmetro ou a propriedade que corresponde ao ID de recurso. Se o ARN do segredo for alterado, você também deverá atualizar o parâmetro correspondente para quaisquer conectores que usem o segredo.

nota
O ID do recurso é um identificador arbitrário fornecido pelo cliente.
Crie um grupo de destino que contenha a versão de destino de cada componente que você deseja enviar para o núcleo.
Implante a versão de grupo.

Para obter um tutorial que mostra como criar e implantar recursos de segredos, conectores e funções, consulte Conceitos básicos de conectores do Greengrass (CLI).

Usar segredos locais em conectores e funções do Lambda

As funções do Lambda e os conectores do Greengrass usam segredos locais para interagir com serviços e aplicativos. O valor AWSCURRENT é usado por padrão, mas os valores dos outros rótulos de preparação incluídos no recurso de segredo também estão disponíveis.

Conectores e funções devem ser configurados para que possam acessar segredos locais. Isso afilia o recurso de segredo ao conector ou à função.

Conectores

Se um conector exige acesso a um segredo local, ele fornece parâmetros que você configura com as informações necessárias para acessar o segredo.

Para saber como fazer isso no console do AWS IoT Greengrass, consulte Conceitos básicos de conectores do Greengrass (console).
Para saber como fazer isso com a CLI do AWS IoT Greengrass, consulte Conceitos básicos de conectores do Greengrass (CLI).

Para obter informações sobre os requisitos para conectores individuais, consulte Conectores do Greengrass fornecidos pela AWS.

A lógica para acessar e usar o segredo está integrada ao conector.

Funções do Lambda

Para permitir que uma função do Lambda do Greengrass acesse um segredo local, configure as propriedades da função.

Para saber como fazer isso no console do AWS IoT Greengrass, consulte Como criar um recurso de segredo (console).
Para fazer isso na API do AWS IoT Greengrass, forneça as seguintes informações na propriedade ResourceAccessPolicies.
- ResourceId: o ID do recurso de segredo no grupo do Greengrass. Esse é o recurso que faz referência ao ARN do segredo do Secrets Manager correspondente.
- Permission: o tipo de acesso que a função tem ao recurso. Somente a permissão ro (somente leitura) tem suporte para recursos de segredos.
O exemplo a seguir cria uma função do Lambda que pode acessar o recurso de segredo MyApiKey.
```
aws greengrass create-function-definition --name MyGreengrassFunctions --initial-version '{
    "Functions": [
        {
            "Id": "MyLambdaFunction",
            "FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:myFunction:1",
            "FunctionConfiguration": {
                "Pinned": false,
                "MemorySize": 16384,
                "Timeout": 10,
                "Environment": {
                    "ResourceAccessPolicies": [
                        {
                            "ResourceId": "MyApiKey",
                            "Permission": "ro"
                        }                          
                    ],
                    "AccessSysfs": true
                }
            }
        }
    ]
}'
```
Para acessar segredos locais no runtime, as funções do Lambda do Greengrass chamam a função secretsmanager do cliente do get_secret_value no SDK do AWS IoT Greengrass Core (v1.3.0 ou posterior).

O exemplo a seguir mostra como usar o SDK do AWS IoT Greengrass Core para Python para obter um segredo. Ele transmite o nome do segredo para a função get_secret_value. O SecretId pode ser o nome ou o ARN do segredo do Secrets Manager (e não o recurso de segredo).
```
import greengrasssdk

secrets_client = greengrasssdk.client("secretsmanager")
secret_name = "greengrass-MySecret-abc"


def function_handler(event, context):
    response = secrets_client.get_secret_value(SecretId=secret_name)
    secret = response.get("SecretString")
```
Para segredos do tipo texto, a função get_secret_value retorna uma string. Para segredos do tipo binário, ela retorna uma string codificada em base64.

Importante
Certifique-se de que suas funções do Lambda definidas pelo usuário tratem os segredos com segurança e não registrem em log nenhum dado confidencial armazenado no segredo. Para obter mais informações, consulte Mitigate the Risks of Logging and Debugging Your Lambda Function no Guia do usuário do AWS Secrets Manager. Embora essa documentação se refira especificamente às funções de alternância, a recomendação também se aplica às funções do Lambda do Greengrass.

O valor atual do segredo é retornado por padrão. Essa é a versão à qual o rótulo de preparação AWSCURRENT está anexado. Para acessar uma versão diferente, transmita o nome do rótulo de preparação correspondente para o argumento VersionStage opcional. Por exemplo:
```
import greengrasssdk

secrets_client = greengrasssdk.client("secretsmanager")
secret_name = "greengrass-TestSecret"
secret_version = "MyTargetLabel"


# Get the value of a specific secret version
def function_handler(event, context):
    response = secrets_client.get_secret_value(
        SecretId=secret_name, VersionStage=secret_version
    )
    secret = response.get("SecretString")
```
Para obter outro exemplo de função que chame get_secret_value, consulte Crie um pacote de implantação para a função do Lambda.

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

Implantar segredos no núcleo

Como criar um recurso de segredo (console)