EKM (claves externas) en la API de administración

Aprende a administrar claves externas para EKM mediante la API de administración.

Última actualización: yesterday

Resumen

Acceso

  • Se puede acceder a los puntos de acceso de EKM en la API de administración mediante una clave de API de administrador. https://platform.openai.com/settings/organization/admin-keys (no uses una clave de API normal). Las claves de API de administración están disponibles para los propietarios de la organización.

  • Usa api.external_keys.write para crear o eliminar claves externas, y api.external_keys.read para listar, recuperar o validar claves externas. Una sola clave necesita ambos alcances solo si debe realizar operaciones de lectura y escritura.

Uso

Restricciones

  • Primero debes probar EKM en un proyecto nuevo mediante la API de gestión.

  • Te recomendamos iniciar nuevos proyectos para las cargas de trabajo de EKM. Ten en cuenta las siguientes mejores prácticas antes de implementar EKM en proyectos de producción existentes.

    • Prueba primero en tu proyecto de API de EKM de prueba todas las funciones de la API que uses en producción.

    • Aplica un despliegue gradual en lugar de configurar EKM en todos los proyectos de API de producción de una sola vez.

Puntos de acceso organizacionales

Registrar una clave externa en tu organización

AWS

Solicitud de ejemplo:

  • type: string - always “aws”

  • name: cadena - Un nombre descriptivo para tu configuración

  • role_arn: cadena - El ARN del rol que OpenAI asumirá en tu nube

  • kms_arn: cadena - El ARN del sistema de administración de claves para la clave maestra que tú administras

  • external_id: cadena - ID de la organización o ID del proyecto de la API

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "aws",
"name": "AWS EKM Config",
"role_arn": "arn:aws:iam::<12_DIGIT_ACCOUNT_NUMBER>:role/<ROLE>",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"external_id": "<your org id or project id>"
}'

Respuesta de ejemplo:

{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "aws",
"name": "AWS EKM Config",
"role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"external_id": "<your org id or project id>"
}

GCP

Solicitud de ejemplo:

  • type: string - always "gcp",

  • name: cadena - Un nombre descriptivo para tu configuración

  • workload_identity_project_number: cadena - El número de proyecto de GCP en formato numérico donde registraste la identidad de carga de trabajo de OpenAI

  • workload_identity_pool_id: cadena - El grupo que contiene el proveedor de identidad de carga de trabajo que registraste para OpenAI

  • workload_identity_provider_id: cadena - El proveedor de identidad de carga de trabajo que registraste para OpenAI

  • audience: cadena - La audiencia que OpenAI debe pasar en el token cuando asumimos un rol a través de tu STS de GCP

  • kms_project_id: cadena - El nombre del proyecto de GCP donde se encuentra tu KMS

  • kms_key_ring_name: cadena - El ARN del Sistema de administración de claves para la clave maestra que administra

  • kms_key_name: cadena - El nombre de la clave maestra del sistema de gestión de claves

  • kms_key_location: cadena - La región donde se encuentra la clave maestra de tu sistema de administración de claves

Si tu KMS está en un proyecto de GCP distinto de aquel en el que registraste la Workload Identity de OpenAI, asegúrate de que el proyecto que contiene la Workload Identity de OpenAI al menos tenga KMS habilitado; para ello, ve a https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview.

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "gcp",
"name": "GCP EKM Config",
"workload_identity_project_number": "123456789012",
"workload_identity_pool_id": "openai-azure",
"workload_identity_provider_id": "openai-ekm-service-role",
"audience": "<your org id or project id>",
"kms_project_id": "adjective-noun-12345",
"kms_key_name": "openai-kms-key",
"kms_key_ring_name": "openai-kms-key-ring",
"kms_key_location": "us-east1"
}'

Respuesta de ejemplo:

{
"id": "extkey_xxxxxx",
"object": "organization.external_key",
"created_at": 1746174349,
"api_project_ids": [],
"type": "gcp",
"name": "GCP EKM Config",
"workload_identity_project_number": "123456789012",
"kms_key_ring_name": "openai-kms-key-ring",
"kms_key_name": "openai-kms-key",
"kms_key_location": "us-east1",
"audience": "<your org id or project id>",
"kms_project_id": "adjective-noun-12345",
"workload_identity_pool_id": "openai-azure",
"workload_identity_provider_id": "openai-ekm-service-role"
}

Azure

Solicitud de ejemplo:

  • type: cadena - siempre "azure",

  • name: cadena - Un nombre descriptivo para tu configuración

  • tenant_id: cadena - El UUID de tu tenant de Azure

  • vault_uri: cadena - El URI del almacén de Azure que contiene la clave maestra que tú administras

  • key_name: cadena - El nombre de la clave maestra de Azure Key Vault que tú administras

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "azure",
"name": "Azure EKM Config",
"tenant_id": "<UUID>",
"vault_uri": "https://<VAULT_NAME>.vault.azure.net/",
"key_name": "org-xxx--some-key"
}'

Respuesta de ejemplo:

{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746174377,
"api_project_ids": [],
"type": "azure",
"name": "Azure EKM Config",
"tenant_id": "<UUID>",
"vault_uri": "https://<VAULT_NAME>.vault.azure.net/",
"key_name": "org-xxx--some-key"
}

OCI

Configura una clave AES-256 habilitada y concede a OpenAI acceso. La clave debe tener configurada una etiqueta de formato libre openai_organization_id con el ID de la organización de OpenAI. Para conocer los pasos de configuración, consulta: Configuración de OCI Vault para la administración de claves empresariales.

Solicitud de ejemplo:

  • type: cadena - siempre "oci"

  • propósito: cadena - "ekm"; el valor predeterminado si se omite

  • name: cadena - Un nombre descriptivo para tu configuración

  • región: cadena - La región de OCI que contiene tu almacén y tu clave

  • vault_ocid: string - El OCID completo de tu almacén

  • key_ocid: string - El OCID completo de tu clave AES-256

No envíes key_version_ocid para EKM.

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}'

Respuesta de ejemplo:

{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}

La API devuelve HTTP 200 si la solicitud se realiza correctamente. Guarda el id devuelto y úsalo como external_key_id al crear un proyecto. Las operaciones existentes de listar, recuperar, validar y eliminar también se aplican a los registros de OCI.

Para la recuperación de PSP, usa un registro RSA-3072 independiente con el propósito: "psp_decryption" y un key_version_ocid exacto. Asigna psp_decryption_key_id al ID de registro de OpenAI. OpenAI solo necesita acceso de lectura a los metadatos y las claves públicas de esa clave RSA. Para ver la configuración completa, consulta: Configurar claves asimétricas: OCI Vault.

Eliminar una clave externa registrada en tu organización

Nota: La eliminación se bloquea mientras un proyecto activo o un espacio de trabajo use el registro. Para EKM, primero archiva los proyectos de API asociados; el registro de EKM asociado a un espacio de trabajo permanece protegido. Para la recuperación de PSP, reemplaza o borra psp_decryption_key_id en cada proyecto activo que haga referencia al registro antes de eliminarlo. Eliminar un registro de OpenAI no elimina la clave de la nube.

Solicitud de ejemplo

curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"

Respuesta de ejemplo

{
"id": "extkey_xxxxx",
"object": "organization.external_key.deleted",
"created_at": 1746127808,
"api_project_ids": [],
"type": "aws",
"account_number": "123456789012",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"name": "AWS EKM Config",
"role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>"
}

Obtén las claves externas registradas en su organización

Sin un filtro de propósito, la lista incluye registros de recuperación de EKM y PSP. Usa ?purpose=ekm o ?purpose=psp_decryption para filtrar por propósito.

Solicitud de ejemplo

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"

Respuesta de ejemplo

{
"object": "list",
"data": [
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746127808,
"api_project_ids": [],
"type": "aws",
"name": "AWS EKM Config",
"account_number": "123456789012",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>"
}
],
"first_id": "extkey_xxxx",
"has_more": false,
"last_id": "extkey_xxxx"
}

Validar una clave externa

Usa la validación para comprobar que OpenAI aún puede acceder a tu clave en la nube.

  • Para EKM, OpenAI verifica que puede cifrar y descifrar con la clave. Para conocer el comportamiento de revocación y almacenamiento en caché, consulta: guía del ciclo de vida de las claves.

  • Para la recuperación de PSP, OpenAI recupera la clave pública de la versión registrada y la compara con la instantánea almacenada. La validación exitosa no confirma que tu identidad de recuperación pueda descifrar. La validación fallida no elimina ni reemplaza la instantánea de clave pública almacenada.

La recuperación de un registro con GET devuelve la configuración almacenada y no vuelve a verificar el acceso a tu clave en la nube.

Solicitud de ejemplo

curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"

Respuesta de ejemplo

{
"status": "success"
}

O bien, surgió un error del proveedor de servicios en la nube.

Puntos de acceso a nivel de proyecto

Crea un nuevo proyecto con un identificador de clave externa

Esto es igual al punto de acceso existente de Create Project, con la adición del parámetro external_key_id en la solicitud y la respuesta.

Solicitud de ejemplo

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects" \
-d '{
"name": "Some Project",
"external_key_id": "extkey_xxxx"
}'

Respuesta de ejemplo

{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}

Actualizar un proyecto existente con un ID de clave externa

Esto es lo mismo que el punto de acceso existente de Update Project, con la adición del parámetro external_key_id en la solicitud y la respuesta.

Te recomendamos crear nuevos proyectos de API para tus cargas de trabajo de EKM. Ten en cuenta las siguientes mejores prácticas antes de implementar EKM en proyectos de producción existentes.

  • Prueba primero en tu proyecto de API de EKM de prueba todas las funciones de la API que uses en producción.

  • Aplica un despliegue gradual en lugar de configurar EKM en todos los proyectos de API de producción de una sola vez.

Solicitud de ejemplo

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects/proj_xxx" \
-d '{
"external_key_id": "extkey_xxxx"
}'

Enumera todos los proyectos de tu organización

Esto es igual al punto de acceso existente, pero con la adición de external_key_id en la respuesta de la API.

Solicitud de ejemplo

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"

Respuesta de ejemplo

{
"object": "list",
"data": [
{
"object": "organization.project",
"id": "proj_xxxx",
"name": "Project Name",
"external_key_id": "extkey_xxxx",
"created_at": 1717798982,
"archived_at": null,
"status": "active"
}
],
"first_id": "proj_xxxx",
"last_id": "proj_xxxx",
"has_more": true
}

¿Este artículo te fue útil?