Gerencie chaves de API para cargas de trabalho sensíveis à segurança

AWS Secrets Manager ajuda você a gerenciar, recuperar e alternar credenciais de banco de dados, credenciais de aplicativos, tokens OAuth, chaves de API e outros segredos ao longo de seus ciclos de vida. Esta página fornece orientação prescritiva para gerenciar chaves de API e credenciais de terceiros em cargas de trabalho sensíveis à segurança. Combine a rotação automática com AWS KMS chaves gerenciadas pelo cliente e políticas de IAM com menos privilégios. Configure também o acesso ao VPC endpoint para minimizar a janela de exposição e o raio de explosão de uma credencial comprometida.

Armazene chaves de API em AWS Secrets Manager

Esta seção descreve como estruturar seus segredos de chave de API para otimizar a rotação e a recuperação. Armazene cada chave de API como um segredo separado com um valor JSON estruturado. Com essa estrutura, seu aplicativo pode recuperar campos individuais e o Secrets Manager pode passar os valores corretos para uma função de rotação.

O exemplo a seguir mostra uma estrutura JSON comum para segredos de chave de API de terceiros. Os campos reais dependem dos requisitos do seu provedor. Consulte a documentação do provedor para ver as credenciais e os metadados específicos que você precisa armazenar.

{
  "apiKey": "your-api-key-value",
  "apiKeyId": "key-identifier",
  "endpoint": "https://api.example.com/v1",
  "provider": "example-service"
}

Exemplo de estrutura secreta para chaves de API

Campo	Valor de exemplo	Finalidade
apiKey	sk_live_abc123...	O valor da credencial que seu aplicativo usa para se autenticar com a API de terceiros.
apiKeyId	key_001	Identificador da chave do lado do provedor. Usado durante a rotação para criar uma nova chave e excluir a antiga.
endpoint	https://api.example.com/v1	URL do endpoint da API. Armazene com a chave para que a recuperação retorne tudo o que o aplicativo precisa para se conectar.
provider	stripe	Nome do provedor. Útil para a lógica de funções de marcação, filtragem e rotação que manipula vários provedores.

Marque cada segredo com metadados para dar suporte às condições da política do IAM e à filtragem organizacional. Por exemplo, você pode marcar segredos com a equipe proprietária, o ambiente e o escopo de conformidade usando o console AWS CLI or:

aws secretsmanager tag-resource \
    --secret-id prod/payments/stripe-api-key \
    --tags Key=Team,Value=payments Key=Environment,Value=production \
           Key=Provider,Value=stripe Key=Compliance,Value=pci-dss

Para obter mais informações sobre como criar segredos, consulteCrie um AWS Secrets Manager secret.

Configuração de criptografia

O Secrets Manager criptografa cada valor secreto em repouso usando uma AWS KMS chave. Para cargas de trabalho sensíveis à segurança, escolha a chave de criptografia com base em seus requisitos de conformidade e controle de acesso.

Opções de chave KMS para segredos de chave de API

Tipo de chave	Quando usar	Considerações sobre segurança
AWS chave gerenciada (aws/secretsmanager)	Padrão para a maioria das cargas de trabalho. Sem custo adicional ou sobrecarga de gerenciamento de chaves.	A política de chaves é restrita somente às operações do Secrets Manager e não pode ser modificada. Não pode ser usado para acesso entre contas.
Chave gerenciada pelo cliente	Requisitos de conformidade (por exemplo, PCI DSS, HIPAA, SOC 2 ou outros padrões aplicáveis). Cross-account compartilhamento secreto. Requisitos de auditoria de uso de chaves.	Você controla a política de chaves. Você pode restringir quais diretores podem descriptografar. Você pode desativar ou programar a exclusão da chave independentemente do segredo. Fornece uma trilha de auditoria independente.

Para cargas de trabalho sensíveis à segurança, use uma chave gerenciada pelo cliente com as seguintes principais condições de política:

• kms:ViaService— Restrinja o uso de chaves às solicitações originadas do Secrets Manager (secretsmanager.<region>.amazonaws.com).

• kms:EncryptionContext:SecretARN— Restrinja a decodificação a ARNs secretos específicos combinando o contexto de criptografia do Secrets Manager.

• Chaves separadas por limite de conformidade — Use AWS KMS chaves diferentes para segredos em diferentes escopos de conformidade (por exemplo, PCI em comparação com não-PCI).

Para obter uma explicação completa do processo de criptografia e decodificação, consulteCriptografia e decodificação secretas em AWS Secrets Manager.

Rotação automática para chaves de API

A rotação automática reduz a janela de exposição das credenciais comprometidas. O Secrets Manager invoca uma função do Lambda em um cronograma. A função cria uma nova chave de API no provedor, atualiza o valor secreto e exclui a chave antiga.

O Secrets Manager fornece funções gerenciadas de rotação para alguns fornecedores terceirizados por meio de segredos externos gerenciados. Para obter mais informações sobre esse recurso e a lista de provedores compatíveis, consulteParceiros de segredos externos gerenciados. Para provedores sem suporte de rotação gerenciada, você implementa uma função de rotação personalizada do Lambda que chama a API do provedor para criar e excluir chaves.

Ciclo de vida da função de rotação

Uma função Lambda de rotação implementa quatro etapas. O Secrets Manager invoca a função uma vez para cada etapa, passando um Step parâmetro. Se alguma etapa falhar, o Secrets Manager repetirá automaticamente toda a rotação.

Etapas de rotação para chaves de API

Etapa	Ação para chaves de API	Tratamento de falhas
createSecret	Chame a API do provedor para criar uma nova chave. Armazene o novo valor da chave no Secrets Manager com o rótulo AWSPENDING de teste.	Se a criação da chave falhar, a rotação não passará para a próxima etapa. A chave existente permanece ativa comoAWSCURRENT.
setSecret	Para chaves de API criadas no provedor, essa etapa geralmente é autônoma. Essa etapa é usada quando uma chave aleatória é gerada no Secrets Manager e precisa ser definida no provedor — o que não é o fluxo típico de chaves da API.	Se essa etapa falhar, a rotação não prosseguirátestSecret.
testSecret	Recupere o AWSPENDING valor do Secrets Manager e faça uma chamada de API de teste para o provedor para verificar se a nova chave funciona.	Se o teste falhar, exclua a chave pendente no provedor e gere uma exceção.
finishSecret	Vá AWSCURRENT para a nova chave. A chave antiga passa paraAWSPREVIOUS. Opcionalmente, exclua a chave antiga no provedor.	Se a atualização da etiqueta falhar, a rotação não será concluída. A nova chave existe, mas ainda não está rotuladaAWSCURRENT.

Para obter o modelo completo da função de rotação e as diretrizes de implementação, consulteFunção de alternância do Lambda.

Configuração do cronograma de rotação

Defina o intervalo de rotação com base em seus requisitos de conformidade e políticas internas de segurança. Consulte os padrões de conformidade aplicáveis à sua carga de trabalho para determinar a frequência de rotação apropriada.

Use uma janela de rotação para controlar quando a rotação ocorre. Isso evita que a rotação funcione durante períodos de pico de tráfego ou janelas de manutenção:

aws secretsmanager rotate-secret \
    --secret-id prod/payments/stripe-api-key \
    --rotation-rules '{
        "ScheduleExpression": "cron(0 4 ? * SUN *)",
        "Duration": "2h"
    }'

Para saber a sintaxe da expressão de agendamento, consulteProgramação de alternância.

Recupere segredos com eficiência

O Secrets Manager suporta 10.000 transações por segundo em GetSecretValue chamadas. A maioria dos aplicativos não sofre limitação. Para aplicativos com volumes de chamadas muito altos ou caminhos sensíveis à latência, use uma solução de cache para reduzir as chamadas de API e melhorar os tempos de resposta.

O Secrets Manager fornece clientes de cache para vários idiomas, bem como uma extensão Lambda que armazena segredos localmente no ambiente de execução. Para obter mais informações sobre as opções de armazenamento em cacheObtenha um segredo do Secrets Manager usando Java com armazenamento em cache no lado do cliente, consulteObtenha um segredo do Secrets Manager usando Python com armazenamento em cache no lado do cliente, e. Obter um segredo do Secrets Manager usando Go com armazenamento em cache no lado do cliente

Para todos os padrões de acesso, configure políticas do IAM que restrinjam secretsmanager:GetSecretValue aos segredos específicos de que cada aplicativo precisa:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "secretsmanager:GetSecretValue",
    "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/payments/*",
    "Condition": {
      "StringEquals": {
        "aws:ResourceTag/Environment": "production"
      }
    }
  }]
}

Fortalecimento da segurança para cargas de trabalho confidenciais

As práticas a seguir fornecem defesa aprofundada para chaves de API em ambientes com requisitos rígidos de segurança (por exemplo, PCI DSS, SOC 2, HIPAA ou outras estruturas de conformidade aplicáveis):

Restrinja o acesso à rede com endpoints VPC

Crie um endpoint VPC de interface para o Secrets Manager para que a recuperação secreta nunca atravesse a Internet pública. Aplique uma política de endpoint que restrinja quais segredos podem ser acessados por meio do endpoint. Para obter mais informações, consulte Usando um AWS Secrets Manager VPC endpoint.

Aplique políticas de recursos aos segredos

Anexe uma política de recursos a cada segredo que negue explicitamente o acesso de diretores fora da sua conta ou fora de endpoints VPC específicos. Isso fornece um segundo limite de autorização independente das políticas de identidade do IAM.

Monitore o acesso secreto com

registra automaticamente todas as chamadas da API do Secrets Manager GetSecretValuePutSecretValue, incluindo, RotateSecret e. Para segredos sensíveis à segurança, crie um CloudWatch alarme da Amazon que seja acionado em GetSecretValue chamadas inesperadas — por exemplo, chamadas de endereços IP de origem não reconhecidos ou diretores do IAM.

Use AWSPREVIOUS para uma rotação elegante

Durante a rotação, o Secrets Manager mantém o valor da chave anterior com o rótulo AWSPREVIOUS de teste. Se seu provedor invalidar a chave anterior quando uma nova chave for criada, configure seu aplicativo para usar AWSPREVIOUS se AWSCURRENT retornar um erro de autenticação. Isso evita o tempo de inatividade durante o breve intervalo entre a criação da chave e a atualização da etiqueta.

Valide as políticas de recursos antes de anexar

Segredos sem uma política de recursos já bloqueiam o acesso público. Ao anexar uma política de recursos ao seu segredo, use a ValidateResourcePolicy API para garantir que sua política não conceda amplo acesso público. Você também pode usar o BlockPublicPolicy parâmetro with PutResourcePolicy para evitar a anexação de políticas que concedam acesso público. Use a chave de aws:PrincipalOrgID condição nas políticas de recursos para impedir o acesso de diretores fora da sua organização.

Perguntas frequentes

Esta seção responde a perguntas comuns sobre rotação de chaves de API e gerenciamento de segredos em AWS Secrets Manager.

Como faço para lidar com o período de sobreposição durante a rotação?

Isso só é necessário se o provedor invalidar a chave existente quando uma nova chave for criada. Se o provedor oferecer suporte a várias chaves ativas simultaneamente, ambas funcionarão durante o período de rotação sem a lógica de fallback do lado do aplicativo. Para provedores que invalidam a chave antiga, configure seu aplicativo para tentar novamente AWSPREVIOUS se a chave atual retornar um erro 401 ou 403. Exclua a chave antiga no provedor na finishSecret etapa somente depois de confirmar que a nova chave está funcionando.

E se meu provedor não oferecer suporte à criação de chaves programáticas?

Se o provedor exigir a criação manual de chaves (por meio de um console web, por exemplo), você não poderá automatizar totalmente a rotação. Em vez disso, use uma função de rotação que envie uma notificação (por meio do Amazon Simple Notification Service) quando a rotação for concluída, solicitando que um operador crie a chave manualmente e atualize o valor secreto. Defina o cronograma de rotação de acordo com seu requisito de rotação de conformidade e use CloudWatch os alarmes da Amazon ativados days_since_last_rotation para detectar rotações perdidas.

Como evito a limitação da API ao recuperar segredos?

O Secrets Manager suporta 10.000 transações por segundo emGetSecretValue. A maioria dos aplicativos não sofre limitação. Se seu aplicativo fizer um volume excepcionalmente alto de chamadas, use um cliente de cache ou a extensão Lambda Parameters and Secrets. Eles armazenam em cache o valor secreto na memória e são atualizados periodicamente, reduzindo o número de chamadas de API. Defina o TTL do cache para um valor menor que seu intervalo de rotação para que o aplicativo pegue novas chaves após a rotação.

Devo usar um segredo por ambiente ou um segredo com versões?

Use segredos separados para cada ambiente (por exemplo, prod/payments/stripe edev/payments/stripe). Isso permite diferentes políticas de IAM, programações de rotação e chaves de criptografia por ambiente. As versões secretas (rótulos de teste) são para gerenciamento do estado de rotação, não para separação de ambientes.