Adición de soporte de mTLS a despliegues de API
Descubra cómo utilizar una política de solicitud para agregar soporte de mTLS a despliegues de API con API Gateway.
Los gateways de API que cree con el servicio API Gateway están protegidos mediante cifrado y verificación TLS. Un gateway de API presenta un certificado de servidor a un cliente de API durante un establecimiento de comunicación de TLS, lo que permite al cliente de API validar la autenticidad del gateway de API. El proceso de autenticación del cliente de API del gateway de API se conoce como TLS unidireccional.
En muchas situaciones, solo desea permitir que los clientes de API autenticados accedan a una API. En estas situaciones, desea que el gateway de API valide la autenticidad de un cliente de API, verificando el certificado TLS presentado por el cliente de API. El proceso de autenticación del gateway de API del cliente de API se conoce como TLS mutua (mTLS).
Con mTLS, tanto el gateway de API como el cliente de API intercambian y verifican certificados durante el establecimiento de comunicación de TLS. El gateway de API verifica el certificado TLS presentado por el cliente de API mediante certificados raíz de autoridad de certificación (CA) personalizados y paquetes de CA personalizados de certificados raíz e intermedios. Las CA personalizadas y los grupos de CA se almacenan en el almacén de confianza del gateway de API, junto con un grupo de CA por defecto que contiene certificados de CA públicas conocidas. Tenga en cuenta que en un establecimiento de comunicación de mTLS, el gateway de API solo utiliza CA personalizadas y grupos de CA personalizados para verificar los certificados de cliente de API. El gateway de API no utiliza el grupo de autoridades de certificación por defecto para verificar los certificados de cliente de API. Por lo tanto, si desea que un gateway de API soporte mTLS, debe agregar CA y grupos de CA personalizados al almacén de confianza del gateway de API (consulte Personalización de almacenes de confianza para la verificación de certificados TLS).
Para obtener un control adicional, también puede especificar que los certificados presentados por los clientes de API a un gateway de API deben contener valores concretos en los campos Dirección de correo electrónico, URL o Nombre de dominio del certificado. Si especifica valores para estos campos al configurar mTLS para un gateway de API, el gateway de API rechazará las solicitudes de los clientes de API que presenten certificados que no los contengan. Si no especifica valores para estos campos al configurar mTLS, el gateway de API aceptará todas las solicitudes de los clientes de API siempre que el certificado sea válido. Puede especificar hasta 10 valores por defecto para cada despliegue de API (puede cambiar este límite interno).
Después de un establecimiento de comunicación mTLS correcto entre el gateway de API y un cliente de API, se guarda una versión codificada por Base64 del certificado presentado por el cliente de API en la tabla de contexto request.cert
como una variable de contexto denominada request.cert[client_base64]
. Al definir un despliegue de API, puede hacer referencia al certificado con el formato ${request.cert[client_base64]}
(consulte Adición de variables de contexto a políticas y definiciones de backend HTTP). Tenga en cuenta que si un cliente de API presenta un certificado TLS de más de 8 KB de tamaño (después de haber sido codificado con Base64), el certificado no se guarda como una variable de contexto.
Puede utilizar una política de solicitud en la especificación de despliegue de API para agregar soporte de mTLS a una API (consulte Adición de políticas de solicitud y políticas de respuesta a especificaciones de despliegue de API). La política de solicitud de mTLS se aplica globalmente a todas las rutas de una especificación de despliegue de API.
- Si un cliente de API presenta un certificado TLS a un gateway de API y el despliegue de API no está activado para mTLS, el gateway de API simplemente ignora el certificado TLS que se ha presentado. La variable de contexto
request.cert[client_base64]
no está definida en esta situación. - Si un gateway de API no puede validar el certificado TLS presentado por un cliente de API, el gateway de API rechaza la solicitud con un código de respuesta de estado de error HTTP 401.
- Si un gateway de API utiliza un grupo de autoridades de certificación personalizado para validar el certificado TLS presentado por un cliente de API, no se pueden recorrer más de tres certificados de autoridad de certificación en ningún momento de la cadena de certificados durante la validación. En otras palabras, para ser válido, un certificado de CA de la cadena debe estar firmado directamente por una CA personalizada presente en el almacén de confianza del gateway de API o no debe estar a más de dos certificados intermedios de un certificado que haya sido firmado por dicha CA personalizada. Póngase en contacto con nosotros si desea permitir más certificados intermedios.
Puede agregar una política de solicitud mTLS a una especificación de despliegue de API mediante:
- uso de la consola
- edición de un archivo JSON
Uso de la consola para agregar políticas de solicitud de mTLS
Para agregar una política de solicitud mTLS a una especificación de despliegue de API mediante la consola:
-
Cree o actualice un despliegue de API con la consola, seleccione la opción Desde cero e introduzca los detalles en la página Información básica.
Para obtener más información, consulte Despliegue de una API en un gateway de API mediante la creación de un despliegue de API y Actualización de un gateway de API.
-
En la sección Políticas de solicitud de API de la página Información básica, en Mutual-TLS, seleccione la opción Activar mTLs y, opcionalmente, especifique:
- Nombre alternativo de asunto (SAN) / Nombre común: valores que deben aparecer en uno o más de los siguientes campos del certificado presentado por el cliente de API para que el gateway de API acepte solicitudes del cliente:
- Dirección de correo electrónico
- URL
- Nombre del Dominio
Por ejemplo,
example.com
. Puede especificar hasta 10 valores por defecto (puede cambiar este límite interno). La validación no distingue entre mayúsculas y minúsculas.Puede incluir un comodín asterisco (*) al inicio y/o al final de cada valor para representar cero, uno o más caracteres. No puede incluir un comodín asterisco en el medio del valor. Por ejemplo:
*.example.com
coincide conserver.example.com
server.example.*
coincide conserver.example.com
*.example.*
coincide conserver.example.com
server.*.com
no coincide conserver.example.com
porque el comodín no puede estar en el medio del valor
Si especifica valores al configurar mTLS para un despliegue de API, el gateway de API rechazará las solicitudes de clientes de API que presenten certificados que no los contengan. Si no especifica valores al configurar mTLS, el gateway de API aceptará todas las solicitudes de los clientes de API que proporcionen el certificado es válido.
- Nombre alternativo de asunto (SAN) / Nombre común: valores que deben aparecer en uno o más de los siguientes campos del certificado presentado por el cliente de API para que el gateway de API acepte solicitudes del cliente:
- Seleccione Revisar para revisar los detalles introducidos para el despliegue de API.
- Seleccione Crear o Guardar cambios para crear o actualizar el despliegue de API.
- (Opcional) Confirme que la API se ha desplegado correctamente llamándola. Para ello, consulte Llamada a una API desplegada en un gateway de API.
Edición de un archivo JSON para agregar políticas de solicitud de mTLS
Pasos para agregar una política de solicitud mTLS a una especificación de despliegue de API en un archivo JSON:
-
Con el editor de JSON de su elección, edite la especificación de despliegue de API existente a la que desea agregar soporte de mTLS o cree una nueva especificación de despliegue de API (consulte Creación de una especificación de despliegue de API).
Por ejemplo, la siguiente especificación básica de despliegue de API define una función sencilla de Hello World sin servidor en OCI Functions como un único backend:
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
-
Para especificar una política de solicitud de mTLS que se aplica globalmente a todas las rutas de un despliegue de API:
-
Inserte una sección
requestPolicies
antes de la secciónroutes
si no existe ninguna. Por ejemplo:{ "requestPolicies": {}, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
-
Añada la siguiente política
mutualTLS
a la nueva secciónrequestPolicies
para aplicarla de forma global a todas las rutas de un despliegue de API:{ "requestPolicies": { "mutualTls":{ "isVerifiedCertificateRequired": true|false, "allowedSans": [<list-of-values>] } }, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
donde:
"isVerifiedCertificateRequired": true|false
, estrue
ofalse
, lo que indica si mTLS está activado para el despliegue de API. Si no se especifica, el valor por defecto esfalse
."allowedSans": [<list-of-values>]
es una lista opcional de valores separados por comas que debe aparecer en uno o más de los siguientes campos del certificado presentado por el cliente de API para que el gateway de API acepte solicitudes del cliente:- Dirección de correo electrónico
- URL
- Nombre del Dominio
Por ejemplo,
example.com
. Puede especificar hasta 10 valores por defecto (puede cambiar este límite interno). La validación no distingue entre mayúsculas y minúsculas.Puede incluir un comodín asterisco (*) al inicio y/o al final de cada valor para representar cero, uno o más caracteres. No puede incluir un comodín asterisco en el medio del valor. Por ejemplo:
*.example.com
coincide conserver.example.com
server.example.*
coincide conserver.example.com
*.example.*
coincide conserver.example.com
server.*.com
no coincide conserver.example.com
porque el comodín no puede estar en el medio del valor
Si especifica valores al configurar mTLS para un despliegue de API, el gateway de API rechazará las solicitudes de clientes de API que presenten certificados que no los contengan. Si no especifica valores al configurar mTLS, el gateway de API aceptará todas las solicitudes de los clientes de API que proporcionen el certificado es válido.
Por ejemplo:
{ "requestPolicies": { "mutualTls":{ "isVerifiedCertificateRequired": true, "allowedSans": [ "example.com", "example.co.uk" ] } }, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
-
- Guarde el archivo JSON que contiene la especificación de despliegue de API.
-
Utilice la especificación de despliegue de API al crear o actualizar un despliegue de API de las siguientes formas:
- Especificando el archivo JSON en la consola al seleccionar la opción Cargar API.
- Especificando el archivo JSON en una solicitud para la API REST de gateway de API.
Para obtener más información, consulte Despliegue de una API en un gateway de API mediante la creación de un despliegue de API y Actualización de un gateway de API.
- (Opcional) Confirme que la API se ha desplegado correctamente llamándola. Para ello, consulte Llamada a una API desplegada en un gateway de API.