Usar seu próprio certificado do ACM para TLS mútuo com o backend no API Gateway
Você pode configurar o API Gateway para apresentar seu próprio certificado assinado por uma CA aos serviços de backend. Importe seu certificado para o Gerenciador de certificados da AWS (ACM) ou emita um por meio da Autoridade de certificação privada da AWS. Em seguida, associe o ARN do certificado do ACM ao estágio da API.
Pré-requisitos
Antes de configurar um certificado de cliente do ACM, você deve ter o seguinte:
Acesso ao Gerenciador de certificados da AWS na mesma região da API.
Permissões do IAM:
acm:ImportCertificateeacm:DescribeCertificate(para a importação da Opção A),acm:RequestCertificate(para a Opção B) ouacm-pca:IssueCertificate,acm-pca:GetCertificateeacm:ImportCertificate(para a Opção C).Uma API REST implantada em um estágio.
Etapa 1: importar um certificado ou emitir um por meio da Autoridade de certificação privada da AWS
Você pode importar um certificado da PKI existente ou emitir um novo certificado por meio da Autoridade de certificação privada da AWS. Ambos os caminhos produzem um ARN de certificado do ACM que você usará na etapa seguinte.
nota
Os certificados públicos do ACM não são compatíveis com a autenticação de cliente do backend. Desde 11 de junho de 2025, o Gerenciador de certificados da AWS não emite mais certificados públicos com o uso estendido de chave (EKU) de clientAuth. Esse recurso exige esse EKU, portanto, use um certificado importado para o ACM ou emitido por meio da Autoridade de certificação privada da AWS.
nota
Crie o certificado do ACM na mesma região da AWS da API REST que o utilizará. Os certificados do ACM são recursos regionais, portanto, o certificado deve existir na região da API.
Opção A: importar da PKI existente
Para importar um certificado de cliente e sua chave privada para o ACM, execute o comando a seguir. Para obter mais informações, consulte Importar certificados no Manual do usuário do Gerenciador de certificados da AWS.
aws acm import-certificate \ --certificate fileb://client-cert.pem\ --private-key fileb://private-key.pem\ --certificate-chain fileb://ca-chain.pem\ --regionregion
O comando retorna o ARN do certificado do ACM. Registre esse valor para a próxima etapa.
Opção B: solicitar um certificado por meio da Autoridade de certificação privada da AWS (gerenciada pelo ACM)
Para solicitar um certificado privado que o ACM gerencia e pode renovar automaticamente, execute o comando a seguir. Consulte mais informações em Solicitar um certificado privado no Guia do usuário do Gerenciador de certificados da AWS.
aws acm request-certificate \ --domain-namewww.example.com\ --certificate-authority-arn arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/12345678-1234-1234-1234-123456789012\ --regionregion
O comando retorna o ARN do certificado do ACM. Registre esse valor para a próxima etapa.
Opção C: emitir por meio da Autoridade de certificação privada da AWS e importar para o ACM
Se precisar de controle direto sobre os parâmetros do certificado, como extensões personalizadas ou algoritmos de assinatura, você poderá emitir um certificado por meio da Autoridade de certificação privada da AWS e, depois, importá-lo para o ACM. Os certificados importados dessa maneira não são renovados automaticamente pelo ACM. Certifique-se de que o certificado atenda aos requisitos de certificado. Consulte mais informações sobre a emissão de certificados privados em Emitir um certificado da entidade final privado no Guia do usuário do Autoridade de certificação privada da AWS.
aws acm-pca issue-certificate \ --certificate-authority-arn arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/12345678-1234-1234-1234-123456789012\ --csr fileb://csr.pem\ --signing-algorithm SHA256WITHRSA \ --validity Value=365,Type=DAYS
Recuperar e importar o certificado
O comando issue-certificate retorna um ARN de certificado da Autoridade de certificação privada da AWS, e não um ARN do ACM. Para usar esse certificado com o API Gateway, recupere-o usando o aws acm-pca get-certificate e depois importe-o para o ACM usando aws acm import-certificate. A importação produz o ARN do certificado do ACM que você usará na próxima etapa. Ao executar aws acm import-certificate, defina --region como a região da API para que o certificado do ACM seja criado nela.
Etapa 2: configurar um estágio da API para usar o certificado do ACM
Depois de obter um ARN de certificado do ACM, configure o estágio da API para apresentar o certificado ao backend.
Como configurar um estágio (console)
Abra o console do API Gateway em https://console.aws.amazon.com/apigateway
. Escolha a API REST.
Escolha Estágios.
Na seção Detalhes do estágio, selecione Editar.
Em Certificado de cliente, selecione o certificado do ACM na lista suspensa.
Escolha Salvar alterações.
Como configurar um estágio (AWS CLI)
Execute o seguinte comando:
aws apigateway update-stage \ --rest-api-idabc123\ --stage-nameprod\ --patch-operations op='replace',path=/clientCertificateId,value=arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012
nota
O API Gateway usa o mesmo campo clientCertificateId tanto para certificados do ACM quanto para certificados gerados pelo API Gateway. Quando você fornece um ARN de certificado do ACM, o API Gateway detecta automaticamente o formato e usa o fluxo de trabalho gerenciado pelo ACM.
Etapa 3: verificar a configuração
Para verificar se o API Gateway envia o certificado ao backend, conclua as seguintes etapas:
O backend deve solicitar um certificado de cliente
O backend deve estar configurado para solicitar um certificado de cliente durante o handshake TLS. Se o backend não solicitar um certificado, o API Gateway não apresentará o certificado.
Invoque o endpoint da API.
Verifique se o backend recebe o certificado de cliente durante o handshake TLS.
Verifique se o backend aceita o certificado e retorna uma resposta bem-sucedida.
Se o backend rejeitar o certificado, verifique se a cadeia de certificados pode ser validada em relação ao repositório de confiança do backend.
Requisitos de certificado
O certificado de entidade final que você configurar deve atender aos requisitos a seguir.
| Requisito | Descrição |
|---|---|
| Comprimento máximo da cadeia | 5 certificados |
| Validity | O certificado não pode estar expirado nem ainda não estar válido quando você o configurar. |
| Região | O certificado do ACM deve estar na mesma região que a API |
| Conta | O certificado do ACM deve estar na mesma conta que a API |
| Uso estendido de chave (EKU) | Se presente, deve incluir clientAuth. Se ausente, o certificado será aceito. |
| Uso de chave (KU) | Se presente, deve incluir digitalSignature ou keyAgreement. Se ausente, o certificado será aceito. |
| Algoritmo de chave | Deve ser um dos seguintes: RSA 2048, RSA 3072, RSA 4096, ECDSA P-256 (EC_prime256v1), ECDSA P-384 (EC_secp384r1) ou ECDSA P-521 (EC_secp521r1). |
| Status do certificado do ACM | Deve ser ISSUED |
nota
O API Gateway não valida a cadeia de confiança entre o certificado de entidade final e os certificados intermediários. O API Gateway também não valida a finalidade do certificado nem as restrições básicas, como CA:TRUE, nos certificados intermediários. O backend realiza essas validações durante o handshake TLS.
Renovação e propagação do certificado
Quando um certificado é alterado no ACM, o API Gateway detecta a atualização e propaga automaticamente o novo certificado. Não é necessário reimplantar o estágio, e a API não apresenta tempo de inatividade durante a rotação.
A propagação do certificado é eventualmente consistente. Durante a atualização, o backend poderá receber o certificado antigo ou o novo até que a propagação seja concluída.
A forma como o certificado é renovado depende de como ele foi emitido:
Certificados emitidos por meio da Autoridade de certificação privada da AWS (gerenciada pelo ACM) (Opção B): o ACM renova esses certificados automaticamente. O API Gateway detecta a renovação e é atualizado automaticamente.
Certificados emitidos pela Autoridade de certificação privada da AWS e importados (Opção C): o ACM não renova automaticamente certificados importados. Você deve importar novamente o certificado renovado. Depois de importar novamente o certificado, o API Gateway detecta a alteração e é atualizado automaticamente.
Certificados importados da sua PKI (Opção A): você deve importar novamente o certificado renovado para o ACM. Depois de importar novamente o certificado, o API Gateway detecta a alteração e é atualizado automaticamente.
O ACM envia notificações de expiração de certificados por meio do Amazon EventBridge. Você pode usar essas notificações para configurar alarmes antes que um certificado expire.
Comportamento e limitações dos certificados do ACM
- Visualizar o certificado configurado
Os certificados do ACM não aparecem nas respostas das APIs
GetClientCertificateouGetClientCertificates. Para visualizar o ARN do certificado ACM configurado em um estágio, use GetStage. Para visualizar os detalhes do certificado, use as APIs do ACM DescribeCertificate e GetCertificate.- Reutilização entre estágios
Você pode anexar o mesmo certificado do ACM a vários estágios. Cada estágio faz referência ao certificado de forma independente por meio do ARN.
- As APIs de certificado de cliente não se aplicam aos certificados do ACM
Os certificados do ACM não são recursos gerenciados pelo API Gateway. As APIs
GetClientCertificate,UpdateClientCertificateeDeleteClientCertificateretornam umNotFoundExceptionquando são chamadas com um ARN de certificado do ACM. Use as APIs do ACM para gerenciar o ciclo de vida do certificado.- Limpeza automática da associação do certificado
Quando você remove um certificado do ACM de um estágio, atualiza um estágio para usar um certificado diferente ou exclui um estágio ou uma API REST, o API Gateway remove automaticamente a associação do certificado. Nenhuma ação manual é necessária.
- Excluir o certificado do ACM
O ACM não permite que você exclua um certificado enquanto o API Gateway tiver uma associação ativa com ele. Para excluir o certificado do ACM, primeiro remova-o de todos os estágios que fazem referência a ele.
