TLS mutuo

TLS mutuo (mTLS) agrega la verificación de certificados de cliente TLS a las solicitudes a la API de OpenAI. Cuando activas 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 la credencial de portador habitual.

Usa mTLS cuando una carga de trabajo pueda almacenar de forma segura la clave privada del cliente y quieras que OpenAI verifique la identidad que acredita 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 cargas de trabajo.

Antes de configurar mTLS

Cualquier organización que use 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, consultar y probar la configuración de los 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 también puedes otorgarlos mediante un rol personalizado. Para obtener más información, consulta Administrar permisos en la plataforma de OpenAI.

Prepara lo siguiente:

• Un certificado de cliente y su clave privada para cada carga de trabajo.
• Los certificados intermedios necesarios para construir una cadena desde el certificado de cliente hasta tu ancla de confianza.
• Un ancla de confianza estable en formato PEM que puedas activar para la organización o el 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 sistema de control de versiones. No incluyas claves privadas, contenido de certificados ni credenciales de portador en los registros.

Cargar y activar anclas de confianza

Al cargar un certificado, este se almacena. Las solicitudes solo pasan a requerir mTLS cuando activas el certificado.

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

También puedes administrar los certificados mediante la API:

Usa una credencial que tenga el permiso requerido, ya sea api.mtls.read o api.mtls.write. Para consultar los esquemas de solicitud y respuesta, ve a la referencia de la API de certificados de la organización.

Requisitos de los certificados

Usa un ancla de confianza en formato PEM por cada objeto de certificado. El archivo debe contener un certificado válido al que le quede más de un día de vigencia en el momento de la carga. El certificado de cliente debe incluir un identificador de clave de la autoridad (AKI) para que se pueda verificar la solicitud.

Para que una solicitud pase la verificación mTLS:

• El certificado de cliente debe estar vigente en el momento de la solicitud y ser apto para la autenticación de clientes TLS.
• Debe ser posible construir una cadena válida desde el certificado de cliente hasta un ancla de confianza activa de la organización o del proyecto.
• Si la cadena 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 cadenas de certificados de cliente X.509.

Si cargas un archivo con más de un certificado en formato PEM, la verificación de la cadena presentada en la solicitud usa únicamente el primer certificado configurado como ancla. No des por hecho que se procesará todo el conjunto de certificados PEM.

OpenAI no obtiene los certificados intermedios faltantes de las URL de acceso a la información de la autoridad (AIA) ni comprueba el estado de revocación mediante listas de revocación de certificados (CRL) o el 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 la desactivación de certificados, junto con tus propios controles del ciclo de vida de los certificados.

Orden de verificación

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

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

1. OpenAI intenta primero la verificación directa: comprueba el certificado de cliente con un ancla activa sin usar los certificados intermedios de la solicitud.
2. Si la verificación directa no encuentra una coincidencia y no se produce ningún otro error, OpenAI intenta verificar la cadena de la solicitud con el certificado de cliente y los certificados intermedios presentados en la conexión TLS.
3. Si la cadena pasa la verificación y el certificado activo tiene un filtro CEL, OpenAI evalúa ese filtro sobre el certificado de cliente verificado.

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

La verificación de la cadena de la solicitud se usa como alternativa cuando la verificación directa simplemente no encuentra una coincidencia. No permite recuperarse de todos los errores de verificación directa. Si faltan datos del certificado, si su formato es incorrecto, si falta el AKI o si se produce un error determinista después de que la verificación directa selecciona un ancla, la solicitud puede fallar sin que se intente verificar la cadena presentada.

Filtrar certificados de cliente con CEL

Puedes agregar un filtro de Common Expression Language (CEL) a un certificado que hayas cargado para limitar qué certificados de cliente verificados acepta esa ancla. La expresión debe devolver un valor booleano y se evalúa sobre el certificado de cliente verificado tanto en la verificación directa como en la verificación de la cadena de la solicitud.

CEL proporciona 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 contienen los campos type, value y oid. Los identificadores de tipo de nombre alternativo del sujeto (SAN) admitidos son DNS, EMAIL, IP_ADDRESS, URI y CUSTOM.

Por ejemplo, puedes exigir que la unidad organizativa sea la de producción y que el certificado incluya 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"))

Si el certificado pasa la verificación pero no cumple las condiciones del filtro, la solicitud falla con el error certificate_attribute_verification_failed. Si intentas guardar una política que no pasa la validación, OpenAI la rechaza.

Usar un host mTLS

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

El uso de mTLS depende del host. Usa la misma ruta /v1 que usarías en la interfaz de API correspondiente y prueba cada API y cada modelo que use tu carga de trabajo. La disponibilidad de rutas y modelos puede variar entre los hosts regionales.

Por ejemplo, envía la credencial de portador habitual 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 primer certificado del archivo de la cadena debe ser el de cliente, seguido de los certificados intermedios necesarios. No envíes datos de los certificados en los encabezados HTTP ni en el cuerpo de las solicitudes.

La federación de identidades de cargas de trabajo con X.509 usa un punto de acceso independiente para el intercambio. Usa exactamente POST https://mtls.auth.openai.com/oauth/token. Ese intercambio genera un token de portador de corta duración. No permite autenticarse en la API únicamente con un certificado. Para consultar la estructura completa de la solicitud, ve a la referencia del intercambio de tokens de identidad de cargas de trabajo.

Rotar certificados

Durante la rotación, mantén activas ambas anclas de confianza por un tiempo 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 donde vayas a usarla o para toda la organización.
3. Actualiza las cargas de trabajo para que presenten certificados de cliente cuya cadena llegue a la nueva ancla. Luego prueba cada host mTLS y cada interfaz de API que usen.
4. Desactiva el ancla anterior una vez que todas las cargas de trabajo usen la nueva.
5. Elimina el certificado anterior solo después de desactivarlo para la organización y para cada proyecto.

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

Resolver problemas con las 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 indica que el archivo PEM cargado no pasó la validación, expired_certificate indica que el certificado vence demasiado pronto o ya venció, mtls_cel_policy_invalid indica que el filtro no pasa la validación y certificate_in_use indica 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 habitual de la API. Un certificado por sí solo no basta para autorizar una solicitud a la API.
• OpenAI no obtiene certificados intermedios mediante AIA ni realiza comprobaciones mediante CRL u OCSP.
• Private Link no es compatible con mTLS. Consulta Private Link si necesitas usar una ruta de red privada de Azure en su lugar.
• Los hosts mTLS admitidos por la API son mtls.api.openai.com, mtls-us.api.openai.com y mtls-eu.api.openai.com. No des por hecho que cada uno de los demás hosts regionales de la API tenga un host mTLS equivalente.
• La federación de identidades de cargas de trabajo con X.509 no devuelve un token de actualización ni usa DPoP, una declaración cnf o un token de portador vinculado a un certificado. Consulta Configurar la federación de identidades de cargas de trabajo con certificados X.509.