Okta와 함께 WIF 사용하기

Okta는 OAuth 2.0 client_credentials 그랜트를 통해 서비스 애플리케이션에 OIDC 액세스 토큰을 발급함으로써 워크로드 ID 공급자 역할을 할 수 있습니다. 워크로드는 Okta에 인증하고(일반적으로 private_key_jwt를 사용하므로 공유 시크릿이 저장되지 않음), 서명된 "JSON Web Token"(JSON 웹 토큰), 즉 JWT를 받은 다음, 해당 JWT를 Anthropic과 교환하여 단기 액세스 토큰을 얻습니다.

Okta 인증 서버의 발급자 URL은 https://<your-domain>.okta.com/oauth2/<auth-server-id> 형식을 따릅니다. 기본 제공 default 서버를 사용하는 경우 경로는 /oauth2/default입니다.

Okta를 구성하고 인증하는 방법은 다양하며, 이는 본 문서의 범위를 벗어납니다. 구성 및 인증 메커니즘이 회사의 지침과 보안 관행을 따르는지 확인하세요.

사전 요구 사항

• WIF 개념에 대한 이해: 서비스 계정, 페더레이션 발급자, 페더레이션 규칙.
• API Access Management가 활성화된 Okta 조직(커스텀 인증 서버에 필요).
• Anthropic 조직의 Claude Console에서 서비스 계정, 페더레이션 발급자, 페더레이션 규칙을 생성할 수 있는 권한.
• Okta의 /v1/token 엔드포인트에서 토큰을 요청하고 api.anthropic.com에 접근할 수 있는 워크로드.

Okta 구성

개략적으로 다음 작업이 필요합니다.

1. Okta 서비스 애플리케이션을 생성합니다.
2. 기본 인증 서버를 구성하거나(또는 새 커스텀 인증 서버를 생성하여) 오디언스, 스코프, 액세스 정책, 그리고 매칭에 사용할 커스텀 클레임을 설정합니다.

정확한 탐색 경로는 Okta 조직 구성 및 관리 콘솔 버전에 따라 다릅니다. 아래 번호가 매겨진 단계는 일반적인 경로 중 하나를 안내합니다.

1. 서비스 앱 통합을 생성합니다. Okta Admin Console에서 API Services 유형(OIDC, machine-to-machine)의 새 앱 통합을 생성합니다. 생성된 Client ID를 기록해 두세요.
2. 클라이언트 인증을 구성합니다. 키 없는 설정을 위해서는 Public key / Private key(private_key_jwt)를 선택하고 워크로드의 공개 JWK를 등록합니다. 또는 환경에서 클라이언트 시크릿을 안전하게 저장할 수 있는 경우 클라이언트 시크릿을 사용할 수 있습니다. 다음 예제에서는 애플리케이션의 DPoP 요구 사항을 비활성화해야 할 수 있습니다. 프로덕션 설정이 조직의 보안 요구 사항을 준수하는지 확인하세요.
3. 오디언스를 설정합니다. 커스텀 인증 서버에서 오디언스를 https://api.anthropic.com으로 설정하여 발급된 액세스 토큰이 해당 aud 클레임을 포함하도록 합니다. Anthropic은 이 고정 값에 대해 aud를 검증합니다.
4. 스코프를 부여합니다. 커스텀 인증 서버에서 서비스 앱이 요청할 수 있는 스코프가 하나 이상 존재하는지 확인합니다(예: anthropic.access). Okta는 부여된 스코프를 포함하지 않는 client_credentials 요청을 거부합니다.
5. 액세스 정책을 생성합니다. 커스텀 인증 서버에서 4단계에서 부여한 스코프를 서비스 앱이 요청할 수 있도록 허용하는 규칙이 하나 이상 포함된 액세스 정책을 생성합니다.
6. (선택 사항) 커스텀 클레임을 추가합니다. 클라이언트 ID 이외의 항목으로 매칭하려면 인증 서버의 Claims 탭에서 액세스 토큰에 클레임을 추가합니다.

client_credentials를 사용하는 서비스 앱의 경우, Okta는 발급된 액세스 토큰의 sub 클레임을 애플리케이션의 Client ID로 설정하고, iss를 인증 서버의 발급자 URL로 설정합니다.

Anthropic 구성

설정 안내를 따라 Claude Console에서 페더레이션 발급자를 등록하고, Anthropic 서비스 계정을 생성하고, 페더레이션 규칙을 생성합니다. 다음 Okta 관련 값을 사용하세요.

페더레이션 발급자: Okta 커스텀 인증 서버 URL과 디스커버리 모드를 사용합니다. Anthropic은 Okta의 .well-known/openid-configuration 디스커버리 문서를 읽고 해당 문서에 명시된 jwks_uri에서 JWKS를 가져옵니다.

{
  "name": "okta-prod",
  "issuer_url": "https://acme.okta.com/oauth2/aus1a2b3c4d5e6f7g8h9",
  "jwks_source": "discovery"
}

페더레이션 규칙: 서비스 앱의 Client ID인 Okta sub 클레임으로 매칭합니다. Okta에서 커스텀 클레임을 정의한 경우, claims 맵 또는 CEL condition을 사용하여 해당 클레임으로 매칭할 수 있습니다.

{
  "name": "okta-pipeline",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "0oa1b2c3d4e5f6g7h8i9",
    "audience": "https://api.anthropic.com"
  },
  "target": { "type": "service_account", "service_account_id": "svac_..." },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

토큰 획득 및 Claude API 호출

워크로드의 런타임 내부에서 토큰을 사용할 수 있게 하는(프로젝션된 파일 또는 로컬 메타데이터 엔드포인트를 통해) 플랫폼 네이티브 공급자(AWS, Google Cloud, Kubernetes)와 달리, Okta는 그렇지 않습니다. 워크로드는 Okta의 토큰 엔드포인트를 호출하여 JWT를 얻은 다음, 해당 JWT를 ID 토큰으로 Anthropic SDK에 전달해야 합니다.

import os
import httpx
import anthropic
from anthropic import WorkloadIdentityCredentials


def fetch_okta_token() -> str:
    response = httpx.post(
        f"{os.environ['OKTA_ISSUER']}/v1/token",
        data={
            "grant_type": "client_credentials",
            "scope": "anthropic.access",
            "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
            # Okta 앱의 개인 키로 서명된 RFC 7523 client_assertion JWT를 빌드합니다
            "client_assertion": build_signed_client_assertion(),
        },
    )
    response.raise_for_status()
    return response.json()["access_token"]


client = anthropic.Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=fetch_okta_token,
        federation_rule_id=os.environ["ANTHROPIC_FEDERATION_RULE_ID"],
        organization_id=os.environ["ANTHROPIC_ORGANIZATION_ID"],
        service_account_id=os.environ["ANTHROPIC_SERVICE_ACCOUNT_ID"],
        workspace_id=os.environ.get("ANTHROPIC_WORKSPACE_ID"),
    ),
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text)

각 SDK 탭은 호출 가능한 패턴을 보여줍니다. Anthropic SDK는 Anthropic 액세스 토큰이 만료에 가까워질 때마다 ID 토큰 공급자를 다시 호출하므로, Okta 페처는 토큰을 무기한 캐싱하지 말고 호출될 때마다 새 토큰을 반환해야 합니다. ant CLI는 각 교환 시 ANTHROPIC_IDENTITY_TOKEN_FILE을 다시 읽으므로, 장시간 실행되는 셸의 경우 타이머를 사용하여 해당 파일을 새로 고치세요.

설정 확인

교환이 성공하면 sk-ant-oat01-로 시작하는 access_token과 초 단위의 expires_in 값이 반환됩니다. 400 invalid_grant 오류가 발생하면 실패한 교환 문제 해결을 참조하세요. Okta 측에서 가장 흔한 원인은 issuer_url 불일치입니다(/oauth2/<auth-server-id> 경로를 포함해야 하며, Okta 조직 인증 서버는 사용할 수 없습니다).

규칙 범위 지정

규칙의 match 블록을 사용 사례에 맞는 가장 좁은 범위로 제한하세요.

• 정확한 Client ID 고정: subject_prefix를 후행 * 없이 서비스 앱의 전체 Client ID로 설정합니다.
• 오디언스 고정: 인증 서버에 구성한 audience 값과 매칭하여 다른 오디언스용으로 발급된 토큰이 거부되도록 합니다.
• 커스텀 클레임으로 매칭: 더 세밀한 범위 지정을 위해 인증 서버의 Claims 탭에서 클레임을 추가하고 규칙의 claims 맵 또는 CEL condition으로 매칭합니다.
• 서비스 앱당 하나의 규칙 사용: 여러 앱에서 하나의 규칙을 공유하지 말고 각 서비스 앱마다 별도의 페더레이션 규칙을 생성합니다.

다음 단계

• 전체 자격 증명 확인 순서 및 프로필 구성에 대해서는 WIF 참조를 검토하세요.
• CEL 표현식으로 커스텀 Okta 클레임을 매칭하려면 WIF 참조를 참조하세요.