Como ativar a autenticação do TLS mútuo para APIs REST 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.

Pré-requisitos do TLS mútuo

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

Nomes de domínios personalizados

Para habilitar o TLS mútuo para uma API REST, é 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 Nome de domínio personalizado para APIs REST 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 são aceitos no armazenamento de confiança:

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:

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

Veja a seguir um exemplo da possível aparência de um arquivo .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 REST, é necessário usar um nome de domínio personalizado regional para sua API, com uma política de segurança TLS_1_2. Para saber mais sobre como escolher uma política de segurança, consulte Escolher uma política de segurança para o domínio personalizado da API REST no API Gateway.

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 apigateway create-domain-name --region us-east-2 \
    --domain-name api.example.com \
    --regional-certificate-arn arn:aws:acm:us-east-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
    --endpoint-configuration types=REGIONAL \
    --security-policy TLS_1_2 \
    --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:

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 apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreVersion',value='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 apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreUri',value=''

Solucionar problemas de TLS mútuo para a API REST

O tópico a seguir fornece orientações para a solução de erros e problemas que você pode encontrar ao ativar o TLS mútuo.

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.

Solucionar problemas de certificado incorreto devolvido

Ao migrar um certificado dedicado de um nome de domínio totalmente qualificado (FQDN) para um nome de domínio de cliente curinga, o API Gateway pode retornar o certificado para o FQDN em vez do nome de domínio curinga.

O comando a seguir mostra qual certificado está sendo retornado pelo API Gateway:

openssl s_client -connect hostname:port

Se o certificado resultante for para o FQDN, entre em contato com o AWS Support para abrir um tíquete.