DEV Community

Cover image for Cómo Testear APIs que Requieren Certificados de Cliente (mTLS) en Apidog
Roobia
Roobia

Posted on • Originally published at apidog.com

Cómo Testear APIs que Requieren Certificados de Cliente (mTLS) en Apidog

Envías una solicitud a la API de un socio con un token válido y una estructura correcta, pero recibes un error de handshake TLS. El endpoint no está rechazando tu clave API: está pidiendo a tu cliente que demuestre su identidad con un certificado antes de que salga cualquier solicitud HTTP. Eso es TLS mutuo (mTLS).

Prueba Apidog hoy

Esta guía muestra cómo configurar certificados de cliente y certificados CA en Apidog para probar APIs protegidas con mTLS. Configurarás un certificado y una clave privada para un host, añadirás una CA para confiar en certificados autofirmados o internos y enviarás solicitudes HTTPS que Apidog firmará automáticamente. Si necesitas repasar los errores de certificados, consulta esta guía sobre verificación de certificados SSL. Para los fundamentos del protocolo, revisa la referencia de TLS de MDN.

Qué es TLS mutuo y por qué algunas APIs lo exigen

En HTTPS estándar, la confianza es unidireccional:

  1. El servidor presenta su certificado.
  2. El cliente valida ese certificado.
  3. Se establece una conexión cifrada.
  4. El servidor autentica al cliente mediante una clave API, OAuth o un token enviado en la solicitud.

Con mTLS, la confianza es bidireccional. Durante el handshake, el servidor también solicita un certificado al cliente. Si el certificado de cliente no es válido o no está emitido por una CA aceptada por el servidor, la conexión falla antes de enviar:

  • Encabezados HTTP.
  • Tokens OAuth.
  • Claves API.
  • Cuerpo de la solicitud.

mTLS es habitual en estos casos:

  • Banca y pagos: APIs de banca abierta o procesadores de pagos pueden requerir certificado de cliente además de OAuth. La documentación de Stripe describe modelos de credenciales por capas para endpoints financieros sensibles.
  • Tráfico interno entre servicios: en arquitecturas de confianza cero, los servicios prueban su identidad con certificados.
  • APIs B2B de socios: el socio emite un certificado durante el proceso de incorporación para limitar el acceso a clientes registrados.

Si una API requiere OAuth y mTLS, ambas capas se complementan. RFC 8705 define cómo vincular tokens OAuth a certificados de cliente mediante TLS mutuo.

En Apidog, configura cada mecanismo en su lugar:

Mecanismo Dónde configurarlo
Certificado de cliente para mTLS Certificados
Certificado CA para confiar en el servidor Certificados
Clave API, Bearer token, OAuth o Basic Auth Autorización

Cómo Apidog asigna certificados por host

Apidog configura certificados globalmente y los asocia a un host. No necesitas seleccionar un certificado para cada solicitud.

Cuando envías una solicitud HTTPS, Apidog:

  1. Obtiene el host de la URL.
  2. Busca un certificado configurado para ese host o patrón.
  3. Adjunta el certificado durante el handshake TLS si encuentra una coincidencia.
  4. Envía la solicitud HTTP solo después de completar el handshake.

Hay dos tipos de certificados:

  • Certificado de cliente: demuestra la identidad de tu cliente ante el servidor mTLS.
  • Certificado CA: añade confianza para una autoridad certificadora que Apidog no reconoce de forma predeterminada, por ejemplo, una CA interna o una raíz autofirmada.

La coincidencia depende del host. Si el host configurado no coincide con el de la solicitud, Apidog no adjuntará el certificado de cliente.

Configura un certificado de cliente para una API mTLS

Supón este escenario:

  • Tu socio de pagos expone https://partner-api.acmebank.com.
  • Durante la incorporación recibiste un certificado de cliente y una clave privada.
  • Debes consultar GET /v1/settlements.
  • La API requiere mTLS y OAuth.

Paso 1: Abre la sección Certificados

En Apidog:

  1. Abre Configuración desde el icono de la esquina superior derecha.
  2. Ve a la pestaña Certificados.

Aquí se administran tanto los certificados de cliente como los certificados CA. La configuración se aplica según el host de cada solicitud, no por solicitud individual.

Paso 2: Añade un certificado de cliente

En Certificados de Cliente, selecciona Añadir Certificado.

En el campo Host, introduce únicamente el dominio:

partner-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

No incluyas el protocolo:

https://partner-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Si un mismo certificado cubre varios subdominios, usa un patrón:

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Esto permite reutilizar el certificado para hosts como:

partner-api.acmebank.com
sandbox-api.acmebank.com
settlements-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

El puerto es opcional:

  • Déjalo vacío para usar 443.
  • Especifica un puerto si la API mTLS usa uno no estándar, como 8443.

Paso 3: Carga los archivos del certificado

Apidog admite estos formatos para certificados de cliente:

  • CRT + clave: un archivo de certificado y un archivo de clave privada independientes.
  • PFX: un único archivo que contiene el certificado y la clave privada.

Si la clave privada está protegida, introduce la contraseña en el campo frase de contraseña. Si no tiene contraseña, déjalo vacío.

Un paquete típico de incorporación puede incluir:

client.crt
client.key
Enter fullscreen mode Exit fullscreen mode

O bien:

client.pfx
Enter fullscreen mode Exit fullscreen mode

Paso 4: Guarda la configuración

Selecciona Añadir.

El certificado queda asociado a:

partner-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

A partir de ese momento, Apidog lo aplicará automáticamente a las solicitudes HTTPS que coincidan con ese host.

Paso 5: Envía la solicitud autenticada

Crea y envía una solicitud como esta:

GET https://partner-api.acmebank.com/v1/settlements
Authorization: Bearer <tu_token_oauth>
Enter fullscreen mode Exit fullscreen mode

Apidog realiza automáticamente estas acciones:

  1. Detecta que el host coincide con la configuración del certificado.
  2. Adjunta el certificado de cliente durante el handshake TLS.
  3. Completa mTLS.
  4. Envía el encabezado OAuth como parte de la solicitud HTTP.

El certificado identifica al cliente en la capa TLS. El token identifica al emisor o usuario en la capa de aplicación.

Una respuesta exitosa podría ser:

{
  "settlements": [
    {
      "id": "stl_88213",
      "amount": 41200,
      "currency": "USD",
      "status": "cleared",
      "settled_at": "2026-07-14T09:31:00Z"
    }
  ],
  "next_cursor": null
}
Enter fullscreen mode Exit fullscreen mode

Añadir un certificado CA para raíces internas o autofirmadas

El certificado de cliente permite que el servidor confíe en ti. Pero tu cliente también debe poder confiar en el servidor.

En servicios internos o entornos de preparación, el certificado del servidor puede estar firmado por una CA privada. En ese caso, la solicitud puede fallar antes de iniciar mTLS con un error similar a:

SSL Error: Self signed certificate
Enter fullscreen mode Exit fullscreen mode

Para resolverlo, añade la CA correspondiente en Apidog.

Configuración de una CA personalizada

En la misma pestaña Certificados:

  1. Activa Certificados CA.
  2. Selecciona el archivo PEM de tu CA.

Los certificados CA usan formato PEM. Un solo archivo puede incluir una cadena completa de certificados raíz e intermedios:

-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQG...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIBAgIQeM8V5x8B3QksZ4 b2VqkJTANBgkqhkiG9w0BAQ...
-----END CERTIFICATE-----
Enter fullscreen mode Exit fullscreen mode

Con esta configuración:

  • La CA permite que Apidog confíe en el certificado del servidor.
  • El certificado de cliente permite que el servidor confíe en Apidog.

Para un servicio mTLS interno con una raíz privada, normalmente necesitas ambos.

Consejos prácticos y casos frecuentes

Usa un patrón para cubrir subdominios

Si tu certificado es válido para varios subdominios, configura un único patrón:

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Evita registrar cada host por separado cuando todos usan el mismo certificado.

Configura puertos no estándar

El puerto predeterminado es 443. Si la API escucha en 8443 o 9443, configura ese puerto en el certificado.

Por ejemplo:

Host: partner-api.acmebank.com
Puerto: 8443
Enter fullscreen mode Exit fullscreen mode

Si el puerto no coincide, Apidog podría no encontrar la configuración adecuada para el host.

Elimina y vuelve a crear para actualizar certificados

Los certificados no se editan después de añadirlos. Para rotar un certificado renovado o corregir el host:

  1. Elimina la configuración existente.
  2. Añade el nuevo certificado.
  3. Verifica el host, el puerto y la frase de contraseña.

Incluye este proceso en tu procedimiento de rotación de certificados.

Registra un certificado por dominio

Evita crear varias configuraciones de certificado de cliente para el mismo dominio. Las configuraciones duplicadas generan ambigüedad sobre qué certificado debe presentar Apidog.

Mantén una única configuración por host o patrón.

Separa mTLS de la autorización HTTP

No intentes configurar un token OAuth o una clave API dentro de Certificados.

  • Certificados: identidad TLS, mTLS y confianza de CA.
  • Autorización: API keys, Bearer tokens, OAuth y Basic Auth.

La autorización puede definirse en tres niveles:

  1. Solicitud individual.
  2. Carpeta.
  3. Colección.

Las solicitudes pueden heredar la autorización de su carpeta o colección. Para profundizar en la parte de autenticación HTTP, consulta la guía de autenticación de gateway API y este tutorial sobre configuración de autenticación Kerberos en Apidog.

mTLS requiere HTTPS

Apidog no adjunta certificados de cliente a solicitudes HTTP sin TLS.

Esto no activa mTLS:

http://partner-api.acmebank.com/v1/settlements
Enter fullscreen mode Exit fullscreen mode

Usa siempre HTTPS:

https://partner-api.acmebank.com/v1/settlements
Enter fullscreen mode Exit fullscreen mode

Automatiza las pruebas mTLS con la CLI de Apidog

Cuando la solicitud funcione en la interfaz, guarda el escenario y ejecútalo desde CI/CD con la CLI de Apidog.

Instala la CLI e inicia sesión:

npm install -g apidog-cli
apidog login --with-token <TU_TOKEN_DE_ACCESO>
Enter fullscreen mode Exit fullscreen mode

Ejecuta un escenario guardado en un entorno:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <id_escenario> -e <id_entorno> -r cli
Enter fullscreen mode Exit fullscreen mode

Para configurar mTLS directamente desde la CLI, usa:

  • --ssl-client-cert para el certificado PEM.
  • --ssl-client-key para la clave privada.
  • --ssl-client-passphrase si la clave tiene contraseña.
  • --ssl-extra-ca-certs para CA adicionales de confianza.
  • --ssl-client-cert-list para una configuración de certificados asociada a patrones de URL.

También puedes combinar reporteros:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <id_escenario> \
  -e <id_entorno> \
  -r html,cli
Enter fullscreen mode Exit fullscreen mode

Integra este comando en tu pipeline para ejecutar las pruebas de APIs protegidas con certificados en cada push. Consulta la guía de Apidog CLI en CI/CD para implementar el flujo en una pipeline.

Preguntas frecuentes

¿Necesito un certificado de cliente y un certificado CA?

Depende del endpoint:

  • Necesitas un certificado de cliente cuando el servidor exige mTLS.
  • Necesitas un certificado CA cuando el certificado del servidor está firmado por una autoridad que tu equipo no reconoce, como una CA interna.

Una API pública con una CA pública de confianza suele requerir solo el certificado de cliente. Un servicio interno con CA privada suele requerir ambos.

¿Por qué Apidog no envía mi certificado de cliente?

Revisa estos puntos:

  1. El campo Host contiene el dominio exacto y no incluye https://.
  2. El puerto configurado coincide con el endpoint.
  3. La solicitud usa https://.
  4. El certificado corresponde al host o patrón configurado.

Apidog nunca adjunta certificados de cliente a una solicitud HTTP sin TLS.

¿Dónde configuro las claves API y los tokens Bearer?

Configúralos en la pestaña Autorización de la solicitud, carpeta o colección.

Los certificados manejan la identidad en TLS; Autorización maneja credenciales de la solicitud HTTP. Consulta la guía de esquemas de seguridad para ver los tipos de autenticación disponibles.

¿Un certificado puede cubrir varios subdominios?

Sí. Usa un patrón de host:

*.example.com
Enter fullscreen mode Exit fullscreen mode

Así, el certificado se aplicará a los subdominios de example.com.

¿Cómo actualizo un certificado?

Elimina el certificado existente y añade la versión nueva o corregida. Para mantener la configuración de pruebas organizada, también puedes establecer parámetros globales en Apidog.

Conclusión

Probar una API protegida con mTLS en Apidog requiere tres pasos:

  1. Vincular el certificado de cliente al host correcto.
  2. Añadir un certificado CA si el servidor usa una raíz privada o autofirmada.
  3. Enviar solicitudes HTTPS y dejar que Apidog aplique el certificado según la coincidencia del host.

Mantén separados los certificados TLS y la autorización HTTP. Cuando cada capa está configurada en su lugar, el handshake deja de ser un bloqueo y pasa a formar parte automática de tus pruebas.

Descarga Apidog para añadir el certificado de tu socio y enviar tu primera solicitud autenticada. Pruébalo gratis; no se requiere tarjeta de crédito.

Top comments (0)