OpenAI
Trang này được dịch bằng máy học. Xem bài viết gốc bằng tiếng Anh.

EKM (Khóa bên ngoài) trong Management API

Quản lý khóa bên ngoài cho EKM bằng Management API

Đã cập nhật: 3 days ago

Tóm tắt

Quyền truy cập

  • Có thể truy cập các điểm cuối EKM trong Management API thông qua Khóa API quản trị viên. https://platform.openai.com/settings/organization/admin-keys (không dùng khóa API thông thường). Khóa API quản trị viên khả dụng cho chủ sở hữu tổ chức.

  • Dùng api.external_keys.write để tạo hoặc xóa khóa bên ngoài, và api.external_keys.read để liệt kê hoặc xác thực khóa bên ngoài. Một khóa chỉ cần cả hai phạm vi nếu khóa đó phải thực hiện cả thao tác đọc và ghi.

  • Hiện tại chúng tôi cần bật cờ tính năng cho tổ chức của bạn để dùng các điểm cuối này. Bạn sẽ biết mình có cờ tính năng này nếu thấy **external_key_id **được trả về từ điểm cuối List Projects hiện có: https://api.openai.com/v1/organization/projects

Cách dùng

Hạn chế

  • Trước tiên bạn phải kiểm thử EKM trên một dự án mới qua Management API.

  • Chúng tôi khuyên bạn tạo các dự án mới cho khối lượng công việc EKM của mình. Tuy nhiên, nếu bạn muốn dùng EKM trên một dự án hiện có, chúng tôi có thể thêm bạn vào cờ tính năng. Vui lòng lưu ý các phương pháp hay nhất sau trước khi triển khai EKM cho các dự án production hiện có của bạn.

    • Trước tiên hãy kiểm thử mọi tính năng API mà bạn dùng trong production trong dự án API EKM thử nghiệm của bạn

    • Triển khai dần dần thay vì áp dụng EKM cho tất cả dự án API production cùng lúc

Điểm cuối cấp tổ chức

Đăng ký một khóa bên ngoài cho tổ chức của bạn

AWS

Yêu cầu mẫu

  • type: string - luôn là “aws”

  • name: string - Tên thân thiện cho cấu hình của bạn

  • role_arn: string - Role ARN mà OpenAI sẽ đảm nhận trong đám mây của bạn

  • kms_arn: string - ARN của Key Management System cho khóa gốc do bạn quản lý

  • external_id: string - ID tổ chức hoặc ID dự án API của bạn

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

Phản hồi mẫu

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

Yêu cầu mẫu

  • type: string - luôn là "gcp",

  • name: string - Tên thân thiện cho cấu hình của bạn

  • workload_identity_project_number: string - Số dự án GCP gồm 12 chữ số nơi bạn đã đăng ký danh tính khối lượng công việc của OpenAI

  • workload_identity_pool_id: string - Pool chứa nhà cung cấp Workload Identity mà bạn đã đăng ký cho OpenAI

  • workload_identity_provider_id: string - Nhà cung cấp Workload Identity mà bạn đã đăng ký cho OpenAI

  • audience: string - Audience mà OpenAI nên truyền trong token khi chúng tôi đảm nhận một vai trò thông qua GCP STS của bạn

  • kms_project_id: string - Tên dự án GCP nơi KMS của bạn tồn tại

  • kms_key_ring_name: string - Key ring của Key Management System chứa khóa gốc do bạn quản lý

  • kms_key_name: string - Tên khóa gốc của Key Management System

  • kms_key_location: string - Vùng nơi khóa gốc của Key Management System của bạn được đặt

Nếu KMS của bạn nằm trong một dự án GCP khác với dự án nơi bạn đã đăng ký Workload Identity của OpenAI, hãy bảo đảm rằng dự án chứa Workload Identity của OpenAI ít nhất đã bật KMS bằng cách truy cập 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"
}'

Phản hồi mẫu

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

Yêu cầu mẫu

  • type: string - luôn là "azure",

  • name: string - Tên thân thiện cho cấu hình của bạn

  • tenant_id: string - UUID tenant Azure của bạn

  • vault_uri: string - URI của Azure vault chứa khóa gốc do bạn quản lý

  • key_name: string - Tên khóa gốc Azure Key Vault do bạn quản lý.

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

Phản hồi mẫu

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

Xóa một khóa bên ngoài đã đăng ký trên tổ chức của bạn

Lưu ý: Bạn chỉ có thể xóa một khóa bên ngoài nếu khóa đó không liên kết với bất kỳ dự án đang hoạt động nào. Nếu nó liên kết với một dự án đang hoạt động, trước tiên bạn phải lưu trữ dự án đó.

Yêu cầu mẫu

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

Phản hồi mẫu

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

Lấy các khóa bên ngoài đã đăng ký trên tổ chức của bạn

Yêu cầu mẫu

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

Phản hồi mẫu

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

Xác thực một khóa bên ngoài

Bạn có thể dùng điểm cuối này để kiểm tra một số điều

  • Cấu hình đám mây bên ngoài của bạn vẫn hợp lệ với OpenAI sau khi bạn đã thực hiện các thay đổi (bạn sẽ thấy phản hồi thành công)

  • Việc thu hồi khóa của bạn được thực hiện đúng, đang được OpenAI xử lý và sẽ có hiệu lực sau khi TTL bộ nhớ đệm 1 giờ hết hạn (bạn sẽ thấy phản hồi lỗi)

Yêu cầu mẫu

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

Phản hồi mẫu

{
 "status": "success"
}

Hoặc, một lỗi xuất phát từ nhà cung cấp đám mây.

Điểm cuối cấp dự án

Tạo một dự án mới với ID khóa bên ngoài

Điều này giống với điểm cuối Create Project hiện có, có thêm tham số external_key_id trong yêu cầu và phản hồi.

Yêu cầu mẫu

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

Phản hồi mẫu

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

[Bị hạn chế] Cập nhật một dự án hiện có với ID khóa bên ngoài

Điều này giống với điểm cuối Update Project hiện có, có thêm tham số external_key_id trong yêu cầu và phản hồi.

Chúng tôi khuyên bạn tạo các dự án API mới cho khối lượng công việc EKM của mình. Nếu bạn muốn dùng EKM trên tất cả dự án API hiện có của mình, hãy hỏi giám đốc tài khoản của bạn và chúng tôi sẽ thêm bạn vào cờ tính năng. Vui lòng lưu ý các phương pháp hay nhất sau trước khi triển khai EKM cho các dự án production hiện có của bạn.

  • Trước tiên hãy kiểm thử mọi tính năng API mà bạn dùng trong production trong dự án API EKM thử nghiệm của bạn

  • Triển khai dần dần thay vì áp dụng EKM cho tất cả dự án API production cùng lúc

Yêu cầu mẫu

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

Liệt kê tất cả dự án trong tổ chức của bạn

Điều này giống với điểm cuối hiện có nhưng có thêm external_key_id trong phản hồi API

Yêu cầu mẫu

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

Phản hồi mẫu

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

Bài viết này có hữu ích không?