OpenAI
این صفحه به‌صورت ماشینی ترجمه شده است. مقاله اصلی انگلیسی را مشاهده کنید.

EKM (کلیدهای خارجی) در Management API

با نحوهٔ مدیریت کلیدهای خارجی EKM از طریق API مدیریت آشنا شوید.

به‌روزرسانی: 5 hours ago

خلاصه

دسترسی

  • نقطه‌های پایان EKM در API مدیریت با استفاده از کلید 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 را از طریق API مدیریت در یک پروژهٔ جدید آزمایش کنید.

  • توصیه می‌کنیم برای بارهای کاری EKM خود پروژه‌های جدید ایجاد کنید. پیش از پیاده‌سازی EKM در پروژه‌های فعلی محیط عملیاتی، نکات زیر را برای اجرای بهتر در نظر بگیرید.

    • ابتدا تمام قابلیت‌های API را که در محیط عملیاتی استفاده می‌کنید، در پروژهٔ API آزمایشیِ EKM خود آزمایش کنید.

    • به‌جای فعال‌کردن یک‌بارهٔ EKM در تمام پروژه‌های API محیط عملیاتی، آن را به‌تدریج پیاده‌سازی کنید.

endpointهای سطح سازمان

ثبت یک کلید خارجی در سازمان شما

AWS

نمونهٔ درخواست:

  • type: رشته - همیشه «aws»

  • name: رشته - نامی خوانا برای پیکربندی شما

  • role_arn: رشته - ARN نقشی که OpenAI در محیط ابری شما بر عهده می‌گیرد

  • kms_arn: رشته - ARN سامانهٔ مدیریت کلید برای کلید اصلی‌ای که مدیریت می‌کنید

  • external_id: رشته - شناسهٔ سازمان یا شناسهٔ پروژهٔ 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>"
}'

نمونهٔ پاسخ:

{
"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 را در آن ثبت کرده‌اید، با مراجعه به https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview مطمئن شوید که دست‌کم KMS در پروژهٔ حاوی هویت بار کاری OpenAI فعال است.

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 مستأجر Azure شما

  • vault_uri: رشته - URI خزانهٔ Azure که کلید اصلیِ تحت مدیریت شما در آن قرار دارد

  • key_name: رشته - نام کلید اصلی Azure Key Vault که مدیریت می‌کنید.

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 شما

برای EKM، پارامتر key_version_ocid را ارسال نکنید.

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 با purpose: "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>"
}

دریافت کلیدهای خارجی ثبت‌شده در سازمان شما

بدون فیلتر purpose، فهرست شامل موارد ثبت‌شده برای 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"
}

یا خطایی که از ارائه‌دهنده ابر نمایش داده شده است.

endpointهای سطح پروژه

ایجاد پروژهٔ جدید با شناسهٔ کلید خارجی

این نقطه پایان همان نقطه پایان فعلیِ ایجاد پروژه است، با این تفاوت که پارامتر 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 به درخواست و پاسخ اضافه شده است.

توصیه می‌کنیم برای بارهای کاری EKM خود پروژه‌های API جدید ایجاد کنید. پیش از پیاده‌سازی EKM در پروژه‌های فعلی محیط عملیاتی، نکات زیر را برای اجرای بهتر در نظر بگیرید.

  • ابتدا تمام قابلیت‌های API را که در محیط عملیاتی استفاده می‌کنید، در پروژهٔ API آزمایشیِ EKM خود آزمایش کنید.

  • به‌جای فعال‌کردن یک‌بارهٔ 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
}

آیا این مقاله مفید بود؟