Autenticação do TLS mútua para APIs HTTP no API Gateway

A autenticação TLS mútua requer autenticação bidirecional entre o cliente e o servidor. Com TLS mútuo, os clientes devem apresentar certificados X.509 para verificar sua identidade a fim de acessar sua API. O TLS mútuo é um requisito comum para a Internet das Coisas (IoT) e aplicações business-to-business.

É possível usar o TLS mútuo juntamente com outras operações de autorização e autenticação compatíveis com o API Gateway. O API Gateway encaminha os certificados que os clientes fornecem aos autorizadores do Lambda e às integrações de backend.

Importante

Por padrão, os clientes podem invocar sua API usando o endpoint execute-api gerado pelo API Gateway para sua API. Para garantir que os clientes possam acessar sua API somente usando um nome de domínio personalizado com TLS mútuo, desabilite o endpoint execute-api padrão. Para saber mais, consulte Desabilitar o endpoint padrão para APIs HTTP.

Pré-requisitos do TLS mútuo

Para configurar o TLS mútuo, você precisa de:

• Um nome de domínio personalizado

• Pelo menos um certificado configurado no AWS Certificate Manager para o seu nome de domínio personalizado

• Um armazenamento de confiança configurado e carregado no Amazon S3

Nomes de domínios personalizados

Para habilitar o TLS mútuo para uma API HTTP, é necessário configurar um nome de domínio personalizado para sua API. Você pode habilitar o TLS mútuo para um nome de domínio personalizado e, depois, fornecer o nome de domínio personalizado aos clientes. Para acessar uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado, os clientes devem apresentar certificados confiáveis em solicitações de API. Você pode encontrar essas informações em Nomes de domínio personalizados para APIs HTTP no API Gateway.

Uso de certificados emitidos pelo AWS Certificate Manager

É possível solicitar um certificado publicamente confiável diretamente do ACM ou importar certificados públicos ou autoassinados. Para configurar um certificado no ACM, acesse o ACM. Para importar um certificado, continue lendo na seção a seguir.

Usar um certificado importado ou AWS Private Certificate Authority

Para usar um certificado importado para o ACM ou um certificado do AWS Private Certificate Authority com TLS mútuo, o API Gateway precisa de um ownershipVerificationCertificate emitido pela ACM. Esse certificado de propriedade é utilizado apenas para verificar você se tem permissões para utilizar o nome de domínio. Ele não é usado para o handshake TLS. Se você ainda não tem um ownershipVerificationCertificate, acesse https://console.aws.amazon.com/acm/ para configurar um.

Você precisará manter esse certificado válido durante todo o tempo de vida do seu nome de domínio. Se um certificado expirar e a renovação automática falhar, todas as atualizações do nome de domínio serão bloqueadas. Você precisará atualizar o ownershipVerificationCertificateArn com um ownershipVerificationCertificate válido antes de poder fazer outras alterações. O ownershipVerificationCertificate não pode ser usado como um certificado de servidor para outro domínio de TLS mútuo no API Gateway. Se um certificado for reimportado diretamente para o ACM, o emissor deverá permanecer o mesmo.

Configuração do armazenamento de confiança

Os armazenamentos de confiança são arquivos de texto com extensão .pem. Eles são uma lista confiável de certificados de autoridades de certificação. Para usar TLS mútuo, crie um armazenamento confiável de certificados X.509 que podem acessar sua API.

Você deve incluir a cadeia de confiança completa, começando pelo certificado da autoridade de certificação emissora até o certificado CA, em seu armazenamento de confiança. O API Gateway aceita certificados de cliente emitidos por qualquer autoridade de certificação presente na cadeia de confiança. Os certificados podem ser de autoridades de certificação públicas ou privadas. Eles podem ter um tamanho máximo de cadeia de quatro. Você também pode fornecer certificados autoassinados. Os seguintes algoritmos de hash são aceitos no armazenamento de confiança:

• SHA-256 ou mais forte

• RSA-2048 ou mais forte

• ECDSA-256 ou mais forte

O API Gateway valida várias propriedades de certificado. É possível usar autorizadores do Lambda para executar verificações adicionais quando um cliente invoca uma API, incluindo verificar se um certificado foi revogado. O API Gateway valida as seguintes propriedades:

Validação	Descrição
Sintaxe X.509	O certificado deve atender aos requisitos da sintaxe X.509.
Integridade	O conteúdo do certificado não pode ter sido alterado do assinado pela autoridade de certificação do armazenamento confiável.
Validity	O período de validade do certificado deve ser atual.
Encadeamento de nomes/encadeamento de chaves	Os nomes e os assuntos dos certificados devem formar uma cadeia ininterrupta. Eles podem ter um tamanho máximo de cadeia de quatro.

Fazer upload do armazenamento de confiança para um bucket do Amazon S3 em um único arquivo

exemplo certificates.pem

-----BEGIN CERTIFICATE-----
<Certificate contents>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Certificate contents>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Certificate contents>
-----END CERTIFICATE-----
...

O comando da AWS CLI a seguir faz upload do certificates.pem para seu bucket do Amazon S3.

aws s3 cp certificates.pem s3://bucket-name

Configurar o TLS mútuo para um nome de domínio personalizado

Para configurar o TLS mútuo para uma API HTTP, é necessário usar um nome de domínio personalizado regional para sua API, com uma versão do TLS mínima de 1.2. Para saber mais sobre como criar e configurar um nome de domínio personalizado, consulte Configurar um nome de domínio regional personalizado no API Gateway.

nota

O TLS mútuo não é suportado para APIs privadas.

Depois de fazer upload do armazenamento de confiança para o Amazon S3, você pode configurar o nome de domínio personalizado para usar TLS mútuo. Cole o seguinte (barras incluídas) em um terminal:

aws apigatewayv2 create-domain-name \
    --domain-name api.example.com \
    --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
    --mutual-tls-authentication TruststoreUri=s3://bucket-name/key-name

Depois de criar o nome de domínio, é necessário configurar registros DNS e mapeamentos de caminho base para operações da API. Para saber mais, consulte Configurar um nome de domínio regional personalizado no API Gateway.

Invocar uma API usando um nome de domínio personalizado que requer TLS mútuo

Para invocar uma API com TLS mútuo habilitado, os clientes precisam apresentar um certificado confiável na solicitação de API. Quando um cliente tenta invocar a API, o API Gateway procura o emissor do certificado de cliente no seu armazenamento de confiança. Para que o API Gateway prossiga com a solicitação, o emissor do certificado e a cadeia de confiança completa até o certificado CA raiz devem estar no seu armazenamento de confiança.

O comando curl demonstrativo a seguir envia uma solicitação para api.example.com, que inclui my-cert.pem na solicitação. my-key.key é a chave privada para o certificado.

curl -v --key ./my-key.key --cert ./my-cert.pem api.example.com

Sua API será invocada somente se o seu armazenamento de confiança confiar no certificado. As seguintes condições farão com que o API Gateway falhe no handshake TLS e negue a solicitação com um código de status 403. Se seu certificado:

• não é confiável

• expirou

• não usa um algoritmo compatível

nota

O API Gateway não verifica se um certificado foi revogado.

Atualizar o armazenamento de confiança

Para atualizar os certificados no armazenamento de confiança, faça upload de um novo pacote de certificados para o Amazon S3. Em seguida, você poderá atualizar o nome de domínio personalizado para usar o certificado atualizado.

Use o Versionamento do Amazon S3 para manter várias versões do armazenamento de confiança. Quando o nome de domínio personalizado é atualizado para usar uma nova versão de armazenamento de confiança, o API Gateway exibirá avisos se os certificados forem inválidos.

O API Gateway produz avisos de certificado somente quando o nome de domínio é atualizado. O API Gateway não o notificará se um certificado carregado anteriormente expirar.

O comando da AWS CLI a seguir atualiza um nome de domínio personalizado para usar uma nova versão de armazenamento confiável.

aws apigatewayv2 update-domain-name \
    --domain-name api.example.com \
    --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
    --mutual-tls-authentication TruststoreVersion='abcdef123'

Desativar o TLS mútuo

Para desativar o TLS mútuo para um nome de domínio personalizado, remova o armazenamento de confiança do nome de domínio personalizado, conforme mostrado no comando a seguir.

aws apigatewayv2 update-domain-name \
    --domain-name api.example.com \
    --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
    --mutual-tls-authentication TruststoreUri=''

Solução de problemas de avisos de certificado

Ao criar um nome de domínio personalizado com TLS mútuo, o API Gateway exibirá avisos se os certificados no armazenamento de confiança não forem válidos. Isso também pode ocorrer ao atualizar um nome de domínio personalizado para usar um novo armazenamento de confiança. Os avisos indicam o problema com o certificado e o assunto que produziu o aviso. O TLS mútuo ainda está habilitado para sua API, mas alguns clientes podem não conseguir acessar a API.

Para identificar o certificado que produziu o aviso, é necessário decodificar os certificados em seu armazenamento de confiança. É possível usar ferramentas como openssl para decodificar os certificados e identificar os assuntos.

O comando a seguir exibe o conteúdo de um certificado, incluindo o assunto.

openssl x509 -in certificate.crt -text -noout

Atualize ou remova os certificados que produziram avisos e, depois, faça upload de um novo armazenamento de confiança para o Amazon S3. Após o upload do novo armazenamento de confiança, atualize o nome de domínio personalizado para usar o novo armazenamento de confiança.

Solução de problemas de conflitos de nomes de domínios

O erro "The certificate subject <certSubject> conflicts with an existing certificate from a different issuer." significa que mais de uma autoridade de certificação emitiu um certificado para esse domínio. Para cada entidade no certificado, pode haver somente um emissor no API Gateway para domínios do TLS mútuos. Você precisará obter todos os seus certificados para esse assunto por meio de um único emissor. Se o problema for com um certificado sobre o qual você não tem controle, e você é capaz de provar que é o dono do nome de domínio, entre em contato com AWS Support para abrir um ticket.

Solução de problemas de mensagens de status de nomes de domínio

PENDING_CERTIFICATE_REIMPORT: isso significa que você reimportou um certificado para o ACM e ele falhou na validação porque o novo certificado tem um SAN (nome alternativo de entidade) que não é coberto pelo ownershipVerificationCertificate ou o assunto ou os SANs no certificado não cobrem o nome de domínio. Algo pode estar configurado incorretamente ou um certificado inválido foi importado. Você precisa reimportar um certificado válido para o ACM. Para obter mais informações sobre a validação, consulte Validação da propriedade de domínios.

PENDING_OWNERSHIP_VERIFICATION: isso significa que seu certificado verificado anteriormente expirou e o ACM não conseguiu renová-lo automaticamente. Você precisará renovar o certificado ou solicitar um novo certificado. Mais informações sobre renovação de certificados podem ser encontradas no guia Solução de problemas de renovação de certificados gerenciados do ACM.