Управление внешними ключами для EKM с помощью API управления

Краткое содержание

Доступ

Конечные точки EKM доступны в API управления через ключ Admin API. https://platform.openai.com/settings/organization/admin-keys (не используйте обычный API-ключ). Ключи Admin API доступны владельцам организации.
Используйте api.external_keys.write, чтобы создавать и удалять внешние ключи, и api.external_keys.read — чтобы получать список и проверять внешние ключи. Одному ключу нужны обе области действия только в том случае, если он должен выполнять и операции чтения, и операции записи.
В настоящее время нам необходимо включить вашу организацию для доступа к этим конечным точкам с помощью флага функции. Вы поймете, что у вас есть флаг функции, если увидите external_key_id , возвращаемый существующей конечной точкой List Projects: https://api.openai.com/v1/organization/projects

Использование

Ваша конфигурация EKM регистрируется на уровне организации через новую конечную точку https://api.openai.com/v1/organization/external_keys
Регистрация конфигурации EKM возвращает external_key_id в формате extkey_xxxx
Конфигурации EKM активируются на уровне проекта путем передачи external_key_id в теле существующей конечной точки Create Project https://api.openai.com/v1/organization/projects .

Ограничения

Сначала вы должны протестировать EKM на новом проекте с помощью API управления.
Мы рекомендуем создавать новые проекты для ваших рабочих нагрузок EKM. Однако, если вам нужно EKM для существующего проекта, мы можем подключить вас к флагу функции. Обратите внимание на следующие рекомендации, прежде чем развертывать EKM в существующих рабочих проектах.
- Сначала протестируйте все функции API, которые вы используете в рабочей среде, в своем тестовом проекте EKM API
- Примените постепенное развертывание вместо одновременного внедрения EKM во всех рабочих API проектах

Конечные точки на уровне организации

Регистрация внешнего ключа в вашей организации

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: — 12-значный номер проекта GCP, в котором вы зарегистрировали субъект рабочей нагрузки OpenAI
строка workload_identity_pool_id: — пул, содержащий поставщика удостоверений для рабочей нагрузки, которого вы зарегистрировали для OpenAI
строка workload_identity_provider_id: — поставщик удостоверений для рабочей нагрузки, которого вы зарегистрировали для OpenAI
строка audience: — аудитория, которую OpenAI должна передавать в токене, когда мы принимаем роль через ваш GCP STS
строка kms_project_id: — имя проекта GCP, в котором находится ваша KMS
строка kms_key_ring_name: — связка ключей системы управления ключами, содержащая главный мастер-ключ, которым вы управляете
строка kms_key_name: — имя мастер-ключа системы управления ключами
строка kms_key_location: — регион, в котором находится мастер-ключ вашей системы управления ключами

Если ваша KMS находится в другом проекте GCP, а не в том, где вы зарегистрировали субъект рабочей нагрузки OpenAI, убедитесь, что в проекте, содержащем субъект рабочей нагрузки OpenAI, как минимум включена KMS. Для этого перейдите по ссылке 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, которым вы управляете.
- Это должно выглядеть как <org-xxx>--<any_name>,
- где org-xxx — это ID вашей организации OpenAI, который можно найти на странице https://platform.openai.com/settings/organization/general

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-проектами или рабочей областью. Если он связан с активным проектом API, сначала необходимо архивировать этот проект. Если ключ связан с рабочей областью, его нельзя удалить.

Пример запроса

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

Проверка внешнего ключа

Вы можете использовать эту конечную точку для проверки нескольких вещей

После внесения изменений конфигурация внешнего облака остается для OpenAI действительной (вы увидите ответ об успешном выполнении)
Отзыв вашего ключа выполнен корректно, обрабатывается OpenAI и вступит в силу после истечения срока действия TTL кэша длительностью 1 час (вы получите ответ с ошибкой)

Пример запроса

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

Пример ответа

{
 "status": "success"
}

Или возникла ошибка со стороны облачного провайдера.

Конечные точки на уровне проекта

Создание нового проекта с внешним ID ключа

Это то же самое, что и существующая конечная точка Create Project, с добавлением параметра 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,
}

[Ограничено] Обновление существующего проекта с указанием внешнего идентификатора ключа

Это то же самое, что и существующая конечная точка Update Project, с добавлением параметра external_key_id в запросе и ответе.

Мы рекомендуем создавать новые проекты API для ваших рабочих нагрузок EKM. Если вы хотите использовать EKM во всех ваших существующих API-проектах, обратитесь к вашему менеджеру по работе с клиентами, и мы подключим вас к флагу функции. Обратите внимание на следующие рекомендации, прежде чем развертывать EKM в существующих рабочих проектах.

Сначала протестируйте все функции API, которые вы используете в рабочей среде, в своем тестовом проекте EKM API
Примените постепенное развертывание вместо одновременного внедрения 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"
}'

Перечисление всех проектов в вашей организации

Это то же самое, что и существующая конечная точка, но с добавлением параметра 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
}

EKM (внешние ключи) в API управления

Краткое содержание

Доступ

Использование

Ограничения

Конечные точки на уровне организации

Регистрация внешнего ключа в вашей организации

AWS

Пример запроса

Пример ответа

GCP

Пример запроса

Пример ответа

Azure

Пример запроса

Пример ответа

Удаление внешнего ключа, зарегистрированного в вашей организации

Пример запроса

Пример ответа

Получение внешних ключей, зарегистрированных в вашей организации

Пример запроса

Пример ответа

Проверка внешнего ключа

Пример запроса

Пример ответа

Конечные точки на уровне проекта

Создание нового проекта с внешним ID ключа

Пример запроса

Пример ответа

[Ограничено] Обновление существующего проекта с указанием внешнего идентификатора ключа

Пример запроса

Перечисление всех проектов в вашей организации

Пример запроса

Пример ответа

Была ли эта статья полезной?