GuidesOneMux

Protege las claves de la API de OpenAI en un flujo de preguntas y respuestas sobre documentos

Patrón práctico de seguridad para responder preguntas sobre documentos con OpenAI: separa credenciales, limita permisos, redacta los registros y rota las claves de forma segura sin perder la atribución de fuentes.

AI

Resumen · TL;DR

En una aplicación de preguntas y respuestas sobre documentos, guarda la credencial de la aplicación de OpenAI en un almacén de secretos confiable del lado del servidor, nunca en un navegador, un entorno aislado, un archivo de código fuente ni un registro. Concede a cada carga de trabajo únicamente el acceso que necesita, elimina los datos sensibles de los registros y rota las credenciales mediante un procedimiento documentado de sustitución, verificación y revocación. Devuelve referencias a las fuentes con cada respuesta para que los usuarios puedan comprobar las afirmaciones en los documentos recuperados.

Puntos clave

  • Mantén la clave de la aplicación de OpenAI fuera del código generado por agentes y de otros entornos de ejecución no confiables.
  • Usa un proyecto o límite de carga de trabajo dedicado y concede únicamente los permisos de API que necesite la aplicación.
  • Registra identificadores de solicitudes, tiempos e identificadores de fuentes, no credenciales, fragmentos de documentos ni prompts completos.
  • Devuelve identificadores de documentos y referencias a páginas o secciones junto con las respuestas; no consideres una respuesta fluida como prueba.
  • Rota las credenciales implementando una clave de reemplazo, verificando el tráfico y revocando después la antigua. Si sospechas que se ha expuesto, revócala de inmediato.
En esta página (6)

Un sistema de preguntas y respuestas sobre documentos debe hacer bien dos cosas: responder a partir del material correcto y mantener las credenciales fuera del proceso que maneja ese material. La opción más segura por defecto es que un servidor de aplicaciones confiable llame a OpenAI, mientras que la recuperación de información y la gestión de citas siguen siendo pasos explícitos de tu propio flujo de trabajo. No pongas la clave de la aplicación en un navegador, documento, prompt, repositorio de código fuente ni entorno aislado accesible para agentes.

Empieza por definir un límite de confianza

Un flujo habitual es el siguiente: un usuario hace una pregunta; tu aplicación recupera pasajes relevantes de un almacén de documentos autorizado; el servidor envía la pregunta y los pasajes seleccionados a OpenAI; la aplicación devuelve la respuesta con referencias a esos pasajes. La clave debe permanecer en el lado del servidor, en un almacén de secretos administrado o en una configuración protegida equivalente, no en código que se envíe a un usuario ni en una carga de trabajo que pueda inspeccionar su entorno.

La guía de seguridad de entornos aislados de OpenAI advierte que el código generado por agentes puede acceder a archivos, credenciales y recursos de red disponibles en su entorno. Recomienda aislar las cargas de trabajo, usar entornos separados cuando no se deban compartir datos, dedicar proyectos de OpenAI a aplicaciones o cargas de trabajo y mantener la clave de API de la aplicación fuera del entorno. También indica que no se deben incluir claves en imágenes, código fuente ni registros. Consulta la guía de seguridad de entornos aislados de OpenAI.

En el caso de preguntas y respuestas sobre documentos, esto significa tratar los documentos cargados y el código generado por modelos como entradas no confiables. Un proceso de recuperación debe recibir solo los documentos y las herramientas que necesita para su tarea. No debería heredar una credencial de aplicación sin restricciones por el simple hecho de que necesita enviar una pregunta para inferencia.

Limita los permisos y separa las credenciales

Crea un proyecto o límite de credenciales separado para esta aplicación, en vez de compartir una clave de uso general entre cargas de trabajo no relacionadas. Aplica los permisos más restringidos disponibles para las operaciones de API que realmente usa tu implementación. La guía de OpenAI citada especifica api.agents.read y api.agents.write para sesiones, api.responses.write para inferencia y api.vaults.read y api.vaults.write para la gestión de vaults. Son ejemplos para los casos de uso documentados de Agents API; no concedas todos los permisos por defecto. Confirma qué permisos requieren las API que realmente utilizas.

Si un entorno ejecutor necesita conectarse a OpenAI, la guía describe el uso de una clave de entorno independiente para esa conexión. Indica que esta clave permite conectar entornos y no puede autorizar otras acciones de API. Mantenla separada de la clave de la aplicación. Para servicios de terceros, guarda las credenciales en la aplicación o en un proxy confiable; no inyectes secretos de larga duración en un entorno donde el código generado pueda leerlos.

Redacta los registros sin perder información operativa

Los registros ayudan a diagnosticar recuperaciones vacías, solicitudes fallidas y citas ausentes, pero los prompts y documentos completos pueden contener información personal, confidencial o comercialmente sensible. Registra únicamente lo que tu equipo necesite para operar el servicio, por ejemplo:

  • Un identificador de solicitud, marca de tiempo, estado y latencia.
  • El modelo y la versión de la aplicación, si son útiles para depurar.
  • Identificadores internos de documentos y referencias a páginas o secciones, en vez del texto recuperado completo.
  • Una categoría de error redactada, no los encabezados de la solicitud ni los valores secretos.

Por defecto, nunca registres encabezados de autorización, claves de API, prompts completos de usuarios ni pasajes completos de documentos. Si necesitas depurar temporalmente el contenido, utiliza un proceso controlado y de duración limitada, con restricciones de acceso y una fecha de eliminación definida. Revisa también los sistemas de aplicación, proxy, trazas e informes de errores: redactar los datos en el registrador principal de la aplicación no sanea automáticamente otros puntos de captura.

Un ejemplo ilustrativo de patrón de registro es:

log_event(
    request_id="generated-request-id",
    outcome="success",
    retrieved_sources=["policy-17:p4", "handbook-03:section-2"],
    credential="[never include]",
    prompt="[omit or redact]",
    passage_text="[omit or redact]"
)

Esto es pseudocódigo, no un ejemplo probado del SDK de OpenAI. Adáptalo a tu sistema de registro y verifica que los secretos se eliminen antes de que los eventos salgan del proceso de la aplicación.

Haz que la atribución de fuentes forme parte del contrato de respuesta

No le pidas al modelo que invente citas a posteriori. Conserva los metadatos de origen durante la recuperación, asocia cada pasaje con el identificador del documento y su página, sección o URL, y proporciona esos metadatos al paso de generación de respuestas. Exige el formato de respuesta que espera tu aplicación: una respuesta más referencias obtenidas únicamente del conjunto recuperado. Después, valida las referencias en el código de la aplicación antes de mostrarlas.

Si la recuperación no devuelve pasajes pertinentes, indica que los documentos disponibles no permiten respaldar una respuesta o pide al usuario que concrete la pregunta. Si una afirmación de la respuesta no se puede vincular a una fuente devuelta, márcala como no respaldada u omítela. Una cita solo es útil si la ubicación referenciada existe y contiene pruebas de la afirmación. La implementación concreta de la recuperación y el formato de respuesta dependen de las API que elijas; la guía de seguridad citada aquí no prescribe una implementación de preguntas y respuestas sobre documentos ni de citas.

Define un procedimiento para rotar credenciales

Deja los pasos por escrito antes de que se produzca un incidente. Un procedimiento práctico es:

  1. Identifica la aplicación, el proyecto, la entrada del almacén de secretos y los servicios que utilizan la credencial actual.
  2. Crea una credencial de reemplazo con los mismos permisos mínimos necesarios y guárdala en el almacén de secretos aprobado.
  3. Implementa el reemplazo mediante un cambio de configuración controlado. Evita mostrar la clave durante la implementación o incluirla en los artefactos de compilación.
  4. Envía una pregunta de prueba a través del flujo habitual. Confirma que la inferencia funciona, que las citas siguen resolviéndose y que los registros no contienen secretos ni texto de documentos.
  5. Supervisa los errores y revoca la credencial antigua cuando hayas confirmado que se utiliza la nueva. Elimina las copias obsoletas de los sistemas de implementación y los entornos de desarrollo local.
  6. Si sospechas que se ha expuesto, revoca la credencial afectada de inmediato, investiga los accesos y los registros, y emite un reemplazo. No esperes al siguiente ciclo de rotación programado.

La guía de OpenAI indica que las claves deben rotarse o revocarse cuando sea necesario y que las credenciales deben revocarse inmediatamente si se sospecha que se han expuesto. Tu organización debe fijar su propio intervalo de rotación según el riesgo, las políticas y las limitaciones operativas; la fuente citada no establece un calendario universal.

Lista de comprobación antes del lanzamiento

  • La clave de la aplicación está en el servidor y no es accesible para navegadores ni código generado por agentes.
  • La carga de trabajo está aislada adecuadamente, con un proyecto o entorno dedicado cuando corresponda.
  • Los permisos se limitan a las operaciones que necesita la aplicación.
  • Los registros excluyen claves, encabezados de autorización, prompts sin procesar y pasajes recuperados completos.
  • Las respuestas incluyen referencias validadas a documentos recuperados.
  • Hay una persona responsable designada que puede implementar una credencial de reemplazo y revocar la antigua.

La decisión de diseño fundamental es sencilla: mantén las credenciales fuera del entorno de procesamiento de documentos y asegúrate de que las citas puedan rastrearse hasta las fuentes recuperadas. Así se reduce el impacto de una carga de trabajo comprometida y se ofrece a los usuarios una forma de comprobar en qué se basa la respuesta.

FAQ

¿Puedo poner una clave de la API de OpenAI en una aplicación de preguntas y respuestas sobre documentos basada en navegador?

No expongas la clave de la aplicación en el código del navegador. Envía las solicitudes a OpenAI desde un componente confiable del lado del servidor que recupere la clave de una configuración protegida o de un gestor de secretos.

¿Debería registrar los prompts y los pasajes recuperados de documentos para depurar las respuestas?

Evítalo por defecto. Es preferible registrar identificadores de solicitudes, estados, tiempos e identificadores de fuentes. Si necesitas depurar temporalmente el contenido, restringe el acceso, fija una fecha límite de eliminación y asegúrate de que nunca se capturen credenciales.

¿Con qué frecuencia debería rotar las claves de la API de OpenAI?

La guía de seguridad de OpenAI citada indica que las claves deben rotarse o revocarse cuando sea necesario, pero no especifica un intervalo universal. Establece un calendario según el riesgo y las políticas de tu organización, y revoca la clave de inmediato si sospechas que se ha expuesto.

¿Cómo puedo hacer que las citas de preguntas y respuestas sobre documentos sean confiables?

Conserva los identificadores de documentos y los metadatos de página, sección o URL durante la recuperación, limita las referencias al conjunto de fuentes recuperadas y valida cada referencia antes de mostrarla. No confíes en que el modelo invente citas.

Artículos relacionados