Registra un par de claves asimétricas RSA-3072 de tu proveedor de nube para usarlo con OpenAI.
Tu clave privada permanece en AWS KMS, Azure Key Vault o Google Cloud KMS. Al registrar el par de claves, OpenAI guarda una copia de la clave pública correspondiente.
Al registrar una clave no se configuran las funciones del producto ni el almacenamiento. Esta guía explica cómo configurar claves para el descifrado de PSP.
Antes de empezar
- Ten a mano el ID de tu organización. Usa la misma organización para configurar la relación de confianza con el proveedor de nube, registrar la clave y acceder a la API.
- Crea una clave de la API de administración de tu organización con permisos de lectura y escritura para claves externas. Cárgala de forma segura en
OPENAI_ADMIN_KEY. Las claves de inferencia de proyectos no sirven para esta operación. - Asegúrate de tener permiso para crear una clave RSA-3072 habilitada y otorgar a OpenAI el acceso de lectura a la clave pública con el alcance que se indica en esta guía.
- Limita el uso de la clave privada a los usuarios autorizados y conserva las versiones anteriores mientras haya registros que dependan de ellas.
Configura una clave en la nube
Sigue los pasos de tu proveedor antes de registrar la clave. En todos los casos, se usa RSA-3072 y OpenAI solo obtiene permiso para leer la clave pública y sus metadatos.
Registra tu clave
Los ejemplos usan curl y un shell compatible con Bash. Carga OPENAI_ADMIN_KEY de forma segura y luego establece el ID de tu organización:
API_BASE="https://api.openai.com/v1"
ORG_ID="<OPENAI_ORG_ID>"
: "${OPENAI_ADMIN_KEY:?Load your organization admin key securely}"
KEYS_URL="$API_BASE/organization/external_keys"Prepara la solicitud de registro
La enumeración purpose acepta ekm (el valor predeterminado) o psp_decryption. Usa psp_decryption para las claves asimétricas de esta guía. El valor ekm corresponde a Enterprise Key Management (EKM).
Guarda la solicitud de tu proveedor como registration.json. Reemplaza los valores de ejemplo, ya que JSON no expande las variables del shell.
Solicitud para AWS KMS
{
"type": "aws",
"purpose": "psp_decryption",
"name": "asymmetric-key-aws",
"role_arn": "<CUSTOMER_ROLE_ARN>",
"external_id": "<OPENAI_ORG_ID>",
"kms_arn": "<CUSTOMER_KMS_KEY_ARN>"
}Solicitud para Azure Key Vault
{
"type": "azure",
"purpose": "psp_decryption",
"name": "asymmetric-key-azure",
"tenant_id": "<CUSTOMER_TENANT_ID>",
"vault_uri": "https://<CUSTOMER_VAULT_NAME>.vault.azure.net",
"key_name": "<OPENAI_ORG_ID>--asymmetric-key",
"key_version": "<CUSTOMER_KEY_VERSION>"
}Solicitud para Google Cloud KMS
{
"type": "gcp",
"purpose": "psp_decryption",
"name": "asymmetric-key-gcp",
"workload_identity_project_number": "<CUSTOMER_GCP_PROJECT_NUMBER>",
"workload_identity_pool_id": "openai-keys",
"workload_identity_provider_id": "openai-google",
"audience": "<OPENAI_ORG_ID>",
"kms_project_id": "<CUSTOMER_KMS_PROJECT_ID>",
"kms_key_ring_name": "asymmetric-keys",
"kms_key_name": "asymmetric-key",
"kms_key_location": "us-central1",
"kms_key_version": "1"
}1. Registra y valida la clave
curl --fail-with-body -sS "$KEYS_URL" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "OpenAI-Organization: $ORG_ID" \
-H "Content-Type: application/json" \
--data @registration.jsonDurante el registro, se valida la clave antes de guardarla. Si el registro se completa correctamente, la API devuelve HTTP 200 con un ID extkey y la configuración de tu proveedor. Ejemplo de los campos de la respuesta:
{
"id": "extkey_11111111111111111111111111111111",
"object": "organization.external_key",
"name": "asymmetric-key-gcp",
"type": "gcp",
"purpose": "psp_decryption",
"api_project_ids": []
}Guarda el ID de registro que recibiste:
KEY_ID="<EXTERNAL_KEY_ID>"2. Vuelve a validar la clave (opcional)
GET devuelve los datos almacenados. POST /validate vuelve a comprobar el acceso actual y verifica la validez de la clave comparándola con la clave pública guardada. Esta operación no descifra registros ni actualiza la instantánea.
curl --fail-with-body -sS "$KEYS_URL/$KEY_ID" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "OpenAI-Organization: $ORG_ID"curl --fail-with-body -sS -X POST "$KEYS_URL/$KEY_ID/validate" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "OpenAI-Organization: $ORG_ID"Respuesta esperada (HTTP 200):
{ "status": "success" }Repite la validación después de cualquier cambio en la clave, los permisos o la red. Espera a que se propaguen los cambios de IAM antes de volver a intentarlo.
Para usar la clave registrada en el descifrado de PSP, selecciónala para un proyecto.
Consulta la lista de claves
Usa purpose=psp_decryption para listar los registros de estas claves asimétricas. Si omites el filtro, se devuelven los registros de todos los propósitos. Con purpose=ekm solo se devuelven los de EKM.
curl --fail-with-body -sS --get "$KEYS_URL" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "OpenAI-Organization: $ORG_ID" \
--data-urlencode "purpose=psp_decryption" \
--data-urlencode "order=asc" \
--data-urlencode "limit=20"Mientras has_more sea true, solicita la página siguiente con after establecido en el valor de last_id. Mantén sin cambios purpose, order y limit.
Reemplaza una clave
- Crea una clave de reemplazo en AWS o una nueva versión de la clave en Azure o GCP y otorga acceso de lectura.
- Registra la clave o la versión de reemplazo.
- Selecciona el nuevo ID
extkeyen el proyecto y verifica la selección.
Los registros de claves son instantáneas fijas. La rotación de claves en la nube no los actualiza. Conserva las claves privadas anteriores para los registros que dependan de ellas. Cambiar la selección no migra los registros existentes.
Elimina una clave
Borra o reemplaza la selección en cada proyecto activo antes de eliminar el registro:
curl --fail-with-body -sS -X DELETE "$KEYS_URL/$KEY_ID" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "OpenAI-Organization: $ORG_ID"La operación de eliminación devuelve HTTP 200 con object: "organization.external_key.deleted". No elimina la clave de tu proveedor de nube.
Solución de problemas
| Error | Qué revisar |
|---|---|
| 401 o 403 | Usa una clave de la API de administración de tu organización y confirma que tenga acceso al registro de claves externas. |
400 external_key_provider_error |
Revisa la relación de confianza con el proveedor de nube, los permisos de lectura y el acceso a la red. Comprueba que la clave esté habilitada y que el algoritmo sea correcto. |
| 400 por errores de validación de la solicitud | Revisa el propósito, el ARN de la clave específica de AWS y la versión exacta de la clave de Azure o GCP. |
| 404 | Revisa el ID de registro y la organización. No puedes usar registros eliminados ni registros de otra organización. |
external_key_used_by_active_projects |
Borra o reemplaza la selección de clave en todos los proyectos activos. |
| La clave ya no coincide | Registra la clave de reemplazo y selecciona su nuevo ID. |
Si solicitas ayuda al equipo de soporte, comparte el error y el valor de x-request-id. Nunca compartas credenciales.