نظام EKM (المفاتيح الخارجية) في واجهة برمجة تطبيقات الإدارة

تعرف على كيفية إدارة المفاتيح الخارجية لنظام EKM باستخدام واجهة برمجة تطبيقات الإدارة.

تم التحديث: yesterday

الملخص

إمكانية الوصول

  • يمكن الوصول إلى نقطة النهاية الخاصة بنظام EKM في واجهة برمجة تطبيقات الإدارة عبر مفتاح API للمسؤول. https://platform.openai.com/settings/organization/admin-keys (لا تستخدم مفتاح API عاديًا). مفاتيح API للمسؤول متاحة لمالكي المؤسسات.

  • استخدم api.external_keys.write لإنشاء المفاتيح الخارجية أو حذفها، وapi.external_keys.read لعرض المفاتيح الخارجية أو استرجاعها أو التحقق من صحتها. ولا يحتاج المفتاح الواحد إلى كلا النطاقين إلا إذا كان يجب عليه تنفيذ عمليتي القراءة والكتابة.

الاستخدام

  • يتم تسجيل تكوين نظام EKM الخاص بك على مستوى المؤسسة عبر نقطة نهاية جديدة https://api.openai.com/v1/organization/external_keys

  • يؤدي تسجيل إعدادات نظام EKM إلى إرجاع external_key_id بالشكل extkey_xxxx.

  • يتم تفعيل إعدادات نظام EKM على مستوى المشروع من خلال تمرير external_key_id في نص نقطة نهاية "إنشاء مشروع" https://api.openai.com/v1/organization/projects .

القيود

  • يجب أولًا اختبار نظام EKM على مشروع جديد عبر واجهة برمجة تطبيقات الإدارة.

  • نوصي بإنشاء مشاريع جديدة لأعباء عمل نظام EKM لديك. يرجى ملاحظة أفضل الممارسات التالية قبل طرح نظام EKM على مشاريع الإنتاج الحالية لديك.

    • اختبر أولاً جميع ميزات واجهة API التي تستخدمها في بيئة الإنتاج في مشروع EKM API التجريبي.

    • قم بتطبيق طرح تدريجي بدلاً من تعبئة نظام EKM في جميع مشاريع واجهة API في بيئة الإنتاج دفعة واحدة.

نقطة النهاية على مستوى المنظمة

تسجيل مفتاح خارجي في منظمتك

AWS

مثال على طلب:

  • type: سلسلة نصية - دائمًا "aws"

  • name: سلسلة نصية - اسم سهل الاستخدام للتكوين الخاص بك

  • role_arn: سلسلة نصية - معرّف ARN للدور الذي ستتولاه OpenAI في الخدمة السحابية لديك

  • kms_arn: سلسلة نصية - نظام إدارة المفاتيح ARN للمفتاح الرئيسي الذي تقوم بإدارته

  • external_id: سلسلة نصية - معرّف منظمتك أو معرّف مشروع واجهة برمجة التطبيقات

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

مثال على الرد:

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

مثال على طلب:

  • type: سلسلة نصية - دائمًا "gcp",

  • name: سلسلة نصية - اسم سهل الاستخدام للتكوين الخاص بك

  • workload_identity_project_number: سلسلة نصية - رقم مشروع GCP الرقمي الذي سجّلت فيه هوية عبء العمل الخاصة بـ OpenAI

  • workload_identity_pool_id: سلسلة نصية - المجموعة التي تضم موفّر هوية عبء العمل الذي قمت بتسجيله لـ OpenAI

  • workload_identity_provider_id: سلسلة نصية - موفّر هوية عبء العمل الذي قمت بتسجيله لـ OpenAI

  • audience: سلسلة نصية - الجمهور الذي يجب على OpenAI تمريره في الرمز عند تولي دور من خلال GCP STS الخاص بك

  • kms_project_id: سلسلة نصية - اسم مشروع GCP الذي يوجد فيه نظام KMS الخاص بك

  • kms_key_ring_name: سلسلة نصية - حلقة مفاتيح نظام إدارة المفاتيح التي تحتوي على المفتاح الرئيسي الذي تقوم بإدارته

  • kms_key_name: سلسلة نصية - اسم المفتاح الرئيسي لنظام إدارة المفاتيح

  • kms_key_location: سلسلة نصية - المنطقة التي يوجد فيها المفتاح الرئيسي لنظام إدارة المفاتيح الخاص بك

إذا كان نظام KMS لديك موجود في مشروع GCP مختلف عن المشروع الذي سجّلت فيه هوية عبء العمل الخاصة بـ OpenAI، فتأكد من أن المشروع الذي يحتوي على هوية عبء العمل الخاصة بـ OpenAI مفعّل فيه نظام KMS على الأقل، وذلك بالانتقال إلى 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"
}'

مثال على الرد:

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

مثال على طلب:

  • type: سلسلة نصية - دائمًا "azure",

  • name: سلسلة نصية - اسم سهل الاستخدام للتكوين الخاص بك

  • tenant_id: سلسلة نصية - معرّف UUID لوحدة Tenant الخاصة بـ Azure.

  • vault_uri: سلسلة نصية - معرّف URI لمخزن Azure الذي يحتوي على المفتاح الرئيسي الذي تديره

  • key_name: سلسلة نصية - اسم المفتاح الرئيسي في مخزن مفاتيح Azure الذي تديره

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

مثال على الرد:

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

يرجى إعداد مفتاح AES-256 مفعّل ومنح OpenAI صلاحية الوصول إليه. يجب أن يتضمن المفتاح علامة حرة الصيغة باسم openai_organization_id تكون قيمتها معرّف المؤسسة الخاص بك في OpenAI. وللاطلاع على خطوات الإعداد، راجع: تهيئة OCI Vault لإدارة المفاتيح المؤسسية.

مثال على طلب:

  • type: سلسلة نصية - دائمًا "oci"

  • purpose: سلسلة نصية - "ekm"؛ القيمة الافتراضية عند إغفاله

  • name: سلسلة نصية - اسم سهل الاستخدام للتكوين الخاص بك

  • region: سلسلة نصية - منطقة OCI التي تحتوي على خزنتك ومفتاحك

  • vault_ocid: سلسلة - معرّف OCID الكامل لخزنتك

  • key_ocid: سلسلة نصية - معرّف OCID الكامل لمفتاح AES-256 الخاص بك

لا تمرر key_version_ocid عند استخدام 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>"
}'

مثال على الرد:

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

تعيد واجهة API رمز HTTP 200 عند النجاح. احفظ قيمة id التي تم إرجاعها واستخدمها بوصفها external_key_id عند إنشاء مشروع. تنطبق عمليات العرض والاسترجاع والتحقق من الصحة والحذف الحالية أيضًا على تسجيلات معرّف OCI.

لاسترداد PSP، استخدم تسجيلًا منفصلًا من نوع RSA-3072 مع الغرض: "psp_decryption" ومعرّف key_version_ocid مطابق تمامًا. عيّن psp_decryption_key_id على معرّف التسجيل المقابل له لدى OpenAI. تحتاج OpenAI فقط إلى صلاحية القراءة للبيانات الوصفية والمفاتيح العامة الخاصة بمفتاح RSA هذا. للاطلاع على الإعداد الكامل، راجع: إعداد المفاتيح غير المتماثلة - OCI Vault.

حذف مفتاح خارجي مسجل في منظمتك

ملاحظة: يُمنع الحذف ما دام هناك مشروع نشط أو مساحة عمل تستخدم هذا التسجيل. بالنسبة إلى EKM، قم أولًا بأرشفة مشروعات API المرتبطة؛ يظل تسجيل EKM المرتبط بمساحة عمل محميًا. لاستعادة PSP، استبدل psp_decryption_key_id أو امسحه في كل مشروع نشط يشير إلى التسجيل قبل حذفه. لا يؤدي حذف تسجيل OpenAI إلى حذف المفتاح السحابي.

مثال على طلب

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

مثال على الرد

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

الحصول على المفاتيح الخارجية المسجّلة في منظمتك

من دون عامل تصفية حسب الغرض، تتضمن القائمة تسجيلات الاسترداد لكل من EKM وPSP. استخدم ?purpose=ekm أو ?purpose=psp_decryption لتصفية القائمة حسب الغرض.

مثال على طلب

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

مثال على الرد

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

التحقق من صحة مفتاح خارجي

استخدم التحقق من الصحة للتأكد من أن OpenAI لا يزال بإمكانه الوصول إلى مفتاحك السحابي.

  • عند استخدام EKM، تتحقق OpenAI من قدرتها على التشفير وفك التشفير باستخدام المفتاح. للاطلاع على تفاصيل الإلغاء وآلية التخزين المؤقت، راجع: إرشادات دورة استخدام المفتاح.

  • في حالة استرداد PSP، تسترجع OpenAI المفتاح العام للإصدار المسجل وتقارنه باللقطة المخزنة. لا يؤكد نجاح التحقق من الصحة أن هوية الاسترداد الخاصة بك قادرة على فك التشفير. لا يؤدي فشل التحقق من الصحة إلى إزالة لقطة المفتاح العام المخزنة أو استبدالها.

يؤدي استرجاع عملية تسجيل باستخدام GET إلى إرجاع التهيئة المخزنة، ولا يعيد التحقق من إمكانية الوصول إلى مفتاحك السحابي.

مثال على طلب

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

مثال على الرد

{
"status": "success"
}

أو ظهر خطأ من مزود الخدمة السحابية.

نقطة النهاية على مستوى المشروع

إنشاء مشروع جديد باستخدام معرّف مفتاح خارجي

هذا مماثل لنقطة نهاية إنشاء مشروع الحالية، مع إضافة المعلمة external_key_id إلى الطلب والرد.

مثال على طلب

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

مثال على الرد

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

تحديث مشروع حالي باستخدام معرّف مفتاح خارجي

هذا مماثل لنقطة نهاية تحديث المشروع الحالية، مع إضافة المعلمة external_key_id إلى الطلب والرد.

نوصي بإنشاء مشاريع API جديدة لأعباء عمل نظام EKM لديك. يرجى ملاحظة أفضل الممارسات التالية قبل طرح نظام EKM على مشاريع الإنتاج الحالية لديك.

  • اختبر أولاً جميع ميزات واجهة API التي تستخدمها في بيئة الإنتاج في مشروع EKM API التجريبي.

  • قم بتطبيق طرح تدريجي بدلاً من تعبئة نظام EKM في جميع مشاريع واجهة API في بيئة الإنتاج دفعة واحدة.

مثال على طلب

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

اسرد جميع المشاريع في منظمتك

هذا مماثل لنقطة النهاية الحالية ولكن مع إضافة external_key_id في استجابة API.

مثال على طلب

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

مثال على الرد

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

هل كانت هذه المقالة مفيدة؟