OpenAI
הדף הזה תורגם באופן אוטומטי. לצפייה במאמר המקורי באנגלית.

EKM (מפתחות חיצוניים) ב-API לניהול

ניהול מפתחות חיצוניים עבור EKM באמצעות ה-API לניהול

עודכן: 2 days ago

סיכום

גישה

  • ניתן לגשת ל-endpoints של EKM ב-API לניהול באמצעות מפתח API של מנהל מערכת. https://platform.openai.com/settings/organization/admin-keys (אין להשתמש במפתח API רגיל). מפתחות API של מנהל מערכת זמינים לבעלי הארגון.

  • השתמשו ב-api.external_keys.write כדי ליצור או למחוק מפתחות חיצוניים, וב-api.external_keys.read כדי להציג רשימת מפתחות חיצוניים או לבדוק את תקינותם. מפתח יחיד זקוק לשתי ההרשאות רק אם עליו לבצע גם פעולות קריאה וגם פעולות כתיבה.

  • כרגע עלינו להפעיל לארגון שלכם גישה ל-endpoints האלה באמצעות דגל תכונה. תוכלו לדעת שדגל התכונה מופעל אם external_key_id מוחזר מה-endpoint הקיים להצגת רשימת הפרויקטים: https://api.openai.com/v1/organization/projects

שימוש

מגבלות

  • תחילה יש לבדוק את EKM בפרויקט חדש באמצעות ה-API לניהול.

  • אנו ממליצים להקים פרויקטים חדשים עבור עומסי העבודה שלכם המשתמשים ב-EKM. עם זאת, אם תרצו להפעיל EKM בפרויקט קיים, נוכל להפעיל עבורכם את דגל התכונה. לפני הטמעת EKM בפרויקטים הקיימים שלכם בסביבת הייצור, שימו לב להמלצות הבאות.

    • בדקו תחילה את כל תכונות ה-API שבהן אתם משתמשים בסביבת הייצור בפרויקט ה-API הניסיוני שלכם עם EKM

    • בצעו הטמעה הדרגתית במקום להפעיל EKM בכל פרויקטי ה-API בסביבת הייצור בבת אחת

endpoints ברמת הארגון

רישום מפתח חיצוני בארגון שלכם

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 בן 12 הספרות שבו רשמתם את זהות עומס העבודה של OpenAI

  • workload_identity_pool_id: מחרוזת - המאגר המכיל את ספק זהות עומס העבודה שרשמתם עבור OpenAI

  • workload_identity_provider_id: מחרוזת - ספק זהות עומס העבודה שרשמתם עבור OpenAI

  • audience: מחרוזת - קהל היעד שעל OpenAI להעביר באסימון בעת קבלת הרשאות של תפקיד דרך שירות ה-STS שלכם ב-GCP

  • kms_project_id: מחרוזת - שם פרויקט ה-GCP שבו נמצא ה-KMS שלכם

  • kms_key_ring_name: מחרוזת - צרור המפתחות במערכת ניהול המפתחות המכיל את המפתח הראשי שאתם מנהלים

  • kms_key_name: מחרוזת - שם המפתח הראשי במערכת ניהול המפתחות

  • kms_key_location: מחרוזת - האזור שבו נמצא המפתח הראשי שלכם במערכת ניהול המפתחות

אם ה-KMS שלכם נמצא בפרויקט GCP שונה מזה שבו רשמתם את זהות עומס העבודה של OpenAI, ודאו שלכל הפחות KMS מופעל בפרויקט המכיל את זהות עומס העבודה של OpenAI, דרך הקישור 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 של הדייר שלכם ב-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"
}

מחיקת מפתח חיצוני הרשום בארגון שלכם

הערה: ניתן למחוק מפתח חיצוני רק אם הוא אינו משויך לפרויקט API פעיל כלשהו או ל-workspace. אם הוא משויך לפרויקט API פעיל, יש להעביר תחילה את הפרויקט לארכיון. אם הוא משויך ל-workspace, לא ניתן למחוק את המפתח.

בקשה לדוגמה

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

אחזור המפתחות החיצוניים הרשומים בארגון שלכם

בקשה לדוגמה

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

בדיקת תקינות של מפתח חיצוני

ניתן להשתמש ב-endpoint הזה כדי לבדוק כמה דברים

  • שתצורת הענן החיצוני שלכם עדיין תקינה לשימוש עם OpenAI לאחר שביצעתם שינויים (תתקבל תגובת הצלחה)

  • שביטול המפתח בוצע כראוי, נמצא בתהליך עיבוד ב-OpenAI וייכנס לתוקף לאחר שיפוג תוקף המטמון (TTL), העומד על שעה (תתקבל תגובת שגיאה)

בקשה לדוגמה

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

תגובה לדוגמה

{
 "status": "success"
}

או שגיאה שהוחזרה מספק הענן.

endpoints ברמת הפרויקט

יצירת פרויקט חדש עם מזהה מפתח חיצוני

זהה ל-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": "project",
  "id": "proj_xxxxx",
  "title": "Some Project",
  "external_key_id": "extkey_xxxxx",
  "created": 1740012721,
  "organization_id": "org-xxxxx",
  "is_initial": false,
  "geography": null,
  "scale_tier_enabled": false,
  "disable_user_api_keys": false,
  "zdr_type": null,
}

[גישה מוגבלת] עדכון פרויקט קיים עם מזהה מפתח חיצוני

זהה ל-endpoint הקיים לעדכון פרויקט, בתוספת הפרמטר external_key_id בבקשה ובתגובה.


אנו ממליצים להקים פרויקטי API חדשים עבור עומסי העבודה שלכם המשתמשים ב-EKM. אם תרצו להפעיל 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"
}'

הצגת רשימת כל הפרויקטים בארגון שלכם

זהה ל-endpoint הקיים, בתוספת 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
}

האם המאמר הזה היה מועיל?