OpenAI
Cette page a été traduite automatiquement. Afficher l’article original en anglais.

EKM (clés externes) dans l’API de gestion

Découvrez comment gérer les clés externes pour EKM à l’aide de l’API de gestion.

Mise à jour : 3 hours ago

Résumé

Accès

  • Les points de terminaison EKM sont accessibles dans l’API de gestion au moyen d’une clé API d’administration. https://platform.openai.com/settings/organization/admin-keys (n’utilisez pas de clé API standard). Les clés API d’administration sont accessibles aux propriétaires d’organisation.

  • Utilisez api.external_keys.write pour créer ou supprimer des clés externes, et api.external_keys.read pour lister, récupérer ou valider des clés externes. Une même clé n’a besoin des deux portées que si elle doit effectuer des opérations de lecture et d’écriture.

Utilisation

Restrictions

  • Vous devez d’abord tester EKM dans un nouveau projet au moyen de l’API de gestion.

  • Nous recommandons de créer de nouveaux projets pour vos charges de travail EKM. Veuillez tenir compte des bonnes pratiques suivantes avant de déployer EKM dans vos projets de production existants.

    • Testez d’abord toutes les fonctionnalités de l’API que vous utilisez en production dans votre projet API EKM de test.

    • Procédez à un déploiement progressif plutôt que d’activer EKM dans tous les projets API de production à la fois.

endpoints au niveau de l’organisation

Enregistrer une clé externe dans votre organisation

AWS

Exemple de requête :

  • type : chaîne - toujours « aws »

  • name : chaîne - Un nom convivial pour votre configuration

  • role_arn : chaîne - L’ARN du rôle qu’OpenAI assumera dans votre environnement infonuagique

  • kms_arn : chaîne - L’ARN du système de gestion des clés pour la clé principale que vous gérez

  • external_id : chaîne - Votre identifiant d’organisation ou de projet 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>"
}'

Exemple de réponse :

{
"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

Exemple de requête :

  • type : chaîne - toujours « gcp »,

  • name : chaîne - Un nom convivial pour votre configuration

  • workload_identity_project_number : chaîne - Le numéro du projet GCP dans lequel vous avez enregistré l’identité de charge de travail d’OpenAI

  • workload_identity_pool_id : chaîne - Le pool contenant le fournisseur Workload Identity que vous avez enregistré pour OpenAI

  • workload_identity_provider_id : chaîne - Le fournisseur Workload Identity que vous avez enregistré pour OpenAI

  • audience: chaîne - L’audience qu’OpenAI doit transmettre dans le jeton lorsque nous assumons un rôle par l’intermédiaire de votre STS GCP

  • kms_project_id: chaîne - Le nom du projet GCP qui héberge votre KMS

  • kms_key_ring_name : chaîne - Le trousseau du système de gestion des clés contenant la clé principale que vous gérez

  • kms_key_name : chaîne - Le nom de la clé principale du système de gestion des clés

  • kms_key_location : chaîne - La région où se trouve la clé principale de votre système de gestion des clés

Si votre KMS est hébergé dans un projet GCP différent de celui où vous avez enregistré l’identité Workload Identity d’OpenAI, assurez-vous que KMS est au moins activé dans le projet contenant l’identité Workload Identity d’OpenAI en accédant à 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"
}'

Exemple de réponse :

{
"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

Exemple de requête :

  • type : chaîne - toujours « azure »,

  • name : chaîne - Un nom convivial pour votre configuration

  • tenant_id : chaîne - L’UUID de votre locataire Azure

  • vault_uri : chaîne - L’URI du coffre Azure contenant la clé principale que vous gérez

  • key_name : chaîne - Le nom de la clé principale Azure Key Vault que vous gérez.

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"
}'

Exemple de réponse :

{
"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

Configurez une clé AES-256 activée et accordez-y l’accès à OpenAI. La clé doit comporter une balise à format libre openai_organization_id dont la valeur est votre identifiant d’organisation OpenAI. Pour les étapes de configuration, consultez : Configurer OCI Vault pour la gestion des clés d’entreprise.

Exemple de requête :

  • type : chaîne - toujours "oci"

  • purpose : chaîne - "ekm"; valeur par défaut si omis

  • name : chaîne - Un nom convivial pour votre configuration

  • region : chaîne - La région OCI contenant votre coffre et votre clé

  • vault_ocid : chaîne - L’OCID complet de votre coffre

  • key_ocid : chaîne - L’OCID complet de votre clé AES-256

Ne transmettez pas key_version_ocid pour 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>"
}'

Exemple de réponse :

{
"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>"
}

L’API renvoie HTTP 200 en cas de réussite. Conservez la valeur id renvoyée et utilisez-la comme external_key_id lors de la création d’un projet. Les opérations existantes de listage, de récupération, de validation et de suppression s’appliquent aussi aux enregistrements OCI.

Pour la récupération PSP, utilisez un enregistrement RSA-3072 distinct avec purpose: "psp_decryption" et un key_version_ocid exact. Définissez psp_decryption_key_id sur son identifiant d’enregistrement OpenAI. OpenAI a seulement besoin d’un accès en lecture aux métadonnées et aux clés publiques de cette clé RSA. Pour la configuration complète, consultez : Configurer des clés asymétriques — OCI Vault.

Supprimer une clé externe enregistrée auprès de votre organisation

Remarque : La suppression est bloquée tant qu’un projet ou un espace de travail actif utilise l’enregistrement. Pour EKM, archivez d’abord les projets API associés; un enregistrement EKM associé à un espace de travail demeure protégé. Pour la récupération PSP, remplacez ou effacez psp_decryption_key_id dans chaque projet actif qui fait référence à l’enregistrement avant de supprimer ce dernier. La suppression d’un enregistrement OpenAI ne supprime pas la clé infonuagique.

Exemple de requête

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

Exemple de réponse

{
"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>"
}

Obtenir les clés externes enregistrées auprès de votre organisation

Sans filtre sur le paramètre purpose, la liste comprend les enregistrements EKM et ceux de récupération PSP. Utilisez ?purpose=ekm ou ?purpose=psp_decryption pour filtrer selon l’usage.

Exemple de requête

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

Exemple de réponse

{
"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"
}

Valider une clé externe

Utilisez la validation pour vérifier qu’OpenAI peut toujours accéder à votre clé infonuagique.

  • Pour EKM, OpenAI vérifie qu’il est possible de chiffrer et de déchiffrer avec la clé. Pour le fonctionnement de la révocation et de la mise en cache, consultez : les directives sur le cycle de vie des clés.

  • Pour la récupération PSP, OpenAI récupère la clé publique de la version enregistrée et la compare à l’instantané stocké. Une validation réussie ne confirme pas que votre identité de récupération peut effectuer le déchiffrement. Une validation échouée ne supprime ni ne remplace l’instantané de clé publique stocké.

La récupération d’un enregistrement avec GET renvoie la configuration stockée sans vérifier de nouveau l’accès à votre clé infonuagique.

Exemple de requête

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

Exemple de réponse

{
"status": "success"
}

Ou une erreur renvoyée par le fournisseur infonuagique.

endpoints au niveau du projet

Créer un nouveau projet avec un identifiant de clé externe

Il s’agit du même point de terminaison existant de création de projet, avec l’ajout du paramètre external_key_id dans la requête et la réponse.

Exemple de requête

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"
}'

Exemple de réponse

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

Mettre à jour un projet existant avec un identifiant de clé externe

Il s’agit du même point de terminaison de mise à jour de projet existant, avec l’ajout du paramètre external_key_id dans la requête et la réponse.

Nous recommandons de créer de nouveaux projets API pour vos charges de travail EKM. Veuillez tenir compte des bonnes pratiques suivantes avant de déployer EKM dans vos projets de production existants.

  • Testez d’abord toutes les fonctionnalités de l’API que vous utilisez en production dans votre projet API EKM de test.

  • Procédez à un déploiement progressif plutôt que d’activer EKM dans tous les projets API de production à la fois.

Exemple de requête

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"
}'

Lister tous les projets de votre organisation

Il s’agit du même point de terminaison existant, avec l’ajout de external_key_id dans la réponse de l’API.

Exemple de requête

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

Exemple de réponse

{
"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
}

Cet article vous a-t-il été utile?