Cómo activar la autenticación TLS mutua para las API de REST en API Gateway

La autenticación TLS mutua requiere la autenticación bidireccional entre el cliente y el servidor. Con la TLS mutua, los clientes deben presentar certificados X.509 para verificar su identidad y acceder a su API. La TLS mutua es un requisito frecuente para el Internet de las cosas (IoT) y las aplicaciones entre empresas.

Puede utilizar TLS mutua junto con otras operaciones de autorización y autenticación compatibles con API Gateway. API Gateway reenvía los certificados que los clientes proporcionan a los autorizadores de Lambda y a las integraciones del backend.

Requisitos previos de la TLS mutua

Para configurar la TLS mutua necesita lo siguiente:

Nombres de dominio personalizados

Para habilitar la TLS mutua para una API REST, debe configurar un nombre de dominio personalizado para su API. Puede habilitar la TLS mutua para un nombre de dominio personalizado y, a continuación, proporcionar el nombre de dominio personalizado a los clientes. Para acceder a una API mediante un nombre de dominio personalizado que tenga habilitada la TLS mutua, los clientes deben presentar certificados en los que confíe en las solicitudes de API. Dispone de más información en Nombre de dominio personalizado para las API de REST en API Gateway.

Uso de certificados emitidos por AWS Certificate Manager

Puede solicitar un certificado de confianza pública directamente desde ACM o importar certificados públicos o autofirmados. Para configurar un certificado en ACM, vaya a ACM. Si desea importar un certificado, siga leyendo en la siguiente sección.

Uso de un certificado importado o de AWS Private Certificate Authority

Para utilizar un certificado importado en ACM o un certificado de AWS Private Certificate Authority con TLS mutua, API Gateway necesita un ownershipVerificationCertificate emitido por ACM. Este certificado de propiedad solo se utiliza para comprobar que dispone de permisos para utilizar el nombre de dominio. No se utiliza en el protocolo de enlace TLS. Si todavía no tiene un ownershipVerificationCertificate, vaya a https://console.aws.amazon.com/acm/ para configurarlo.

Este certificado deberá mantener su validez durante toda la vida útil del nombre de dominio. Si un certificado caduca y falla la renovación automática, se bloquearán todas las actualizaciones del nombre de dominio. Tendrá que actualizar el ownershipVerificationCertificateArn con un ownershipVerificationCertificate válido para poder realizar otros cambios. El ownershipVerificationCertificate no se puede utilizar como certificado de servidor para otro dominio de TLS mutua en API Gateway. Si un certificado se vuelve a importar directamente en ACM, el emisor debe ser el mismo.

Configuración del almacén de confianza

Los almacenes de confianza son archivos de texto cuya extensión es .pem. Son una lista de certificados de confianza procedentes de entidades de certificación. Para utilizar la TLS mutua, cree un almacén de confianza de certificados X.509 en los que confíe para acceder a su API.

En el almacén de confianza debe incluir la cadena de confianza completa, desde el certificado de entidad de certificación emisora hasta el certificado de entidad de certificación raíz. API Gateway acepta certificados de cliente emitidos por cualquier entidad de certificación presente en la cadena de confianza. Los certificados pueden ser de autoridades de certificación públicas o privadas. Los certificados pueden tener una longitud máxima de cadena de cuatro. También puede proporcionar certificados autofirmados. Se admiten los siguientes algoritmos en el almacén de confianza:

API Gateway valida una serie de propiedades de certificado. Puede utilizar autorizadores de Lambda para realizar comprobaciones adicionales cuando un cliente invoque una API, tales como verificar si se ha revocado un certificado. API Gateway valida las siguientes propiedades:

Carga del almacén de confianza a un bucket de Amazon S3 en un solo archivo

El siguiente es un ejemplo del aspecto que puede tener un archivo .pem.

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

El siguiente comando de la AWS CLI carga certificates.pem en el bucket de Amazon S3.

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

Configuración de la TLS mutua para un nombre de dominio personalizado

Para configurar la TLS mutua para una API de REST, debe usar un nombre de dominio personalizado regional para la API, con una política de seguridad de TLS_1_2. Para obtener más información sobre cómo se elige una política de seguridad, consulte Elección de una política de seguridad para el dominio personalizado de la API de REST en API Gateway.

Después de cargar su almacén de confianza en Amazon S3, puede configurar su nombre de dominio personalizado para que utilice TLS mutua. Pegue lo siguiente (incluidas las barras) en un 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

Después de crear el nombre de dominio, debe configurar los registros DNS y los mapeos de ruta base para las operaciones de la API. Para obtener más información, consulte Configuración de un nombre de dominio personalizado regional en API Gateway.

Invocar una API mediante un nombre de dominio personalizado que requiere la TLS mutua

Para invocar una API con la TLS mutua habilitada, los clientes deben presentar un certificado de confianza en la solicitud de la API. Cuando un cliente intenta invocar la API, API Gateway busca el emisor del certificado del cliente en el almacén de confianza. Para que API Gateway atienda la solicitud, en el almacén de confianza deben constar el emisor del certificado y la cadena de confianza completa hasta el certificado de entidad de certificación raíz.

El siguiente ejemplo de comando curl envía una solicitud a api.example.com, que incluye my-cert.pem en la solicitud. my-key.key es la clave privada del certificado.

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

Su API solo se invoca si su almacén de confianza confía en el certificado. Las siguientes condiciones provocarán que API Gateway no pueda completar el protocolo de enlace TLS y deniegue la solicitud con un código de estado 403. Si el certificado:

Actualización de su almacén de confianza

Para actualizar los certificados del almacén de confianza, cargue un nuevo paquete de certificados en Amazon S3. Después, puede actualizar el nombre de dominio personalizado para que utilice el certificado actualizado.

Utilice el control de versiones de Amazon S3 para mantener varias versiones de su almacén de confianza. Cuando actualiza el nombre de dominio personalizado para utilizar una nueva versión del almacén de confianza, API Gateway devuelve advertencias si los certificados no son válidos.

API Gateway produce advertencias de certificado solo cuando actualiza el nombre de dominio. API Gateway no le notifica si caduca un certificado cargado anteriormente.

El siguiente comando de la AWS CLI actualiza un nombre de dominio personalizado para utilizar una nueva versión del almacén de confianza.

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreVersion',value='abcdef123'

Deshabilitar la TLS mutua

Para deshabilitar la TLS mutua para un nombre de dominio personalizado, elimine el almacén de confianza del nombre de dominio personalizado, como se muestra en el siguiente comando.

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreUri',value=''

Solución de problemas de TLS mutuo para su API de REST

A continuación se proporcionan consejos para solucionar errores y problemas que puedan surgir al activar TLS mutuo.

Solución de problemas de advertencias de certificados

Cuando se crea un nombre de dominio personalizado con TLS mutua, API Gateway devuelve advertencias si los certificados del almacén de confianza no son válidos. Esto también puede ocurrir cuando se actualiza un nombre de dominio personalizado para que utilice un nuevo almacén de confianza. Las advertencias indican el problema con el certificado y el asunto del certificado que produjo la advertencia. La TLS mutua aún está habilitada en la API, pero es posible que algunos clientes no puedan acceder a su API.

Debe descodificar los certificados del almacén de confianza para identificar cuál de ellos ha producido la advertencia. Puede utilizar herramientas como openssl para descodificar los certificados e identificar sus asuntos.

El siguiente comando muestra el contenido de un certificado, incluido su asunto:

openssl x509 -in certificate.crt -text -noout

Actualice o elimine los certificados que produjeron advertencias y, a continuación, cargue un nuevo almacén de confianza en Amazon S3. Después de cargar el nuevo almacén de confianza, actualice el nombre de dominio personalizado para que utilice ese nuevo almacén de confianza.

Solución de problemas por conflictos de nombres de dominio

El error "The certificate subject <certSubject> conflicts with an existing certificate from a different issuer." significa que varias entidades de certificación han emitido un certificado para este dominio. Para cada asunto del certificado, solo puede haber un emisor en API Gateway para dominios de TLS mutua. Tendrá que obtener todos los certificados para ese asunto a través de un solo emisor. Si el problema se debe a un certificado que no está bajo su control pero puede demostrar la propiedad del nombre de dominio, contacte con AWS Support para abrir un ticket.

Solución de problemas por mensajes de estado de nombres de dominio

PENDING_CERTIFICATE_REIMPORT: esto significa que ha vuelto a importar un certificado en ACM y ha fallado la validación porque el nuevo certificado tiene un SAN (nombre alternativo de sujeto) que no está cubierto por el ownershipVerificationCertificate, o bien porque el asunto o los SAN del certificado no cubren el nombre de dominio. Es posible que haya algo que esté configurado incorrectamente o que se haya importado un certificado no válido. Debe volver a importar un certificado válido en ACM. Para obtener más información sobre la validación, consulte Validación de la propiedad de dominios.

PENDING_OWNERSHIP_VERIFICATION: esto significa que el certificado verificado previamente ha caducado y ACM no lo ha podido renovar automáticamente. Tendrá que renovar el certificado o solicitar otro nuevo. Dispone de más información sobre la renovación de certificados en la guía Solución de problemas de renovación de certificados administrados de ACM.

Resolución del problema de certificado devuelto incorrecto

Al migrar un certificado dedicado de un nombre de dominio completo (FQDN) a un nombre de dominio de cliente comodín, API Gateway puede devolver el certificado del FQDN en lugar del nombre de dominio comodín.

El siguiente comando muestra qué certificado devuelve API Gateway:

openssl s_client -connect hostname:port

Si el certificado resultante es para el FQDN, póngase en contacto con AWS Support para abrir un ticket.