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

Tóm tắt

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 sử 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ị.

  • 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ê, truy xuất 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.

Cách sử dụng

Các hạn chế

  • Trước tiên, bạn phải thử nghiệm EKM trên một dự án mới thông qua API quản lý.

  • Chúng tôi khuyên bạn nên tạo các dự án mới cho khối lượng công việc EKM. Hãy lưu ý những 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 vận hành thực tế.

    • Trước tiên, hãy kiểm thử mọi tính năng API đang dùng trong môi trường thực tế trên dự án API thử nghiệm EKM của bạn.

    • Triển khai từng bước thay vì áp dụng EKM cùng lúc cho mọi dự án API đang vận hành thực 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"
}

OCI

Thiết lập một khóa AES-256 ở trạng thái bật và cấp quyền truy cập cho OpenAI. Khóa phải có thẻ dạng tự do openai_organization_id được đặt thành ID tổ chức OpenAI của bạn. Để biết các bước thiết lập, xem: Cấu hình OCI Vault cho tính năng Quản lý khóa doanh nghiệp.

Yêu cầu mẫu:

  • type: chuỗi - luôn là "oci"

  • purpose: chuỗi - "ekm"; đây là giá trị mặc định nếu bỏ qua tham số này

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

  • region: chuỗi - Vùng OCI chứa kho khóa và khóa của bạn

  • vault_ocid: chuỗi - OCID đầy đủ của kho khóa

  • key_ocid: chuỗi - OCID đầy đủ của khóa AES-256

Không truyền key_version_ocid cho EKM.

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

Phản hồi mẫu:

{
"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 trả về HTTP 200 khi thành công. Lưu id được trả về và dùng giá trị đó làm external_key_id khi tạo dự án. Các thao tác liệt kê, truy xuất, xác thực và xóa hiện có cũng áp dụng cho các bản đăng ký OCI.

Để khôi phục PSP, hãy dùng một bản đăng ký RSA-3072 riêng với purpose: "psp_decryption" và key_version_ocid chính xác. Đặt psp_decryption_key_id thành ID của bản đăng ký đó trên OpenAI. OpenAI chỉ cần quyền đọc siêu dữ liệu và các khóa công khai của khóa RSA đó. Để biết quy trình thiết lập đầy đủ, xem: Thiết lập khóa bất đối xứng — OCI Vault.

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

Lưu ý: Thao tác xóa bị chặn khi một dự án hoặc không gian làm việc đang hoạt động còn sử dụng bản đăng ký đó. Đối với EKM, trước tiên hãy lưu trữ các dự án API liên kết; bản đăng ký EKM liên kết với không gian làm việc vẫn được bảo vệ khỏi việc xóa. Đối với việc khôi phục PSP, hãy thay thế hoặc xóa giá trị psp_decryption_key_id trên mọi dự án đang hoạt động có tham chiếu đến bản đăng ký trước khi xóa bản đăng ký đó. Xóa bản đăng ký trên OpenAI không xóa khóa đám mây.

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

Nếu không lọc theo mục đích, danh sách sẽ bao gồm cả bản đăng ký EKM và bản đăng ký khôi phục PSP. Sử dụng ?purpose=ekm hoặc ?purpose=psp_decryption để lọc theo mục đích.

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

Sử dụng thao tác xác thực để kiểm tra xem OpenAI có còn truy cập được khóa đám mây của bạn hay không.

  • Đối với EKM, OpenAI kiểm tra khả năng mã hóa và giải mã bằng khóa đó. Để biết cách hoạt động của việc thu hồi và lưu vào bộ nhớ đệm, xem: hướng dẫn về vòng đời khóa.

  • Đối với việc khôi phục PSP, OpenAI truy xuất khóa công khai của phiên bản đã đăng ký và so sánh với bản chụp đã lưu. Xác thực thành công không có nghĩa là danh tính dùng để khôi phục của bạn có thể giải mã. Xác thực thất bại không xóa hoặc thay thế bản chụp khóa công khai đã lưu.

Truy xuất bản đăng ký bằng GET sẽ trả về cấu hình đã lưu và không kiểm tra lại quyền truy cập vào khóa đám mây của bạn.

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

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 trong yêu cầu và phản hồi.

Chúng tôi khuyên bạn nên tạo các dự án API mới cho khối lượng công việc EKM. Hãy lưu ý những 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 vận hành thực tế.

  • Trước tiên, hãy kiểm thử mọi tính năng API đang dùng trong môi trường thực tế trên dự án API thử nghiệm EKM của bạn.

  • Triển khai từng bước thay vì áp dụng EKM cùng lúc cho mọi dự án API đang vận hành thực 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?