X.509 인증서로 워크로드 ID 페더레이션 구성하기

X.509 워크로드 ID 페더레이션을 사용하면 워크로드가 TLS 클라이언트 인증서의 ID를 단기 OpenAI 액세스 토큰으로 교환할 수 있습니다. 그런 다음 액세스 토큰과 허용된 클라이언트 인증서를 함께 제시해 OpenAI API를 호출합니다. 이 플로우에서는 액세스 토큰이 API 키를 대체하며, 클라이언트 인증서는 계속 필요합니다.

토큰 교환 요청과 응답에 관한 자세한 내용은 워크로드 ID 토큰 교환 레퍼런스를 참조하세요. 상호 TLS 권한, 인증서 요구 사항과 활성화, mTLS 호스트, 인증서 교체에 관한 내용은 상호 TLS 가이드를 참조하세요.

작동 방식

X.509 워크로드 ID 교환은 다음 다섯 단계로 진행됩니다.

1. 조직이 기존 상호 TLS 설정에서 신뢰할 수 있는 루트 인증서를 업로드하고 활성화합니다.
2. X.509 워크로드 ID 공급자가 검증된 클라이언트 인증서에서 openai.* 속성을 도출합니다. 이때 비어 있지 않은 openai.subject 값 하나를 반드시 도출해야 합니다.
3. 서비스 계정 매핑은 이렇게 도출된 ID에 프로젝트 내 OpenAI 서비스 계정 하나를 사용할 권한을 부여합니다.
4. 워크로드가 mtls.auth.openai.com의 X.509 토큰 엔드포인트에 인증서를 제시하고 단기 Bearer 토큰을 요청합니다. 인증서는 TLS 연결을 통해 전달되므로 요청 본문에는 subject_token이 없습니다.
5. 워크로드가 API 호출 권한을 확인받기 위해 mtls.api.openai.com의 API 경로에 Bearer 토큰과 클라이언트 인증서를 함께 제시합니다.

API 요청을 처리할 때는 Bearer 토큰과 인증서가 각각 인가 조건을 충족하는지 독립적으로 확인합니다. 인증서만으로는 OpenAI API를 호출할 권한이 부여되지 않습니다.

시작하기 전에

다음 항목이 필요합니다.

• 조직의 상호 TLS 인증서와 워크로드 ID 공급자를 관리할 권한
• 워크로드에서 사용할 프로젝트와 서비스 계정
• 클라이언트 인증서와 해당 개인 키, 신뢰할 수 있는 루트 인증서까지 체인을 구성하는 데 필요한 모든 중간 인증서
• 조직 또는 프로젝트 수준에서 활성화된 신뢰할 수 있는 루트 인증서

개인 키는 버전 관리 대상에서 제외하고 해당 키를 사용하는 워크로드만 접근할 수 있도록 제한하세요. 개인 키, 인증서 내용, 반환된 액세스 토큰을 로그에 기록하지 마세요.

상호 TLS 인증서 신뢰 설정

X.509 워크로드 ID 공급자는 조직의 기존 상호 TLS 인증서 설정을 사용합니다. 공급자가 직접 인증서를 업로드하거나 별도의 인증서 신뢰 저장소를 관리하지 않습니다.

상호 TLS 가이드에서 인증서 요구 사항, mTLS 호스트, 인증서 활성화 방식, CEL 필터, 클라이언트 설정을 확인하세요. 그런 다음 조직 설정 > 보안 > 상호 TLS를 열고 신뢰할 수 있는 인증서를 PEM 형식으로 업로드하세요. 조직 전체 또는 X.509 워크로드 ID 페더레이션을 사용할 각 프로젝트에서 인증서를 활성화하세요.

클라이언트 인증서 체인에 중간 인증서가 포함된 경우, 안정적으로 유지되는 인증서를 신뢰 앵커로 설정하세요. TLS 핸드셰이크 시 리프 인증서를 먼저 제시한 뒤 현재 사용하는 중간 인증서를 순서대로 제시하세요. OpenAI는 요청에 포함된 중간 인증서를 사용하며 누락된 중간 인증서를 인증서 URL에서 가져오지 않습니다.

X.509 공급자 구성

다음 단계에 따라 X.509 공급자를 구성하세요.

1. 조직 설정 > 보안 > 워크로드 ID 공급자를 열고 ID 공급자 만들기를 선택하세요.
2. X.509를 공급자 유형으로 선택한 뒤 이름을 입력하세요. 설명은 선택 사항입니다. X.509 공급자는 OIDC 발급자, 대상, 검색 또는 JWKS 설정을 사용하지 않습니다. 공급자를 만든 후에는 유형을 변경할 수 없습니다.
3. 고급 설정에서 필요에 따라 속성 조건에 CEL 표현식을 추가하세요. 이 조건을 사용하면 매핑을 찾기 전에 인증서를 거부할 수 있습니다.
4. 속성 변환 항목에서 필수 변환인 openai.subject에 비어 있지 않은 표현식을 입력하세요. X.509를 선택하면 대시보드가 subject 행을 추가하고 openai. 접두사를 표시하고 적용합니다. 워크로드를 식별할 수 있고 값이 안정적으로 유지되는 인증서 속성을 선택하세요.
5. 필요한 경우 다른 고유한 openai.* 이름으로 변환을 추가한 뒤 만들기를 선택하세요.

다음 예시에서는 인증서의 일반 이름(CN)을 표준 주체 식별자로 사용하고, 조직 단위(OU)를 추가 매핑 속성으로 제공합니다.

12345678910[
  {
    "attribute": "openai.subject",
    "expression": "assertion.subject.common_name"
  },
  {
    "attribute": "openai.environment",
    "expression": "assertion.subject.organizational_unit"
  }
]

인증서 정보는 assertion.subject와 assertion.subject_alt_names에서 참조할 수 있습니다. 매핑에 사용할 변환 결과는 스칼라 값이어야 합니다. 추가하는 변환마다 고유한 openai.* 이름을 사용해야 합니다.

예를 들어 다음 속성 조건 표현식을 사용하면 공급자가 프로덕션 인증서만 허용하도록 제한할 수 있습니다.

assertion.subject.organizational_unit == "Production"

서비스 계정 매핑 만들기

1. X.509 공급자 세부 정보 페이지에서 매핑 만들기를 선택하세요.
2. 대상 프로젝트와 서비스 계정을 선택하고 워크로드에 필요한 API 권한만 부여하세요.
3. 키 및 값 필드에 정확히 일치해야 하는 openai.subject 값을 지정하세요. X.509 매핑은 어설션이 없는 경우(빈 객체 {}로 표시)와 어설션의 키가 모두 openai.로 시작하는 경우를 지원합니다.
4. 만들기를 선택하세요.

예시 설정은 다음과 같습니다.

X.509 매핑은 인증서에서 도출한 openai.* 속성을 사용합니다. sub, iss, aud 같은 원본 JWT 클레임은 매핑 조건으로 사용하지 않습니다.

공급자 목록에서 공급자 ID를 확인할 수 있습니다. 매핑 세부 정보에는 선택한 서비스 계정과 해당 계정의 ID가 표시됩니다. 워크로드가 토큰 교환 시 두 ID를 모두 전송하므로 기록해 두세요.

SDK에서 X.509 워크로드 ID 사용하기

인증서 체인, 개인 키, 공급자, 서비스 계정에 해당하는 환경 변수를 설정하세요.

1234export OPENAI_MTLS_CERT_CHAIN="/path/to/client-chain.pem"
export OPENAI_MTLS_KEY="/path/to/client-key.pem"
export OPENAI_IDENTITY_PROVIDER_ID="idp_example"
export OPENAI_SERVICE_ACCOUNT_ID="svc_acct_example"

인증서 체인 파일에는 리프 인증서를 먼저 넣고, 중간 인증서가 있으면 그 뒤에 순서대로 넣으세요. 요청 본문에는 인증서 데이터나 subject_token을 포함하지 마세요.

이 값으로 OpenAI SDK 클라이언트를 구성하세요. SDK는 토큰 교환과 API 요청 시 클라이언트 인증서를 제시하고, API 요청을 mTLS 엔드포인트로 보내며, 단기 액세스 토큰을 자동으로 갱신합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39import { readFile } from "node:fs/promises";

import OpenAI from "openai";
import { workloadIdentity } from "openai/auth/x509-transport";

const certificatePath = process.env.OPENAI_MTLS_CERT_CHAIN;
const privateKeyPath = process.env.OPENAI_MTLS_KEY;
const identityProviderId = process.env.OPENAI_IDENTITY_PROVIDER_ID;
const serviceAccountId = process.env.OPENAI_SERVICE_ACCOUNT_ID;

if (
  !certificatePath ||
  !privateKeyPath ||
  !identityProviderId ||
  !serviceAccountId
) {
  throw new Error(
    "Set OPENAI_MTLS_CERT_CHAIN, OPENAI_MTLS_KEY, OPENAI_IDENTITY_PROVIDER_ID, and OPENAI_SERVICE_ACCOUNT_ID"
  );
}

const credential = workloadIdentity.fromX509({
  certificateChain: await readFile(certificatePath, "utf8"),
  privateKey: await readFile(privateKeyPath, "utf8"),
  identityProviderId,
  serviceAccountId,
});

try {
  const client = new OpenAI({ credential });
  const response = await client.responses.create({
    model: "gpt-5.6-terra",
    input: "Say hello from X.509 workload identity federation.",
  });

  console.log(response.output_text);
} finally {
  await credential.close();
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26import os
import ssl

from openai import DefaultHttpx2Client, OpenAI
from openai.auth import x509_workload_identity

tls_context = ssl.create_default_context()
tls_context.load_cert_chain(
    certfile=os.environ["OPENAI_MTLS_CERT_CHAIN"],
    keyfile=os.environ["OPENAI_MTLS_KEY"],
)

with OpenAI(
    base_url="https://mtls.api.openai.com/v1",
    workload_identity=x509_workload_identity(
        identity_provider_id=os.environ["OPENAI_IDENTITY_PROVIDER_ID"],
        service_account_id=os.environ["OPENAI_SERVICE_ACCOUNT_ID"],
    ),
    http_client=DefaultHttpx2Client(verify=tls_context, follow_redirects=False),
) as client:
    response = client.responses.create(
        model="gpt-5.6-terra",
        input="Say hello from X.509 workload identity federation.",
    )

    print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"
	"net/http"
	"os"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/auth"
	"github.com/openai/openai-go/v3/option"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	certificate, err := tls.LoadX509KeyPair(
		os.Getenv("OPENAI_MTLS_CERT_CHAIN"),
		os.Getenv("OPENAI_MTLS_KEY"),
	)
	if err != nil {
		log.Fatal(err)
	}

	transport, err := auth.NewX509Transport(&http.Transport{
		TLSClientConfig: &tls.Config{
			Certificates: []tls.Certificate{certificate},
			MinVersion:   tls.VersionTLS12,
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	defer transport.Close()

	client := openai.NewClient(
		option.WithX509WorkloadIdentity(auth.X509WorkloadIdentity{
			IdentityProviderID: os.Getenv("OPENAI_IDENTITY_PROVIDER_ID"),
			ServiceAccountID:   os.Getenv("OPENAI_SERVICE_ACCOUNT_ID"),
			Transport:          transport,
		}),
	)

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-5.6-terra",
		Input: responses.ResponseNewParamsInputUnion{
			OfString: openai.String("Say hello from X.509 workload identity federation."),
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.client.okhttp.X509Transport;
import com.openai.client.okhttp.X509WorkloadIdentity;
import com.openai.models.responses.ResponseCreateParams;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.KeyStore;
import java.time.Duration;
import java.util.Arrays;
import javax.net.ssl.KeyManagerFactory;
import javax.net.ssl.TrustManagerFactory;
import javax.net.ssl.X509ExtendedKeyManager;
import javax.net.ssl.X509TrustManager;

char[] password = System.getenv("OPENAI_X509_KEYSTORE_PASSWORD").toCharArray();
try {
  KeyStore keyStore = KeyStore.getInstance("PKCS12");
  try (InputStream input =
      Files.newInputStream(Paths.get(System.getenv("OPENAI_X509_KEYSTORE_PATH")))) {
    keyStore.load(input, password);
  }

  KeyManagerFactory keyManagers =
      KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
  keyManagers.init(keyStore, password);
  X509ExtendedKeyManager keyManager =
      Arrays.stream(keyManagers.getKeyManagers())
          .filter(X509ExtendedKeyManager.class::isInstance)
          .map(X509ExtendedKeyManager.class::cast)
          .findFirst()
          .orElseThrow(() -> new IllegalStateException("No X.509 key manager available"));

  TrustManagerFactory trustManagers =
      TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
  trustManagers.init((KeyStore) null);
  X509TrustManager trustManager =
      Arrays.stream(trustManagers.getTrustManagers())
          .filter(X509TrustManager.class::isInstance)
          .map(X509TrustManager.class::cast)
          .findFirst()
          .orElseThrow(() -> new IllegalStateException("No X.509 trust manager available"));

  X509Transport transport =
      X509Transport.builder()
          .keyManager(keyManager)
          .certificateAlias(System.getenv("OPENAI_X509_CERTIFICATE_ALIAS"))
          .trustManager(trustManager)
          .build();
  X509WorkloadIdentity identity =
      X509WorkloadIdentity.builder()
          .identityProviderId(System.getenv("OPENAI_IDENTITY_PROVIDER_ID"))
          .serviceAccountId(System.getenv("OPENAI_SERVICE_ACCOUNT_ID"))
          .transport(transport)
          .refreshBuffer(Duration.ofMinutes(10))
          .build();

  OpenAIClient client = OpenAIOkHttpClient.builder().x509WorkloadIdentity(identity).build();
  try {
    ResponseCreateParams params =
        ResponseCreateParams.builder()
            .model("gpt-5.6-terra")
            .input("Say hello from X.509 workload identity federation.")
            .build();

    client.responses().create(params).output().stream()
        .flatMap(item -> item.message().stream())
        .flatMap(message -> message.content().stream())
        .flatMap(content -> content.outputText().stream())
        .forEach(outputText -> System.out.println(outputText.text()));
  } finally {
    client.close();
  }
} finally {
  Arrays.fill(password, '\0');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32require "openai"
require "openssl"

certificate_chain = OpenSSL::X509::Certificate.load(
  File.binread(ENV.fetch("OPENAI_MTLS_CERT_CHAIN"))
)
certificate, *intermediates = certificate_chain
private_key = OpenSSL::PKey.read(File.binread(ENV.fetch("OPENAI_MTLS_KEY")))

http_client = OpenAI::NetHTTPClient.new do |connection|
  connection.cert = certificate
  connection.extra_chain_cert = intermediates
  connection.key = private_key
end

workload_identity = OpenAI::Auth::X509WorkloadIdentity.new(
  identity_provider_id: ENV.fetch("OPENAI_IDENTITY_PROVIDER_ID"),
  service_account_id: ENV.fetch("OPENAI_SERVICE_ACCOUNT_ID"),
  http_client: http_client
)

begin
  client = OpenAI::Client.new(api_key: nil, workload_identity: workload_identity)
  response = client.responses.create(
    model: "gpt-5.6-terra",
    input: "Say hello from X.509 workload identity federation."
  )

  puts(response.output_text)
ensure
  http_client.close
end

이 예시를 실행하려면 위의 X.509 구성을 지원하는 OpenAI SDK 버전이 필요합니다. JavaScript SDK는 7.8.0 이상이어야 하며 피어 종속성인 undici가 설치되어 있어야 합니다. 다른 언어의 SDK는 Python 3.6.0 이상, Go 3.54.0 이상, Java 4.55.0 이상, Ruby 0.83.0 이상이어야 합니다.

Java 예시에서는 PKCS12 키 저장소를 로드해 X509ExtendedKeyManager를 생성하고, 플랫폼의 기본 신뢰 저장소를 사용해 X509TrustManager를 생성합니다. 이 예시를 실행하려면 OPENAI_X509_KEYSTORE_PATH, OPENAI_X509_KEYSTORE_PASSWORD, OPENAI_X509_CERTIFICATE_ALIAS를 설정하세요. SDK에 PEM 기반 또는 하드웨어 기반 관리자를 직접 제공할 수도 있습니다.

인증서 수동 교환

토큰 교환 프로토콜을 직접 확인하거나 구현하려면 X.509 토큰 엔드포인트에 인증서를 제시하세요.

123456789101112curl --cert "$OPENAI_MTLS_CERT_CHAIN" \
  --key "$OPENAI_MTLS_KEY" \
  --request POST "https://mtls.auth.openai.com/oauth/token" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token_type": "urn:openai:params:oauth:token-type:x509",
  "identity_provider_id": "${OPENAI_IDENTITY_PROVIDER_ID}",
  "service_account_id": "${OPENAI_SERVICE_ACCOUNT_ID}"
}
JSON

교환에 성공하면 일반적인 단기 Bearer 토큰이 반환됩니다.

12345678{
  "access_token": "eyJ...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": 1789045200,
  "scope": "api.model.read api.model.request"
}

scope 속성은 일치하는 서비스 계정 매핑에 권한이 설정되어 있을 때만 반환됩니다.

위의 만료 값은 예시입니다. 검증된 클라이언트 인증서가 더 일찍 만료되면 반환되는 토큰의 유효 기간도 짧아질 수 있습니다. 토큰 교환 응답 필드에서 expires_in과 expires_at의 단위와 의미를 확인하세요.

성공 응답에서 access_token 값을 읽어 애플리케이션의 자격 증명 저장소나 OPENAI_WIF_ACCESS_TOKEN 같은 환경 변수에 저장하세요. 이 값은 비밀 정보이므로 출력하거나 로그에 기록하거나 커밋하지 마세요.

OpenAI API 수동 호출

OPENAI_MODEL을 현재 기본 모델인 gpt-6-astra 또는 대상 프로젝트에서 사용할 수 있는 다른 모델로 설정하세요. 그런 다음 Bearer 토큰과 허용된 클라이언트 인증서를 API mTLS 엔드포인트에 함께 보내세요.

1234567curl --request POST \
  --cert "$OPENAI_MTLS_CERT_CHAIN" \
  --key "$OPENAI_MTLS_KEY" \
  --header "Authorization: Bearer $OPENAI_WIF_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data "{\"model\":\"$OPENAI_MODEL\",\"input\":\"Say hello in one sentence.\"}" \
  "https://mtls.api.openai.com/v1/responses"

API 키 대신 Bearer 토큰을 사용하고, API 요청 시 허용된 클라이언트 인증서를 계속 제시하세요.

Bearer 토큰은 인증서와 암호학적으로 연결되어 있지 않습니다. 가장 간단한 구성은 토큰 교환에 사용한 인증서를 API 요청에도 사용하는 것입니다. 현재 적용되는 동일한 API mTLS 정책을 독립적으로 충족하는 다른 인증서도 API 요청에 사용할 수 있습니다.

토큰 유효 기간과 갱신

X.509 워크로드 ID 토큰의 유효 기간은 최대 1시간이며, 검증된 클라이언트 인증서의 만료 시점을 넘지 않습니다. 토큰 교환 시 갱신 토큰은 반환되지 않습니다. 새 액세스 토큰을 받으려면 인증서 교환을 다시 수행하세요.

수동으로 교환할 때는 액세스 토큰과 함께 expires_at을 저장하고 해당 시각 전에 다시 교환하도록 예약하세요. 이때 시스템 간 시각 차이와 요청 지연을 고려하세요. 예시는 토큰 갱신 가이드를 참조하세요.

중간 인증서를 교체할 때는 설정된 루트 인증서를 변경할 필요가 없습니다. 이후 토큰 교환과 API 요청에서는 새 인증서 체인 전체를 제시하세요.

토큰 교환 문제 해결

X.509 토큰 교환 시에는 일반적인 OAuth 오류가 반환되며, 인증서, 루트 인증서, 공급자 또는 매핑의 세부 정보는 공개되지 않습니다.

X.509 교환이 실패해도 OIDC 또는 일반 OAuth 플로우로 전환되지 않습니다.

제한 사항

• X.509 워크로드 ID 공급자는 별도의 인증서 신뢰 저장소를 관리하지 않습니다.
• Bearer 토큰은 인증서에 바인딩되지 않으며 DPoP나 cnf 클레임을 사용하지 않습니다.
• 인증서를 교환했다고 해서 인증서만으로 API 호출 권한이 부여되지는 않습니다. API 요청에는 Bearer 토큰과 허용된 클라이언트 인증서가 모두 필요합니다.
• OpenAI는 누락된 중간 인증서를 AIA URL에서 가져오지 않습니다. TLS 협상 시 인증서 체인 전체를 제시하세요.
• OpenAI는 이 플로우에서 인증서 폐기 목록(CRL)을 확인하거나 OCSP 검사를 수행하지 않습니다. 인증서 관련 사고 대응 계획을 세울 때는 상호 TLS 루트 인증서, 공급자, 매핑의 제어 기능과 발급된 토큰의 짧은 유효 기간을 고려하세요.
• 이 플로우는 SPIFFE X.509-SVID를 지원하지 않습니다. SPIFFE 가이드에서는 계속 JWT-SVID를 사용합니다.