상호 TLS

상호 TLS (Mutual TLS)

상호 TLS(mTLS)는 OpenAI API 요청에 TLS 클라이언트 인증서 검증을 추가합니다. 조직 또는 프로젝트에 대해 신뢰할 수 있는 인증서를 활성화하면, 해당 범위의 요청은 일반 bearer 자격 증명에 더해 허용되는 클라이언트 인증서를 제시해야 합니다.

워크로드가 클라이언트 개인 키를 안전하게 보관할 수 있고, API 요청을 승인하기 전에 OpenAI가 그 인증서 신원을 검증하기를 원할 때 mTLS를 사용하세요. mTLS는 API 키, 서비스 계정 자격 증명 또는 워크로드 신원 접근 토큰을 대체하지 않습니다.

X.509 워크로드 신원 연합(workload identity federation)은 동일한 활성 mTLS 신뢰 앵커를 사용합니다. 인증서 교환은 수명이 짧은 bearer 토큰을 반환하며, 이후 API 호출은 여전히 그 bearer 토큰과 허용되는 API mTLS 인증서를 함께 보냅니다. X.509 인증서로 워크로드 신원 연합 구성하기를 참고하세요.

출처: 문서

본문

mTLS 구성 전에

모든 API 조직은 일반 역할 기반 접근 제어(RBAC)를 통해 mTLS를 관리할 수 있습니다:

  • api.mtls.read를 통해 주체는 인증서 설정을 나열·조회·테스트할 수 있습니다.
  • api.mtls.write를 통해 주체는 인증서를 업로드·업데이트·활성화·비활성화·삭제할 수 있습니다.

organization owner 역할에는 이 권한이 포함되지만, 커스텀 역할을 통해 부여할 수도 있습니다. 자세한 내용은 OpenAI 플랫폼에서 권한 관리하기를 참고하세요.

준비 사항:

  • 각 워크로드에 대한 클라이언트 인증서와 그 개인 키.
  • 클라이언트 인증서에서 신뢰 앵커까지 경로를 구성하는 데 필요한 중간 인증서(intermediate certificates).
  • 조직 또는 프로젝트 수준에서 활성화할 수 있는 안정적인 PEM 인코딩 신뢰 앵커.
  • 프로덕션 트래픽에 mTLS를 활성화하기 전의 중요하지 않은 프로젝트와 테스트된 복구 경로.

개인 키는 소스 제어 밖에 두세요. 개인 키, 인증서 내용 또는 bearer 자격 증명을 로그에 남기지 마세요.

신뢰 업로드 및 활성화

업로드는 인증서를 저장할 뿐 mTLS를 강제하지 않습니다. 활성화가 요청 동작을 변경하는 단계입니다.

  1. Organization settings > Security > Mutual TLS를 엽니다.
  2. 각 인증서 객체에 대해 PEM 인코딩 신뢰 앵커 하나를 업로드하세요. 권한(authority)과 회전 세대를 식별하는 이름을 주세요.
  3. 선택적으로, 그 앵커가 허용할 검증된 클라이언트 인증서를 제한하는 CEL 필터를 추가하세요.
  4. 중요하지 않은 프로젝트에 먼저 인증서를 활성화하세요. 모든 예상 워크로드에서 mTLS API 호스트를 통해 대표 요청을 보내세요.
  5. 검증이 성공한 뒤 다른 프로젝트나 조직에 인증서를 활성화하세요.

API를 통해 인증서를 관리할 수도 있습니다:

작업 엔드포인트
인증서 업로드 POST /v1/organization/certificates
조직 인증서 목록 GET /v1/organization/certificates
인증서 조회·업데이트·삭제 GET, POST, 또는 DELETE /v1/organization/certificates/{certificate_id}
조직에 대해 활성화·비활성화 POST /v1/organization/certificates/activate 또는 POST /v1/organization/certificates/deactivate
프로젝트에 대해 목록·활성화·비활성화 GET /v1/organization/projects/{project_id}/certificates, POST /v1/organization/projects/{project_id}/certificates/activate, 또는 POST /v1/organization/projects/{project_id}/certificates/deactivate

필요한 api.mtls.read 또는 api.mtls.write 권한이 있는 자격 증명을 사용하세요. 요청·응답 스키마는 organization certificates API 참조를 참고하세요.

인증서 요구 사항

인증서 객체마다 PEM 인코딩 신뢰 앵커 하나를 사용하세요. 업로드는 업로드 후 1일 이상 만료되지 않는 유효한 인증서를 포함해야 합니다. 클라이언트 인증서는 요청 검증을 위해 Authority Key Identifier(AKI)를 포함해야 합니다.

요청이 mTLS를 통과하려면:

  • 클라이언트 인증서가 요청 시점에 유효하고 TLS 클라이언트 인증에 적합해야 합니다.
  • 클라이언트 인증서가 활성화된 조직 또는 프로젝트 수준 신뢰 앵커로 유효한 경로를 구성해야 합니다.
  • 경로에 중간 인증서가 포함되면 클라이언트가 TLS 핸드셰이크 중에 그것을 제시해야 합니다.
  • 구성된 신뢰 앵커와 클라이언트 체인이 표준 X.509 클라이언트 인증서 경로 검증을 통과해야 합니다.

업로드에 PEM 인코딩 인증서가 하나보다 많으면 요청 체인 검증은 구성된 첫 번째 인증서만 앵커로 사용합니다. PEM 번들 의미에 의존하지 마세요.

OpenAI는 Authority Information Access(AIA) URL에서 누락된 중간 인증서를 가져오지 않으며, 인증서 폐기 목록(CRL) 또는 Online Certificate Status Protocol(OCSP) 확인을 수행하지 않습니다. 필요한 전체 체인을 제시하고 인시던트 대응은 인증서 회전, 비활성화, 자체 인증서 수명 주기 제어를 통해 관리하세요.

검증 순서 이해하기

OpenAI는 활성 조직 수준 인증서보다 활성 프로젝트 수준 인증서를 먼저 확인합니다. 어느 범위에도 활성 인증서가 없으면 mTLS는 요청에 인증서 검사를 추가하지 않습니다.

활성 인증서가 있으면 OpenAI는 다음 순서로 클라이언트 신원을 검증합니다:

  1. OpenAI는 먼저 기존 직접 경로를 시도합니다. 이는 요청 중간 인증서 없이 활성 앵커에 대해 클라이언트 인증서를 직접 검증합니다.
  2. 일반적인 직접 경로 불일치 후, OpenAI는 TLS 연결이 제시한 클라이언트 인증서와 중간 인증서로 요청 체인 검증을 시도합니다.
  3. 경로가 검증되면 OpenAI는 활성 인증서의 CEL 필터가 있으면 검증된 클라이언트 인증서에 대해 평가합니다.

요청 체인 검증은 기본적으로 사용 가능합니다.

요청 체인 경로는 일반적인 불일치 후의 폴백이지, 모든 직접 경로 오류에 대한 복구 경로가 아닙니다. 누락되거나 잘못된 인증서 자료, 누락된 AKI, 또는 직접 경로가 앵커를 선택한 후의 결정적 오류는 제시된 체인을 시도하지 않고 요청을 실패시킬 수 있습니다.

CEL로 클라이언트 인증서 필터링

필수는 아닌 Common Expression Language(CEL) 필터를 업로드된 인증서에 첨부해 그 앵커가 허용하는 검증된 클라이언트 인증서를 제한하세요. 표현식은 부울로 평가되어야 하며 직접 경로와 요청 체인 경로 모두에서 검증된 클라이언트 인증서에 대해 실행됩니다.

CEL은 다음 필드를 노출합니다:

  • subject.common_name, subject.country_code, subject.organization, subject.organizational_unit, subject.locality, subject.province, subject.street_address, subject.postal_code.
  • subject_alt_names, 목록이며 항목이 type, value, oid를 노출합니다. 지원되는 SAN 유형 식별자는 DNS, EMAIL, IP_ADDRESS, URI, CUSTOM입니다.

예를 들어 프로덕션 조직 단위와 특정 네임스페이스의 DNS SAN을 요구하세요:

subject.organizational_unit == "Production" &&
subject_alt_names.exists(san, san.type == DNS && san.value.endsWith(".example.com"))

검증되지만 필터와 일치하지 않는 인증서는 certificate_attribute_verification_failed로 실패합니다. OpenAI는 저장할 때 검증을 통과하지 못하는 정책을 거부합니다.

mTLS 호스트 사용

api.openai.com 대신 mTLS 호스트로 API 트래픽을 보내세요:

Host 사용
mtls.api.openai.com 기본 API mTLS 호스트.
mtls-us.api.openai.com 미국 지역 API mTLS 호스트.
mtls-eu.api.openai.com EU 지역 API mTLS 호스트.

mTLS는 호스트 기반입니다. 해당 API 표면에서 호출할 것과 동일한 /v1 경로를 사용하고, 워크로드가 사용하는 각 API와 모델을 테스트하세요. 경로와 모델 가용성은 지역 호스트 간에 다를 수 있습니다.

예를 들어 기본 mTLS 호스트에 일반 bearer 자격 증명과 클라이언트 인증서를 보내세요:

export OPENAI_MTLS_CERT_CHAIN="/path/to/client-chain.pem"
export OPENAI_MTLS_KEY="/path/to/client-key.pem"

curl https://mtls.api.openai.com/v1/models \
  --cert "$OPENAI_MTLS_CERT_CHAIN" \
  --key "$OPENAI_MTLS_KEY" \
  --header "Authorization: Bearer ***"

인증서 체인 파일에는 클라이언트 인증서가 먼저, 그다음 필요한 중간 인증서가 와야 합니다. 인증서 자료를 HTTP 헤더나 요청 본문에 보내지 마세요.

X.509 워크로드 신원 연합은 별도의 정확한 교환 엔드포인트를 사용합니다: POST https://mtls.auth.openai.com/oauth/token. 이 교환은 수명이 짧은 bearer 토큰을 생성하며, 인증서 전용 API 인증을 제공하지 않습니다. 전체 요청 형태는 워크로드 신원 토큰 교환 참조를 참고하세요.

인증서 회전

기존 워크로드가 계속 작동하도록 겹치면서 신뢰 앵커를 회전하세요:

  1. 이전 앵커를 비활성화하지 않고 새 신뢰 앵커를 업로드하세요.
  2. 의도한 각 프로젝트 또는 조직 수준에서 새 앵커를 활성화하세요.
  3. 새 앵커에 체이닝되는 클라이언트 인증서를 제시하도록 워크로드를 업데이트한 뒤, 사용하는 각 mTLS 호스트와 API 표면을 테스트하세요.
  4. 모든 워크로드가 이동한 뒤 이전 앵커를 비활성화하세요.
  5. 조직과 모든 프로젝트에 대해 비활성화한 뒤에만 이전 인증서를 삭제하세요.

구성된 신뢰 앵커를 변경하지 않고 중간 인증서를 회전할 수 있습니다. 이후 요청에 새 전체 체인을 제시하세요.

요청 문제 해결

구성 오류와 일시적 서비스 오류를 구별하려면 안정적인 오류 코드를 사용하세요:

오류 코드 확인할 사항
certificate_required 활성 인증서가 적용되지만 요청이 필요한 클라이언트 인증서 자료를 제시하지 않았습니다.
invalid_certificate OpenAI가 클라이언트 인증서를 디코딩하거나 구문 분석할 수 없거나, 인증서에 검증에 필요한 AKI가 없습니다.
certificate_verification_failed 클라이언트 인증서 또는 제시된 체인이 활성 신뢰 앵커에 도달하지 않습니다.
certificate_attribute_verification_failed 인증서 경로가 검증되었지만 CEL 필터가 검증된 클라이언트 인증서를 거부했습니다.
authentication_temporarily_unavailable 검증자 타임아웃, 내부 의존성 오류 또는 CEL 평가자 오류로 HTTP 503이 발생했습니다. 평소 일시적 오류 정책으로 재시도하세요.

관리 요청의 경우 mtls_certificate_invalid는 업로드된 PEM이 검증을 통과하지 못했음, expired_certificate는 너무 빨리 만료되거나 이미 만료되었음, mtls_cel_policy_invalid는 필터가 검증을 통과하지 못함, certificate_in_use는 삭제 전에 인증서를 비활성화해야 함을 의미합니다.

현재 제한 사항

  • 조직은 최대 50개의 인증서 객체를 업로드할 수 있습니다.
  • mTLS는 일반 API 인증에 인증서 검증을 추가합니다. 인증서 전용 API 권한 부여를 제공하지는 않습니다.
  • OpenAI는 AIA 중간 인증서를 가져오지 않으며 CRL 또는 OCSP 확인을 수행하지 않습니다.
  • Private Link는 mTLS와 호환되지 않습니다. 비공개 Azure 네트워크 경로가 필요하면 Private Link를 참고하세요.
  • 지원되는 API mTLS 호스트는 mtls.api.openai.com, mtls-us.api.openai.com, mtls-eu.api.openai.com입니다. 다른 모든 지역 API 호스트에 mTLS 대응이 있다고 가정하지 마세요.
  • X.509 워크로드 신원 연합은 리프레시 토큰을 반환하지 않으며 DPoP, cnf 클레임 또는 인증서 바인딩 bearer 토큰을 사용하지 않습니다. X.509 인증서로 워크로드 신원 연합 구성하기를 참고하세요.

더 알아보기 (Learn more)