비대칭 키 설정

OpenAI에서 사용할 RSA-3072 비대칭 키 쌍을 클라우드 공급자에서 생성해 등록하세요.

개인 키는 AWS KMS, Azure Key Vault 또는 Google Cloud KMS에 그대로 보관됩니다. OpenAI는 등록 시 해당 개인 키와 쌍을 이루는 공개 키의 사본을 저장합니다.

키를 등록해도 제품 기능이나 스토리지가 자동으로 설정되지는 않습니다. 이 가이드에서는 PSP 복호화에 사용할 키를 다룹니다.

시작하기 전에

조직 ID를 준비하세요. 클라우드 신뢰 관계 설정, 키 등록, API 액세스에는 모두 같은 조직을 사용하세요.
외부 키 읽기 및 쓰기 권한이 있는 조직 관리자 API 키를 만드세요. 키를 OPENAI_ADMIN_KEY 환경 변수에 안전하게 설정하세요. 프로젝트 추론용 키는 사용할 수 없습니다.
활성 상태의 RSA-3072 키를 만들고 이 가이드에서 지정한 범위의 공개 키 읽기 권한을 OpenAI에 부여할 수 있어야 합니다.
권한이 있는 사용자만 개인 키를 사용할 수 있도록 제한하세요. 이전 키 버전이 필요한 레코드가 있는 동안에는 해당 버전을 보관하세요.

클라우드 키 설정

키를 등록하기 전에 사용하는 클라우드 공급자에 해당하는 단계를 따르세요. 모든 공급자에서 RSA-3072를 사용하며, OpenAI에는 공개 키와 메타데이터를 읽을 수 있는 권한만 부여합니다.

1. RSA 키 생성

KMS > 고객 관리형 키 > 키 생성 메뉴를 열고 리전을 선택하세요. 다음과 같이 설정하세요.

키 유형: 비대칭
키 사용: 암호화 및 복호화
키 사양: RSA_3072

조직의 키 관리자를 지정하고 키 생성을 완료하세요. 키를 활성 상태로 유지하고 key/<CUSTOMER_KMS_KEY_ID>로 끝나는 키 ARN 전체를 복사하세요. 별칭 ARN은 사용하지 마세요.

2. 공개 키 읽기 정책 생성

IAM > 정책 > 정책 생성 > JSON 메뉴를 여세요. <CUSTOMER_KMS_KEY_ARN>을 실제 키 ARN으로 바꾸고 정책을 OpenAI-PublicKeyRead라는 이름으로 저장하세요.

12345678910{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["kms:DescribeKey", "kms:GetPublicKey"],
      "Resource": "<CUSTOMER_KMS_KEY_ARN>"
    }
  ]
}

키는 복호화를 지원하지만 OpenAI에는 위의 읽기 권한만 필요합니다. OpenAI에 키 사용자 또는 키 관리자 권한을 부여하지 마세요.

3. 신뢰 정책을 적용할 IAM 역할 생성

IAM > 역할 > 역할 생성 > 사용자 지정 신뢰 정책 메뉴를 여세요. <OPENAI_ORG_ID>를 OpenAI 조직 ID로 바꾸세요. OpenAI 보안 주체는 그대로 두세요.

1234567891011121314151617{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::790389265272:role/EnterpriseKeyManagement"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<OPENAI_ORG_ID>"
        }
      }
    }
  ]
}

OpenAI-PublicKeyRead 정책을 연결하고 역할을 생성하세요. 역할의 ARN을 복사하세요. 키를 등록할 때는 external_id 값으로 위와 동일한 조직 ID를 사용하세요.

4. KMS 키 정책 확인

키 정책에서 해당 역할에 권한을 부여하는지 확인하세요. 키 정책이 권한 부여를 IAM에 위임하지 않는 경우 다음 정책 구문을 추가하세요. <CUSTOMER_ROLE_ARN>을 실제 역할 ARN으로 바꾸고 기존 관리자 권한은 유지하세요.

이 KMS 키 정책에서 "Resource": "*"는 정책이 연결된 키에만 적용됩니다. IAM 정책에는 해당 키의 정확한 ARN을 사용합니다.

123456789{
  "Sid": "AllowPublicKeyRead",
  "Effect": "Allow",
  "Principal": {
    "AWS": "<CUSTOMER_ROLE_ARN>"
  },
  "Action": ["kms:DescribeKey", "kms:GetPublicKey"],
  "Resource": "*"
}

등록에 사용할 역할 ARN과 키 ARN을 보관하세요.

1. OpenAI 엔터프라이즈 애플리케이션 추가

테넌트 관리자에게 EKM - OpenAI Azure 애플리케이션을 테넌트에 추가해 달라고 요청하세요. 애플리케이션 ID는 20a14814-5ab7-4612-a671-1382b412bf93입니다.

Azure CLI를 설치한 다음 로그인하고 애플리케이션이 있는지 확인하세요.

123az login --tenant '<CUSTOMER_TENANT_ID>'
az ad sp show --id '20a14814-5ab7-4612-a671-1382b412bf93' \
  --query '{name:displayName,objectId:id}' -o table

애플리케이션이 없으면 추가하세요.

az ad sp create --id '20a14814-5ab7-4612-a671-1382b412bf93' \
  --query '{name:displayName,objectId:id}' -o table

역할을 할당할 때 사용할 수 있도록 해당 테넌트에 있는 서비스 주체의 개체 ID를 저장하세요.

2. 키 생성

키 자격 증명 모음 > 만들기 메뉴를 여세요. 구독, 리소스 그룹, 자격 증명 모음 이름, 지역을 지정하세요. 액세스 구성 항목에서 Azure 역할 기반 액세스 제어 옵션을 선택하세요.

관리자에게는 이 자격 증명 모음에서 키를 만들 수 있는 역할이 필요합니다. 예를 들어 Key Vault Crypto Officer 역할을 사용할 수 있습니다. OpenAI에는 이 역할을 부여하지 마세요.

자격 증명 모음에서 개체 > 키 > 생성/가져오기 메뉴를 열고 다음과 같이 설정하세요.

이름: <OPENAI_ORG_ID>--asymmetric-key에서 자리표시자를 OpenAI 조직 ID로 바꾸세요.
키 유형: RSA
RSA 키 크기: 3072
사용: 예

활성화 날짜나 만료 날짜를 설정했다면 키가 현재 유효한지 확인하세요. 키에 허용된 작업에 암호 해독 작업을 포함하세요. OpenAI에는 키 읽기 권한만 부여됩니다.

Key Vault의 RSA-HSM 키도 지원됩니다. 독립 실행형 Managed HSM 엔드포인트는 지원되지 않습니다.

3. 키 읽기 권한 부여

키 읽기 DataAction을 포함하는 사용자 지정 역할을 만드세요. 다음 내용을 public-key-reader.json으로 저장하고 구독과 리소스 그룹 값을 실제 값으로 바꾸세요.

123456789101112{
  "Name": "OpenAI Public Key Reader",
  "IsCustom": true,
  "Description": "Read key metadata and public keys.",
  "Actions": [],
  "NotActions": [],
  "DataActions": ["Microsoft.KeyVault/vaults/keys/read"],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/<CUSTOMER_SUBSCRIPTION_ID>/resourceGroups/<CUSTOMER_RESOURCE_GROUP>"
  ]
}

VAULT_RESOURCE_ID에는 자격 증명 모음의 속성 화면에 표시된 Azure 리소스 ID를 설정하세요. HTTPS URI를 사용하지 마세요. OPENAI_SP_ID에는 앞에서 저장한 테넌트 내 서비스 주체의 개체 ID를 설정한 다음 키 범위에서 역할을 할당하세요.

123456789101112az role definition create --role-definition @public-key-reader.json

OPENAI_SP_ID='<CUSTOMER_OPENAI_SP_OBJECT_ID>'
VAULT_RESOURCE_ID='<CUSTOMER_VAULT_RESOURCE_ID>'
KEY_NAME='<OPENAI_ORG_ID>--asymmetric-key'
KEY_SCOPE="$VAULT_RESOURCE_ID/keys/$KEY_NAME"

az role assignment create \
  --assignee-object-id "$OPENAI_SP_ID" \
  --assignee-principal-type ServicePrincipal \
  --role 'OpenAI Public Key Reader' \
  --scope "$KEY_SCOPE"

레거시 액세스 정책을 사용하는 자격 증명 모음에서는 기존 권한 모델을 유지하고 키에 대한 가져오기 권한을 대신 부여하세요.

4. 정확한 키 버전 기록

테넌트 ID, 자격 증명 모음 URI, 키 이름을 기록하세요. 활성화된 키 버전을 열고 키 식별자 끝에 있는 32자리 16진수 버전 값을 복사하세요.

1. 프로젝트와 키 준비

키 프로젝트에서 Cloud KMS를 사용 설정하고 페더레이션 프로젝트에서 IAM과 Security Token Service를 사용 설정하세요. 두 프로젝트가 서로 다르면 양쪽 모두에서 Cloud KMS를 사용 설정하세요.

페더레이션 프로젝트의 12자리 프로젝트 번호를 기록하세요. KMS 프로젝트와 페더레이션 프로젝트는 서로 다를 수 있습니다.

보안 > 키 관리 메뉴를 여세요. 키링을 만든 다음 아래 설정으로 키를 만드세요.

보호 수준: 소프트웨어
용도: 비대칭 복호화
알고리즘: 3072비트 RSA - OAEP 패딩 - SHA256 다이제스트

KMS 프로젝트 ID, 위치, 키링, 키 이름, 활성화된 버전을 복사하세요. 버전은 "1"처럼 구체적인 값으로 지정하세요. "latest"나 "0"은 사용하지 마세요. 비대칭 키에는 기본 버전이 없습니다.

2. 워크로드 아이덴티티 페더레이션 구성

IAM 및 관리자 > 워크로드 아이덴티티 제휴 메뉴를 여세요. openai-keys와 같은 이름으로 전역 풀을 만들고 openai-google과 같은 이름으로 OIDC 공급자를 만든 다음 아래와 같이 설정하세요.

공급자 설정	값
발급기관 URL	`https://accounts.google.com`
허용되는 대상	OpenAI 조직 ID와 정확히 일치하는 값
속성 매핑	`google.subject = assertion.sub`
속성 조건	`assertion.sub == '105900137572174660365'`

대상 값으로 OpenAI 조직 ID를 사용하세요. 발급기관과 OpenAI 주체 값은 그대로 두세요.

3. 키 읽기 역할 생성 및 할당

IAM 및 관리자 > 역할 메뉴에서 다음 권한을 포함하는 사용자 지정 역할을 KMS 프로젝트에 만드세요.

cloudkms.cryptoKeyVersions.get
cloudkms.cryptoKeyVersions.viewPublicKey

두 권한이 모두 필요합니다. 공개 키 뷰어 역할만으로는 충분하지 않습니다. 복호화, 서명 또는 서비스 계정 가장 권한은 부여할 필요가 없습니다.

키의 권한 탭에서 액세스 권한 부여 옵션을 선택하세요. <CUSTOMER_GCP_PROJECT_NUMBER>와 <CUSTOMER_GCP_POOL_ID>를 실제 값으로 바꾼 후 다음 주체에 역할을 할당하세요.

principal://iam.googleapis.com/projects/<CUSTOMER_GCP_PROJECT_NUMBER>/locations/global/workloadIdentityPools/<CUSTOMER_GCP_POOL_ID>/subject/105900137572174660365

풀이 속한 프로젝트의 번호를 사용하고 권한 부여 범위를 이 키로 제한하세요. 키 수준의 IAM 권한은 해당 키의 모든 버전에 적용됩니다. 등록에 사용할 풀 ID, 공급자 ID, 대상 값으로 지정한 조직 ID, KMS 식별자를 저장하세요.

키 등록

예시에서는 curl과 Bash 호환 셸을 사용합니다. OPENAI_ADMIN_KEY를 안전하게 불러온 다음 조직 ID를 설정하세요.

123456API_BASE="https://api.openai.com/v1"
ORG_ID="<OPENAI_ORG_ID>"

: "${OPENAI_ADMIN_KEY:?Load your organization admin key securely}"

KEYS_URL="$API_BASE/organization/external_keys"

등록 요청 준비

purpose에 지정할 수 있는 열거형 값은 ekm(기본값)과 psp_decryption입니다. 이 가이드에서 설정하는 비대칭 키에는 psp_decryption을 사용하세요. ekm은 엔터프라이즈 키 관리(EKM)용입니다.

사용 중인 공급자에 해당하는 요청을 registration.json으로 저장하세요. JSON에서는 셸 변수가 실제 값으로 치환되지 않으므로 예시 값을 직접 바꾸세요.

AWS KMS 요청

12345678{
  "type": "aws",
  "purpose": "psp_decryption",
  "name": "asymmetric-key-aws",
  "role_arn": "<CUSTOMER_ROLE_ARN>",
  "external_id": "<OPENAI_ORG_ID>",
  "kms_arn": "<CUSTOMER_KMS_KEY_ARN>"
}

Azure Key Vault 요청

123456789{
  "type": "azure",
  "purpose": "psp_decryption",
  "name": "asymmetric-key-azure",
  "tenant_id": "<CUSTOMER_TENANT_ID>",
  "vault_uri": "https://<CUSTOMER_VAULT_NAME>.vault.azure.net",
  "key_name": "<OPENAI_ORG_ID>--asymmetric-key",
  "key_version": "<CUSTOMER_KEY_VERSION>"
}

Google Cloud KMS 요청

1234567891011121314{
  "type": "gcp",
  "purpose": "psp_decryption",
  "name": "asymmetric-key-gcp",
  "workload_identity_project_number": "<CUSTOMER_GCP_PROJECT_NUMBER>",
  "workload_identity_pool_id": "openai-keys",
  "workload_identity_provider_id": "openai-google",
  "audience": "<OPENAI_ORG_ID>",
  "kms_project_id": "<CUSTOMER_KMS_PROJECT_ID>",
  "kms_key_ring_name": "asymmetric-keys",
  "kms_key_name": "asymmetric-key",
  "kms_key_location": "us-central1",
  "kms_key_version": "1"
}

1. 키 등록 및 검증

12345curl --fail-with-body -sS "$KEYS_URL" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID" \
  -H "Content-Type: application/json" \
  --data @registration.json

등록 시 키를 먼저 검증한 후 저장합니다. 등록에 성공하면 HTTP 200 응답에 extkey ID와 공급자 설정이 포함됩니다. 응답 필드의 예시는 다음과 같습니다.

12345678{
  "id": "extkey_11111111111111111111111111111111",
  "object": "organization.external_key",
  "name": "asymmetric-key-gcp",
  "type": "gcp",
  "purpose": "psp_decryption",
  "api_project_ids": []
}

응답으로 받은 등록 ID를 저장하세요.

KEY_ID="<EXTERNAL_KEY_ID>"

2. 키 재검증(선택 사항)

GET 요청은 저장된 등록 정보를 반환합니다. POST /validate 요청은 현재 키에 액세스할 수 있는지 다시 확인하고 저장된 공개 키와 대조해 키의 유효성을 검증합니다. 레코드를 복호화하거나 스냅샷을 갱신하지는 않습니다.

123curl --fail-with-body -sS "$KEYS_URL/$KEY_ID" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID"

123curl --fail-with-body -sS -X POST "$KEYS_URL/$KEY_ID/validate" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID"

예상 응답(HTTP 200)

{ "status": "success" }

키, 권한 또는 네트워크를 변경한 후에는 다시 검증하세요. IAM을 변경했다면 변경 사항이 반영된 후에 재시도하세요.

등록한 키를 PSP 복호화에 사용하려면 프로젝트에서 해당 키를 선택하세요.

키 목록 조회

purpose=psp_decryption을 지정하면 PSP 복호화용으로 등록한 비대칭 키 목록을 조회할 수 있습니다. 필터를 생략하면 모든 용도의 키가 반환되고 purpose=ekm을 지정하면 EKM용 키만 반환됩니다.

123456curl --fail-with-body -sS --get "$KEYS_URL" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID" \
  --data-urlencode "purpose=psp_decryption" \
  --data-urlencode "order=asc" \
  --data-urlencode "limit=20"

has_more 값이 true인 동안에는 after에 last_id 값을 지정해 다음 페이지를 요청하세요. purpose, order, limit 값은 그대로 유지하세요.

키 교체

AWS에서는 새 키를 만들고 Azure 또는 GCP에서는 새 키 버전을 만든 다음 읽기 권한을 부여하세요.
새 키 또는 키 버전을 등록하세요.
프로젝트에서 새 extkey ID를 선택한 후 올바르게 선택되었는지 확인하세요.

등록 정보는 등록 시점의 고정된 스냅샷이므로 클라우드에서 키를 교체해도 갱신되지 않습니다. 이전 개인 키가 필요한 레코드가 있으면 해당 키를 보관하세요. 선택한 키를 변경해도 기존 레코드는 마이그레이션되지 않습니다.

키 삭제

키 등록을 삭제하기 전에 모든 활성 프로젝트에서 해당 키의 선택을 해제하거나 다른 키로 교체하세요.

123curl --fail-with-body -sS -X DELETE "$KEYS_URL/$KEY_ID" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID"

삭제에 성공하면 HTTP 200 응답에 object: "organization.external_key.deleted"가 포함됩니다. 클라우드에 있는 키는 삭제되지 않습니다.

문제 해결

오류	확인할 사항
401 또는 403	조직 관리자 API 키를 사용하고 외부 키를 등록할 권한이 있는지 확인하세요.
400 `external_key_provider_error`	클라우드 신뢰 관계, 읽기 권한, 네트워크 액세스, 키의 활성 상태와 알고리즘을 확인하세요.
400 요청 검증 오류	키 용도, AWS 키 자체의 ARN, Azure 또는 GCP 키의 정확한 버전을 확인하세요.
404	등록 ID와 조직을 확인하세요. 삭제된 등록 정보나 다른 조직의 등록 정보는 사용할 수 없습니다.
`external_key_used_by_active_projects`	해당 키를 선택한 모든 활성 프로젝트에서 선택을 해제하거나 다른 키로 교체하세요.
키가 더 이상 일치하지 않음	새 키 또는 키 버전을 등록하고 새 등록 ID를 선택하세요.

지원을 요청할 때는 오류 내용과 x-request-id를 공유하세요. 자격 증명은 절대 공유하지 마세요.

추천

시작하기

핵심 개념

SDK 및 CLI

클라우드 제공업체

자료

레거시 API

모델 선택하기

텍스트 및 코드

프롬프트 작성

추론

이미지

실시간 처리 및 오디오

특화 모델

Agents API

Agents SDK

ChatKit

검색 및 정보 조회

도구와 데이터 연결하기

도구를 활용한 워크플로우 구축하기

컴퓨터 및 코드

미디어

GPT-Live

Realtime API

음성 기능 개발

연결

오디오 처리

서비스 출시하기

성능 및 품질

평가

비용 및 처리량

안전 및 거버넌스

인프라 및 접근 권한

운영

핵심 개념

기획

개발

테스트 및 게시

전환 명세

가이드

자료

사용자 식별

ChatGPT 요금제 사용량

가이드

파일 업로드

API

성과 측정

광고주 API

API 레퍼런스

시작하기

시작하기

기초

둘러보기

지원 플랫폼

릴리스

워크플로우

주요 기능

Sites

dot

ChatGPT 스페이스

레퍼런스

맞춤 설정

설정 파일

에이전트 설정

ChatGPT와 Codex 확장하기

Linux

Windows

개발 워크플로우

확장 및 자동화

환경

Codex Cloud

Codex로 개발하기

서드 파티 통합

레퍼런스

권한

Codex Security

사이버 안전

시작하기

기능 설정

ID 및 액세스