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

Tìm hiểu cách quản lý khóa bên ngoài cho EKM bằng API quản lý.

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

Tóm tắt

Quyền truy cập

  • Bạn có thể truy cập các điểm cuối EKM trong API quản lý bằng khóa API quản trị. https://platform.openai.com/settings/organization/admin-keys (không dùng khóa API thông thường). Chủ sở hữu tổ chức có thể sử dụng khóa API quản trị.

  • 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 quyền nếu 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 để cho phép truy cập các điểm cuối này. Cờ tính năng đã được bật nếu bạn thấy external_key_id được trả về từ điểm cuối Liệt kê dự án 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 thử nghiệm EKM trên một dự án mới qua API quản lý.

  • Chúng tôi khuyên bạn nên tạo dự án mới cho các khối lượng công việc sử dụng EKM. Tuy nhiên, nếu bạn muốn dùng EKM cho một dự án hiện có, chúng tôi có thể bật cờ tính năng cho bạn. 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 hiện có đang chạy trong môi trường sản xuất.

    • Trước tiên, hãy kiểm thử tất cả tính năng API mà bạn dùng trong môi trường sản xuất trên dự án API thử nghiệm có EKM.

    • Triển khai theo từng giai đoạn thay vì áp dụng EKM đồng loạt cho tất cả dự án API trong môi trường sản xuất.

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: chuỗi - luôn là “aws”

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

  • role_arn: chuỗi - ARN của vai trò mà OpenAI sẽ đảm nhận trong môi trường đám mây của bạn

  • kms_arn: chuỗi - ARN trong hệ thống quản lý khóa của khóa chính do bạn quản lý

  • external_id: chuỗi - 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: chuỗi - luôn là “gcp”,

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

  • workload_identity_project_number: chuỗi - Số dự án GCP nơi bạn đã đăng ký danh tính khối lượng công việc của OpenAI

  • workload_identity_pool_id: chuỗi - Nhóm chứa nhà cung cấp Workload Identity mà bạn đã đăng ký cho OpenAI

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

  • audience: chuỗi - Đối tượng nhận mà OpenAI cần truyền trong mã thông báo khi chúng tôi đảm nhận một vai trò thông qua GCP STS của bạn

  • kms_project_id: chuỗi - Tên dự án GCP chứa KMS của bạn

  • kms_key_ring_name: chuỗi - Vòng khóa trong hệ thống quản lý khóa chứa khóa chính do bạn quản lý

  • kms_key_name: chuỗi - Tên khóa chính trong hệ thống quản lý khóa

  • kms_key_location: chuỗi - Khu vực chứa khóa chính trong hệ thống quản lý khóa 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 đảm bảo 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: chuỗi - luôn là “azure”,

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

  • tenant_id: chuỗi - UUID của đối tượng thuê Azure của bạn

  • vault_uri: chuỗi - URI của kho Azure chứa khóa chính do bạn quản lý

  • key_name: chuỗi - Tên khóa chính trong 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 khóa bên ngoài đã đăng ký với 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 đang hoạt động hoặc không gian làm việc 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, bạn 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ý với 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 điểm cuối này để kiểm tra những điều sau:

  • 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 hết thời gian tồn tại (TTL) 1 giờ của bộ nhớ đệm (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

Điểm cuối này giống điểm cuối Tạo dự án hiện có, nhưng bổ sung tham số external_key_id vào 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": "organization.project",
  "id": "proj_xxxxx",
  "name": "Some Project",
  "external_key_id": "extkey_xxxx",
  "created_at": 1740012721,
  "archived_at": null,
  "status": "active"
}

[Hạn chế quyền truy cập] Cập nhật dự án hiện có bằng ID khóa bên ngoài

Điểm cuối này giống điểm cuối Cập nhật dự án hiện có, nhưng bổ sung tham số external_key_id vào 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 khối lượng công việc sử dụng EKM. Nếu bạn muốn dùng EKM cho tất cả dự án API hiện có, hãy liên hệ người phụ trách tài khoản của bạn và chúng tôi sẽ bật cờ tính năng cho bạn. 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 hiện có đang chạy trong môi trường sản xuất.

  • Trước tiên, hãy kiểm thử tất cả tính năng API mà bạn dùng trong môi trường sản xuất trên dự án API thử nghiệm có EKM.

  • Triển khai theo từng giai đoạn thay vì áp dụng EKM đồng loạt cho tất cả dự án API trong môi trường sản xuất.

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ểm cuối này giống điểm cuối hiện có, nhưng bổ sung external_key_id vào 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?