OpenAI 상호 TLS를 사용하면 조직은 OpenAI API 트래픽에 추가 보안 계층을 구성할 수 있습니다. 구성 후 API 요청은 https://mtls.api.openai.com(또는 EU 데이터 레지던시 고객의 경우 https://mtls-eu.api.openai.com)로 보내야 하며, 올바른 API 키와 클라이언트 인증서가 제공된 경우에만 트래픽이 허용됩니다. mTLS는 https://platform.openai.com 대시보드에는 적용되지 않습니다. 이 기능은 현재 베타입니다.
mTLS 통합은 어떻게 설정하나요?
설정 탐색 막대에 “상호 TLS” 탭이 표시됩니다.
인증서 업로드
인증서 활성화
인증서를 업로드한 후 다음 단계는 인증서를 활성화하는 것입니다. 프로젝트에 대해 인증서가 활성화되면, 해당 프로젝트로 가는 모든 API 요청에도 대응하는 클라이언트 인증서가 필요해집니다. 프로젝트에 여러 인증서가 활성화되어 있으면, 대응하는 클라이언트 인증서 중 아무 것이나 전달할 수 있습니다. 조직에 대해 인증서가 활성화되면 모든 API 요청에 적용되며 모든 프로젝트에 “상속”됩니다.
CA 인증서 요구 사항
다음 요구 사항을 충족하는 PEM 형식의 X.509 CA 인증서를 업로드할 수 있습니다.
요청에 사용할 예정인 클라이언트 인증서에 직접 서명합니다.
Certificate Authority, Subject Key Identifier, Authority Key Identifier(KeyIdentifier 형식) 확장이 있습니다.
Key Usage: “Certificate Sign, CRL Sign” 권한이 있습니다.
1일 이내에 만료되도록 설정되어 있지 않습니다.
총 인증서 크기는 16kb 미만이어야 합니다.
클라이언트 인증서 요구 사항
클라이언트 인증서는 사전에 업로드한 인증서로 직접 서명되어야 합니다. 현재는 단일 길이 인증서 체인만 지원합니다. 그 밖에도 클라이언트 인증서는 다음 요구 사항을 충족해야 합니다.
Subject Key Identifier 및 Authority Key Identifier 확장(KeyIdentifier 형식)이 있습니다.
Key Usage: “Digital Signature, Key Encipherment” 권한이 있습니다.
Extended Key Usage: “TLS Web Client Authentication” 권한이 있습니다.
Subject Alternate Name 확장이 있습니다.
FAQ
API를 통해 mTLS를 구성할 수 있나요?
예. 자세한 내용은 https://platform.openai.com/docs/api-reference/에서 API Reference를 확인할 수 있습니다.
어떤 엔드포인트가 mTLS를 지원하나요?
이번 베타 기간 동안 mTLS는 다음에서 공식적으로 지원됩니다.
/v1/chat/completions (with all supported extensions e.g. image, audio, streaming, etc.)/v1/completions/v1/embeddings/v1/audio/transcriptions/v1/audio/speech/v1/files/v1/batches/v1/responses/v1/images/v1/moderations/v1/realtime (via server-side web sockets)/v1/fine_tuning/v1/tunnels
요청과 함께 클라이언트 인증서를 어떻게 보내나요?
cURL 요청의 경우 --cert 및 --key 옵션을 사용할 수 있습니다(매뉴얼 페이지는 여기 참조). 대부분의 다른 HTTP 클라이언트에서도 클라이언트 인증서를 전달하는 방법이 있습니다. 예: Python의 requests, JS의 fetch. 공식 SDK를 통해 HTTP 클라이언트 재정의도 지원합니다. Python 예시는 여기를 참조하세요.
프로덕션 트래픽에 mTLS를 적용하기 전에, 사용 중인 HTTP 클라이언트가 클라이언트 인증서 요청을 제대로 처리하는지 확인하세요(특정 브라우저의 WebSocket 등 일부는 그렇지 않습니다). 당사 서버는 클라이언트 인증서 요청에서 certificate_authorities 목록을 제공하지 않는다는 점에 유의하세요.
누가 인증서에 액세스하고 수정할 수 있나요?
https://platform.openai.com/settings/organization/mtls 대시보드 UI를 통해 조직 소유자가 인증서에 액세스하고 수정할 수 있습니다. Admin API Key(https://platform.openai.com/settings/organization/admin-keys)를 가진 사람도 인증서에 액세스/수정할 수 있습니다. 다만 주의하세요. 조직 수준에서 상호 TLS를 활성화하면 이러한 API 요청에도 인증서가 적용됩니다. 모든 mTLS 변경 사항은 감사 로그에 표시됩니다.
인증서는 몇 개까지 보유할 수 있나요?
각 조직은 최대 50개의 인증서를 업로드할 수 있으며, 이 인증서는 프로젝트 간에 공유할 수 있지만 다른 조직과는 공유할 수 없습니다. 한 번에 10개 프로젝트에 대해 인증서를 원자적으로 활성화/비활성화할 수 있습니다. 또는 조직이나 특정 프로젝트 1개에 대해 한 번에 10개의 인증서를 활성화/비활성화할 수 있습니다.
인증서를 업데이트하거나 삭제할 수 있나요?
인증서의 이름은 업데이트할 수 있지만, 콘텐츠는 업데이트할 수 없습니다. 또한 현재 어떤 범위에서도 활성 상태가 아닌 인증서는 삭제할 수 있습니다.
인증서 해지는 어떻게 작동하나요?
현재 CRL 또는 OCSP 스테이플링은 지원하지 않습니다. 권장되는 대안은 대신 API 키를 삭제하거나 교체하는 것입니다. CA 인증서를 교체하거나 유효 기간이 더 짧은 클라이언트 인증서를 사용할 수도 있습니다.
더 긴 길이의 인증서 체인을 사용할 수 있나요?
현재는 단일 길이 체인만 지원합니다. 즉, CA 인증서가 클라이언트 인증서에 직접 서명해야 합니다. 추가 질문이 있으면 Account Director에게 문의하세요.
권장 설정은 무엇인가요?
이 기능을 처음 설정할 때는 공식 프로덕션 트래픽을 처리하지 않는 스테이징 프로젝트로 시작하는 것을 권장합니다. 이 기회를 활용해 인증서가 머신에 올바르게 설정되어 있고 API 트래픽을 성공적으로 보낼 수 있는지 확인하세요. 그 밖에도 요구 사항을 가장 잘 이해하기 위해 조직의 보안 팀과 상담하는 것을 권장합니다.
추가 지원
대시보드와 API를 통해 mTLS 기능을 완전히 셀프 서비스로 이용할 수 있습니다. 다만 처음에 섀도 모드로 mTLS를 활성화하려면 Account Director에게 문의하거나 이 페이지의 오른쪽 하단에서 새 채팅을 시작해 지원 티켓을 여세요.
부록: 용어
CA 인증서: 요청과 함께 보낼 클라이언트 인증서에 직접 서명한 신뢰할 수 있는 인증서 중 하나입니다. 자체 서명된 CA 인증서를 사용해도 됩니다.
인증서 업로드: 계정에 CA 인증서를 추가하는 것입니다. 아직 mTLS에 대해 어디에도 적용되지 않지만, 구성을 시작할 수 있습니다.
범위: 특정 프로젝트 또는 전체 조직입니다.
범위에서 CA 인증서 활성화: 해당 범위에 대해 mTLS를 활성화하며, 모든 API 키 기반 요청에는 CA 인증서로 서명된 클라이언트 인증서가 필요합니다.
범위에서 CA 인증서 비활성화: 이 범위에서 요청을 확인하는 데 이 인증서를 사용하지 않도록 비활성화합니다. 해당 범위에 남아 있는 인증서가 없으면 mTLS는 사실상 꺼집니다.
인증서 상속: 조직에 대해 인증서를 활성화하면 모든 프로젝트에서도 활성화됩니다.