Menggunakan WIF dengan Okta

Okta dapat bertindak sebagai penyedia identitas workload dengan menerbitkan token akses OIDC ke service application (aplikasi layanan) melalui grant OAuth 2.0 client_credentials. Workload Anda melakukan autentikasi ke Okta (biasanya dengan private_key_jwt, sehingga tidak ada rahasia bersama yang disimpan), menerima JSON Web Token (JWT) yang ditandatangani, dan menukarkan JWT tersebut dengan Anthropic untuk mendapatkan token akses berumur pendek.

URL issuer server otorisasi Okta berbentuk https://<your-domain>.okta.com/oauth2/<auth-server-id>. Jika Anda menggunakan server default bawaan, path-nya adalah /oauth2/default.

Ada banyak cara untuk mengonfigurasi dan melakukan autentikasi ke Okta yang berada di luar cakupan dokumentasi ini. Pastikan bahwa konfigurasi dan mekanisme autentikasi Anda mengikuti panduan dan praktik keamanan perusahaan Anda.

Prasyarat

• Pemahaman tentang konsep WIF: service account, federation issuer, dan federation rule.
• Organisasi Okta dengan API Access Management yang diaktifkan (diperlukan untuk server otorisasi kustom).
• Izin untuk membuat service account, federation issuer, dan federation rule di Claude Console untuk organisasi Anthropic Anda.
• Workload yang dapat meminta token dari endpoint /v1/token Okta dan menjangkau api.anthropic.com.

Mengonfigurasi Okta

Secara garis besar, Anda perlu:

1. Membuat aplikasi layanan Okta.
2. Mengonfigurasi server otorisasi default Anda (atau membuat server otorisasi kustom baru) dengan audience, scope, access policy, dan custom claim apa pun yang ingin Anda cocokkan.

Navigasi yang tepat bergantung pada konfigurasi org Okta Anda dan versi konsol admin. Langkah-langkah bernomor berikut menjelaskan salah satu jalur yang umum:

1. Buat integrasi aplikasi layanan. Di Okta Admin Console, buat integrasi aplikasi baru dengan tipe API Services (OIDC, machine-to-machine). Catat Client ID yang dihasilkan.
2. Konfigurasikan autentikasi klien. Untuk penyiapan tanpa kunci, pilih Public key / Private key (private_key_jwt) dan daftarkan JWK publik workload Anda. Sebagai alternatif, gunakan client secret jika lingkungan Anda dapat menyimpannya dengan aman. Untuk contoh berikut, Anda mungkin perlu menonaktifkan persyaratan DPoP pada aplikasi; pastikan bahwa penyiapan produksi Anda mematuhi persyaratan keamanan organisasi Anda.
3. Tetapkan audience. Pada server otorisasi kustom Anda, tetapkan audience ke https://api.anthropic.com sehingga token akses yang diterbitkan membawa claim aud tersebut. Anthropic memvalidasi aud terhadap nilai tetap ini.
4. Berikan scope. Pada server otorisasi kustom Anda, pastikan setidaknya ada satu scope yang diizinkan untuk diminta oleh aplikasi layanan (misalnya, anthropic.access). Okta menolak permintaan client_credentials yang tidak menyertakan scope yang telah diberikan.
5. Buat access policy. Pada server otorisasi kustom Anda, buat access policy dengan setidaknya satu aturan yang mengizinkan aplikasi layanan Anda meminta scope yang Anda berikan pada langkah 4.
6. (Opsional) Tambahkan custom claim. Jika Anda ingin mencocokkan sesuatu selain client ID, tambahkan claim ke token akses di tab Claims server otorisasi Anda.

Untuk aplikasi layanan yang menggunakan client_credentials, Okta menetapkan claim sub dari token akses yang diterbitkan ke Client ID aplikasi, dan iss ke URL issuer server otorisasi.

Mengonfigurasi Anthropic

Di Claude Console, buka Settings → Workload identity, klik Connect workload, dan pilih Custom OIDC. Wizard akan memandu Anda mendaftarkan issuer, membuat service account, dan membuat federation rule.

Wizard membuat sumber daya ini untuk Anda. Gunakan nilai-nilai berikut, baik Anda memasukkannya di wizard maupun mengirimkannya ke Admin API:

Federation issuer: Gunakan URL server otorisasi kustom Okta Anda dan mode discovery. Anthropic membaca dokumen discovery .well-known/openid-configuration Okta dan mengambil JWKS dari jwks_uri yang diiklankannya.

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

Federation rule: Cocokkan pada claim sub Okta, yaitu Client ID aplikasi layanan. Jika Anda mendefinisikan custom claim di Okta, Anda dapat mencocokkannya sebagai gantinya dengan map claims atau condition CEL.

{
  "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
}

Memperoleh token dan memanggil Claude API

Tidak seperti penyedia platform-native (AWS, Google Cloud, Kubernetes), yang menyediakan token di dalam runtime workload (melalui file yang diproyeksikan atau endpoint metadata lokal), Okta tidak melakukannya. Workload Anda harus memanggil endpoint token Okta untuk memperoleh JWT, lalu meneruskan JWT tersebut ke Anthropic SDK sebagai identity token.

import os
import httpx2
import anthropic
from anthropic import WorkloadIdentityCredentials


def fetch_okta_token() -> str:
    response = httpx2.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",
            # Buat JWT client_assertion RFC 7523 yang ditandatangani dengan kunci privat aplikasi Okta Anda
            "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-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "text"))

Setiap tab SDK menunjukkan pola callable: Anthropic SDK memanggil kembali penyedia identity token Anda setiap kali token akses Anthropic mendekati masa kedaluwarsa, sehingga fetcher Okta Anda harus mengembalikan token baru pada setiap pemanggilan alih-alih menyimpannya dalam cache tanpa batas waktu. CLI ant membaca ulang ANTHROPIC_IDENTITY_TOKEN_FILE pada setiap pertukaran, jadi perbarui file tersebut secara berkala dengan timer untuk shell yang berjalan lama.

Memverifikasi penyiapan

Pertukaran yang berhasil mengembalikan access_token yang diawali dengan sk-ant-oat01- dan nilai expires_in dalam detik. Jika pertukaran gagal dengan respons 401 authentication_error yang tidak transparan (pesan Authentication failed), periksa halaman riwayat autentikasi untuk mengetahui alasan penolakan dan lihat Memecahkan masalah pertukaran yang gagal; penyebab paling umum di sisi Okta adalah ketidakcocokan issuer_url (harus menyertakan path /oauth2/<auth-server-id>; server otorisasi org Okta tidak dapat digunakan).

Membatasi cakupan aturan Anda

Kunci blok match aturan ke cakupan tersempit yang sesuai dengan kasus penggunaan Anda:

• Sematkan Client ID yang tepat: Tetapkan subject_prefix ke Client ID lengkap aplikasi layanan tanpa * di akhir.
• Sematkan audience: Cocokkan nilai audience yang Anda konfigurasikan pada server otorisasi sehingga token yang dicetak untuk audience berbeda ditolak.
• Cocokkan pada custom claim: Untuk pembatasan cakupan yang lebih terperinci, tambahkan claim di tab Claims server otorisasi dan cocokkan dengan map claims aturan atau condition CEL.
• Gunakan satu aturan per aplikasi layanan: Buat federation rule terpisah untuk setiap aplikasi layanan alih-alih berbagi satu aturan di antara beberapa aplikasi.

Langkah selanjutnya

• Tinjau referensi WIF untuk urutan resolusi kredensial lengkap dan konfigurasi profil.
• Lihat referensi WIF untuk mencocokkan custom claim Okta dengan ekspresi CEL.