TLS mutuo

TLS mutuo (mTLS) agrega la verificación de certificados de cliente TLS a las solicitudes a la API de OpenAI. Después de activar un certificado de confianza para una organización o un proyecto, las solicitudes dentro de ese ámbito deben presentar un certificado de cliente aceptado, además de su credencial de portador habitual.

Usa mTLS cuando una carga de trabajo pueda almacenar de forma segura una clave privada de cliente y quieras que OpenAI verifique la identidad de su certificado antes de autorizar una solicitud a la API. mTLS no reemplaza las claves de API, las credenciales de cuentas de servicio ni los tokens de acceso de identidad de carga de trabajo.

Antes de configurar mTLS

Cualquier organización de la API puede administrar mTLS mediante el control de acceso basado en roles (RBAC) habitual:

• api.mtls.read permite a una entidad de seguridad enumerar, ver y probar la configuración de certificados.
• api.mtls.write permite a una entidad de seguridad cargar, actualizar, activar, desactivar y eliminar certificados.

El rol de propietario de la organización incluye estos permisos, pero puedes otorgarlos mediante un rol personalizado. Para obtener más información, consulta Administrar permisos en la plataforma de OpenAI.

Prepara:

• Un certificado de cliente y su clave privada para cada carga de trabajo.
• Los certificados intermedios necesarios para construir una ruta desde el certificado de cliente hasta tu ancla de confianza.
• Un ancla de confianza estable codificada en PEM que puedas activar a nivel de organización o de proyecto.
• Un proyecto no crítico y un procedimiento de recuperación probado antes de habilitar mTLS para el tráfico de producción.

Mantén las claves privadas fuera del control de versiones. No guardes en los registros claves privadas, contenido de certificados ni credenciales de portador.

Cargar y activar anclas de confianza

La carga almacena un certificado, pero no exige el uso de mTLS. La activación es el paso que cambia el comportamiento de las solicitudes.

1. Abre Configuración de la organización > Seguridad > TLS mutuo.
2. Carga un ancla de confianza codificada en PEM por cada objeto de certificado. Asígnale un nombre que identifique la autoridad y la generación de rotación.
3. Opcionalmente, agrega un filtro CEL que restrinja qué certificados de cliente verificados puede aceptar esa ancla.
4. Activa primero el certificado para un proyecto no crítico. Envía solicitudes representativas a través de un host mTLS de la API desde cada carga de trabajo prevista.
5. Activa el certificado para otros proyectos o para la organización una vez que la validación se complete correctamente.

También puedes administrar los certificados a través de la API:

Usa una credencial con el permiso requerido, api.mtls.read o api.mtls.write. Para consultar los esquemas de solicitud y respuesta, consulta la referencia de la API de certificados de la organización.

Requisitos de los certificados

Usa un ancla de confianza codificada en PEM por objeto de certificado. La carga debe contener un certificado válido que venza más de un día después de la carga. El certificado de cliente debe incluir un identificador de clave de autoridad (AKI) para la verificación de solicitudes.

Para que una solicitud pase la verificación mTLS:

• El certificado de cliente debe ser válido en el momento de la solicitud y adecuado para la autenticación de clientes TLS.
• El certificado de cliente debe permitir construir una ruta válida hasta un ancla de confianza activa a nivel de organización o de proyecto.
• Si la ruta incluye certificados intermedios, el cliente debe presentarlos durante la negociación TLS.
• El ancla de confianza configurada y la cadena del cliente deben pasar la validación estándar de rutas de certificados de cliente X.509.

Si una carga contiene más de un certificado codificado en PEM, la verificación de la cadena de la solicitud usa solo el primer certificado configurado como ancla; no dependas de la semántica de los paquetes PEM.

OpenAI no obtiene los certificados intermedios faltantes desde las URL de acceso a la información de la autoridad (AIA) ni realiza comprobaciones de listas de revocación de certificados (CRL) o del protocolo de estado de certificados en línea (OCSP). Presenta la cadena completa requerida y gestiona la respuesta a incidentes mediante la rotación y desactivación de certificados, así como tus propios controles del ciclo de vida de los certificados.

Comprender el orden de verificación

OpenAI comprueba los certificados activos a nivel de proyecto antes que los certificados activos a nivel de organización. Si ninguno de los dos ámbitos tiene un certificado activo, mTLS no agrega una comprobación de certificados a la solicitud.

Cuando existe un certificado activo, OpenAI verifica la identidad del cliente en este orden:

1. OpenAI primero intenta la ruta directa existente, que verifica el certificado de cliente directamente contra un ancla activa sin usar los certificados intermedios de la solicitud.
2. Si la ruta directa no encuentra una coincidencia y no se produce otro error, OpenAI intenta verificar la cadena de la solicitud con el certificado de cliente y los certificados intermedios presentados por la conexión TLS.
3. Si una ruta se verifica correctamente, OpenAI evalúa el filtro CEL del certificado activo, si lo tiene, sobre el certificado de cliente verificado.

La verificación de la cadena de la solicitud está disponible de forma predeterminada.

La ruta de la cadena de la solicitud es una alternativa cuando no se encuentra una coincidencia y no se produce otro error; no es un mecanismo de recuperación para todos los errores de la ruta directa. Los datos de certificados faltantes o malformados, la ausencia de un AKI o un error determinista después de que la ruta directa seleccione un ancla pueden hacer que la solicitud falle sin intentar verificar la cadena presentada.

Filtrar certificados de cliente con CEL

Agrega un filtro opcional de Common Expression Language (CEL) a un certificado cargado para restringir qué certificados de cliente verificados acepta esa ancla. La expresión debe dar como resultado un valor booleano y se evalúa sobre el certificado de cliente verificado tanto en la ruta directa como en la ruta de la cadena de la solicitud.

CEL expone estos campos:

• subject.common_name, subject.country_code, subject.organization, subject.organizational_unit, subject.locality, subject.province, subject.street_address y subject.postal_code.
• subject_alt_names, una lista cuyas entradas exponen type, value y oid. Los identificadores de tipo SAN admitidos son DNS, EMAIL, IP_ADDRESS, URI y CUSTOM.

Por ejemplo, exige una unidad organizativa de producción y un SAN de tipo DNS en un espacio de nombres específico:

subject.organizational_unit == "Production" &&
subject_alt_names.exists(san, san.type == DNS && san.value.endsWith(".example.com"))

Un certificado que se verifica correctamente, pero no cumple con el filtro, falla con certificate_attribute_verification_failed. OpenAI rechaza cualquier política que no pase la validación al guardarla.

Usar un host mTLS

Envía el tráfico de la API a un host mTLS en lugar de api.openai.com:

mTLS funciona por host. Usa la misma ruta /v1 que llamarías en la interfaz de API correspondiente y prueba cada API y modelo que use tu carga de trabajo. La disponibilidad de rutas y modelos puede variar entre hosts regionales.

Por ejemplo, envía una credencial de portador normal y un certificado de cliente al host mTLS predeterminado:

1234567export OPENAI_MTLS_CERT_CHAIN="/path/to/client-chain.pem"
export OPENAI_MTLS_KEY="/path/to/client-key.pem"

curl https://mtls.api.openai.com/v1/models \
  --cert "$OPENAI_MTLS_CERT_CHAIN" \
  --key "$OPENAI_MTLS_KEY" \
  --header "Authorization: Bearer $OPENAI_API_KEY"

El archivo de la cadena de certificados debe contener primero el certificado de cliente, seguido de los certificados intermedios necesarios. No envíes material de certificados en encabezados HTTP ni en cuerpos de solicitudes.

La federación de identidades de carga de trabajo con X.509 usa un punto de acceso de intercambio específico e independiente: POST https://mtls.auth.openai.com/oauth/token. Ese intercambio genera un token de portador de corta duración; no proporciona autenticación de API basada únicamente en certificados. Para conocer la estructura completa de la solicitud, consulta la referencia del intercambio de tokens de identidad de carga de trabajo .

Rotar certificados

Rota las anclas de confianza con un período de superposición para que las cargas de trabajo existentes sigan funcionando:

1. Carga la nueva ancla de confianza sin desactivar la anterior.
2. Activa la nueva ancla en cada proyecto previsto o a nivel de la organización.
3. Actualiza las cargas de trabajo para que presenten certificados de cliente cuya cadena llegue a la nueva ancla y luego prueba cada host mTLS e interfaz de API que usen.
4. Desactiva el ancla anterior después de que todas las cargas de trabajo hayan migrado.
5. Elimina el certificado anterior solo después de desactivarlo para la organización y todos los proyectos.

Puedes rotar los certificados intermedios sin cambiar el ancla de confianza configurada. Presenta la nueva cadena completa en las solicitudes posteriores.

Solucionar problemas de solicitudes

Usa los códigos de error estables para distinguir los errores de configuración de los errores temporales del servicio:

En las solicitudes de administración, mtls_certificate_invalid significa que el PEM cargado no pasó la validación; expired_certificate, que vence demasiado pronto o ya venció; mtls_cel_policy_invalid, que el filtro no pasa la validación; y certificate_in_use, que debes desactivar el certificado antes de eliminarlo.

Limitaciones actuales

• Una organización puede cargar hasta 50 objetos de certificado.
• mTLS agrega la verificación de certificados a la autenticación normal de la API; no proporciona autorización de API basada únicamente en certificados.
• OpenAI no obtiene certificados intermedios mediante AIA ni realiza comprobaciones de CRL u OCSP.
• Private Link no es compatible con mTLS. Consulta Private Link si, en su lugar, necesitas una ruta de red privada de Azure.
• Los hosts mTLS de la API admitidos son mtls.api.openai.com, mtls-us.api.openai.com y mtls-eu.api.openai.com. No supongas que todos los demás hosts regionales de la API tienen un equivalente mTLS.
• La federación de identidades de carga de trabajo con X.509 no devuelve un token de actualización y no usa DPoP, una declaración cnf ni un token de portador vinculado a un certificado. Consulta Configurar la federación de identidades de carga de trabajo con certificados X.509.