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: 20 days ago

Tóm tắt

Quyền truy cập

  • Các endpoint EKM có thể được truy cập trong Management API bằng Khóa API quản trị. https://platform.openai.com/settings/organization/admin-keys (không sử dụng khóa API thông thường). Khóa API quản trị dành cho chủ sở hữu tổ chức.

  • Sử 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 feature flag cho tổ chức của bạn để dùng các endpoint này. Bạn biết mình đã có feature flag nếu thấy external_key_id được trả về từ endpoint List Projects hiện có: https://api.openai.com/v1/organization/projects

Cách sử 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 nên tạo dự án mới cho các workload 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 feature flag. Vui lòng lưu ý các phương pháp hay nhất sau đây trước khi triển khai EKM cho các dự án sản xuất hiện có của bạn.

    • Trước tiên, hãy kiểm thử tất cả tính năng API bạn dùng trong sản xuất trên 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 sản xuất cùng lúc

Các endpoint cấp tổ chức

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

AWS

Yêu cầu mẫu

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

  • name: string -  Tên dễ nhận biết cho cấu hình của bạn

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

  • kms_arn: string - ARN của Key Management System cho khóa chính mà 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 dễ nhận biết 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ý workload identity 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 - Đối tượng mà OpenAI nên truyền trong token khi chúng tôi giả định một vai trò qua GCP STS của bạn

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

  • kms_key_ring_name: string - Key ring của Key Management System chứa khóa chính mà bạn quản lý

  • kms_key_name: string - Tên của khóa chính trong Key Management System

  • kms_key_location: string - Khu vực đặt khóa chính trong Key Management System của bạn

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 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 dễ nhận biết 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 chính mà bạn quản lý

  • key_name: string - Tên khóa chính Azure Key Vault mà 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ý trong tổ chức của bạn

Lưu ý: Bạn chỉ có thể xóa khóa bên ngoài nếu khóa đó không liên kết với bất kỳ dự án API hoặc không gian làm việc đang hoạt động nào. Nếu khóa đó liên kết với một dự án API đang hoạt động, hãy lưu trữ dự án đó trước. Nếu khóa đó liên kết với một không gian làm việc, thì không thể xóa khóa.

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ý trong 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 khóa bên ngoài

Bạn có thể dùng endpoint 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 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 cách, đ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 được trả về từ nhà cung cấp đám mây.

Các endpoint cấp dự án

Tạo dự án mới bằng ID khóa bên ngoài

Giống endpoint Create Project hiện có, nhưng 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 dự án hiện có bằng ID khóa bên ngoài

Giống endpoint Update Project hiện có, nhưng 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 nên tạo dự án API mới cho các workload 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ó, hãy trao đổi với giám đốc tài khoản của bạn và chúng tôi sẽ thêm bạn vào feature flag. Vui lòng lưu ý các phương pháp hay nhất sau đây trước khi triển khai EKM cho các dự án sản xuất hiện có của bạn.

  • Trước tiên, hãy kiểm thử tất cả tính năng API bạn dùng trong sản xuất trên 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 sản xuất 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

Giống endpoint 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?