상호 TLS

상호 TLS(mTLS)를 사용하면 OpenAI API 요청에서 TLS 클라이언트 인증서도 검증합니다. 조직이나 프로젝트에서 신뢰할 인증서를 활성화하면 해당 범위의 요청에는 기존 Bearer 자격 증명과 함께 허용된 클라이언트 인증서를 제시해야 합니다.

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

mTLS 설정 전 준비 사항

모든 API 조직은 기존 역할 기반 접근 제어(RBAC)를 사용해 mTLS를 관리할 수 있습니다.

• api.mtls.read 권한이 있는 주체는 인증서 목록을 조회하고 인증서 설정을 확인하거나 테스트할 수 있습니다.
• api.mtls.write 권한이 있는 주체는 인증서를 업로드, 업데이트, 활성화, 비활성화하거나 삭제할 수 있습니다.

조직 소유자 역할에는 이러한 권한이 포함되어 있으며, 사용자 지정 역할로도 권한을 부여할 수 있습니다. 자세한 내용은 OpenAI 플랫폼에서 권한 관리하기를 참고하세요.

다음 항목을 준비하세요.

• 각 워크로드에서 사용할 클라이언트 인증서와 해당 개인 키
• 클라이언트 인증서에서 신뢰 앵커까지 인증 경로를 구성하는 데 필요한 중간 인증서
• 조직 또는 프로젝트 수준에서 활성화할 수 있고 안정적으로 유지할 수 있는 PEM 인코딩 신뢰 앵커
• 프로덕션 트래픽에 mTLS를 활성화하기 전에 테스트에 사용할 중요도가 낮은 프로젝트와 검증된 복구 절차

개인 키는 버전 관리 시스템 외부에 보관하세요. 개인 키, 인증서 내용 또는 Bearer 자격 증명을 로그에 기록하지 마세요.

신뢰 앵커 업로드 및 활성화

인증서를 업로드하면 인증서가 저장됩니다. 요청에 mTLS를 적용하려면 인증서를 활성화해야 합니다.

1. 조직 설정 > 보안 > 상호 TLS를 여세요.
2. 인증서 객체마다 PEM으로 인코딩한 신뢰 앵커를 하나씩 업로드하세요. 발급 기관과 교체 세대를 구분할 수 있는 이름을 지정하세요.
3. 필요하면 CEL 필터를 추가해 검증된 클라이언트 인증서 중 해당 앵커가 허용할 인증서를 제한하세요.
4. 먼저 중요도가 낮은 프로젝트에서 인증서를 활성화하세요. 사용할 예정인 모든 워크로드에서 mTLS API 호스트로 대표적인 요청을 보내세요.
5. 검증에 성공하면 다른 프로젝트나 조직에서도 인증서를 활성화하세요.

API로도 인증서를 관리할 수 있습니다.

작업에 필요한 api.mtls.read 또는 api.mtls.write 권한이 있는 자격 증명을 사용하세요. 요청 및 응답 스키마는 조직 인증서 API 레퍼런스를 참고하세요.

인증서 요구 사항

인증서 객체마다 PEM으로 인코딩한 신뢰 앵커를 하나씩 사용하세요. 업로드하는 인증서는 유효해야 하며 업로드 시점에 남은 유효 기간이 하루를 초과해야 합니다. 요청을 검증하려면 클라이언트 인증서에 발급 기관 키 식별자(AKI)가 있어야 합니다.

요청이 mTLS 검증을 통과하려면 다음 조건을 충족해야 합니다.

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

한 번에 여러 PEM 인코딩 인증서를 업로드해도 요청에 제시된 체인을 검증할 때는 설정된 첫 번째 인증서만 앵커로 사용합니다. 여러 인증서가 PEM 번들로 처리된다고 가정하지 마세요.

OpenAI는 발급 기관 정보 액세스(AIA) URL에서 누락된 중간 인증서를 가져오지 않으며, 인증서 폐기 목록(CRL)이나 온라인 인증서 상태 프로토콜(OCSP)을 통한 확인도 수행하지 않습니다. 필요한 인증서 체인 전체를 제시하고, 사고가 발생하면 인증서 교체, 비활성화 및 자체 인증서 수명 주기 관리 절차를 통해 대응하세요.

인증서 검증 순서

OpenAI는 프로젝트 수준의 활성 인증서를 먼저 확인한 다음 조직 수준의 활성 인증서를 확인합니다. 두 범위 모두 활성 인증서가 없으면 해당 요청에 mTLS 인증서 검증을 추가하지 않습니다.

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

1. 먼저 기존 직접 검증 경로를 시도합니다. 이 경로에서는 요청에 포함된 중간 인증서를 사용하지 않고 활성 앵커를 기준으로 클라이언트 인증서를 직접 검증합니다.
2. 직접 검증에서 단순히 일치하는 앵커를 찾지 못하면 요청 체인 검증을 시도합니다. 이때 TLS 연결에서 제시된 클라이언트 인증서와 중간 인증서를 사용합니다.
3. 경로 검증에 성공하고 활성 인증서에 CEL 필터가 설정되어 있으면 검증된 클라이언트 인증서에 해당 필터를 적용합니다.

요청 체인 검증은 기본적으로 사용할 수 있습니다.

요청 체인 검증은 직접 검증에서 단순히 일치하는 앵커를 찾지 못했을 때 시도합니다. 직접 검증 중에 오류가 발생하면 이 단계로 넘어가지 않을 수 있습니다. 인증서 데이터가 누락되었거나 형식이 잘못된 경우, AKI가 없는 경우 또는 직접 검증 경로에서 앵커를 선택한 후 결정적 오류가 발생한 경우에는 제시된 체인을 검증하지 않고 요청이 실패할 수 있습니다.

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

필요하면 업로드한 인증서에 공통 표현 언어(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 트래픽은 api.openai.com 대신 mTLS 호스트로 보내세요.

mTLS는 호스트 단위로 적용됩니다. 해당 API를 호출할 때와 동일한 /v1 경로를 사용하고 워크로드가 사용하는 각 API와 모델을 테스트하세요. 사용 가능한 경로와 모델은 리전별 호스트에 따라 다를 수 있습니다.

예를 들어 기본 mTLS 호스트에 기존 Bearer 자격 증명과 클라이언트 인증서를 함께 보내려면 다음 명령어를 실행하세요.

1234567export 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 $OPENAI_API_KEY"

인증서 체인 파일에는 클라이언트 인증서를 먼저 넣고 그 뒤에 필요한 중간 인증서를 넣으세요. HTTP 헤더나 요청 본문에 인증서 데이터를 넣어 보내지 마세요.

X.509 기반 워크로드 ID 페더레이션에서는 인증서 교환에 별도로 지정된 엔드포인트인 POST https://mtls.auth.openai.com/oauth/token을 사용합니다. 이 교환으로 유효 기간이 짧은 Bearer 토큰을 받습니다. 인증서만으로 API 인증을 수행할 수는 없습니다. 전체 요청 형식은 워크로드 ID 토큰 교환 레퍼런스를 참고하세요.

인증서 교체

기존 워크로드가 계속 작동하도록 새 신뢰 앵커와 기존 신뢰 앵커의 활성 기간을 겹치게 하세요.

1. 기존 신뢰 앵커를 활성 상태로 유지한 채 새 신뢰 앵커를 업로드하세요.
2. 대상 프로젝트 각각에서 또는 조직 수준에서 새 앵커를 활성화하세요.
3. 새 앵커로 체인이 이어지는 클라이언트 인증서를 제시하도록 워크로드를 업데이트한 다음, 각 워크로드가 사용하는 모든 mTLS 호스트와 API 인터페이스를 테스트하세요.
4. 모든 워크로드가 새 앵커로 전환된 후 기존 앵커를 비활성화하세요.
5. 조직과 모든 프로젝트에서 기존 인증서를 비활성화한 후에만 삭제하세요.

설정된 신뢰 앵커를 변경하지 않고도 중간 인증서를 교체할 수 있습니다. 이후 요청에서는 새 인증서 체인 전체를 제시하세요.

요청 오류 해결

일관되게 제공되는 다음 오류 코드를 사용해 설정 오류와 일시적인 서비스 오류를 구분하세요.

인증서 관리 요청에서 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 기반 워크로드 ID 페더레이션은 갱신 토큰을 반환하지 않으며 DPoP, cnf 클레임 또는 인증서에 바인딩된 Bearer 토큰을 사용하지 않습니다. X.509 인증서로 워크로드 ID 페더레이션 구성하기를 참고하세요.