Menggunakan WIF dengan AWS

Workload AWS dapat melakukan autentikasi ke Claude API tanpa kunci API statis dengan menukarkan token identitas OIDC yang ditandatangani AWS. Jalur yang direkomendasikan adalah memanggil API AWS STS GetWebIdentityToken, yang berfungsi di mana pun workload memiliki kredensial AWS: Lambda, EC2, ECS, dan EKS. Workload EKS dapat menggunakan alternatif jalur projected token Kubernetes, yang memiliki lebih sedikit langkah konfigurasi tetapi hanya berfungsi di dalam pod.

Panduan ini menunjukkan kedua jalur tersebut. Untuk konsep yang mendasarinya (service account, federation issuer, dan federation rule), lihat Workload Identity Federation.



Prasyarat

• Pemahaman tentang konsep WIF: service account, federation issuer, dan federation rule.
• Workload AWS (pod EKS, task ECS, fungsi Lambda, atau instance EC2) dengan IAM role yang terpasang.
• CLI aws atau AWS SDK yang tersedia di workload.
• Izin untuk membuat service account, federation issuer, dan federation rule di Claude Console untuk organisasi Anthropic Anda.



Menggunakan token identitas web STS (direkomendasikan)

API AWS STS GetWebIdentityToken mengembalikan token OIDC yang ditandatangani oleh AWS yang menyatakan identitas IAM pemanggil. Karena menggunakan kredensial AWS ambien milik workload, integrasi yang sama mencakup Lambda, EC2, ECS, dan EKS.



Mengonfigurasi AWS



Mengonfigurasi Anthropic

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

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

Federation issuer: Daftarkan URL issuer STS per-akun yang Anda salin pada langkah sebelumnya. URL tersebut mengekspos endpoint JWKS publik, jadi gunakan mode discovery.

{
  "name": "aws-sts",
  "issuer_url": "https://<uuid>.tokens.sts.global.api.aws",
  "jwks": { "type": "discovery" }
}

Federation rule: Cocokkan audience yang Anda berikan ke GetWebIdentityToken dan ARN IAM role pemanggil di klaim sub. Nilai sub adalah ARN IAM role dari workload yang memanggil API, dalam bentuk arn:aws:iam::<account>:role/<role-name>. Token juga membawa klaim https://sts.amazonaws.com/ dengan aws_account, org_id, principal_id, dan request_tags apa pun yang Anda berikan; Anda dapat mencocokkannya dengan map claims pada rule atau condition CEL untuk kontrol yang lebih detail.

{
  "name": "prod-inference",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "arn:aws:iam::123456789012:role/inference-worker",
    "audience": "https://api.anthropic.com"
  },
  "target": { "type": "service_account", "service_account_id": "svac_..." },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

Buat sespesifik yang diizinkan oleh workload. Cocokkan ARN role yang tepat, dan hanya perluas subject_prefix (misalnya, menjadi arn:aws:iam::123456789012:role/*) jika beberapa IAM role harus dipetakan ke service account Anthropic yang sama.



Memperoleh dan menggunakan token

Panggil GetWebIdentityToken dengan https://api.anthropic.com sebagai audience, lalu berikan hasilnya ke kredensial federasi SDK. Token provider adalah sebuah callable, sehingga SDK memanggil ulang STS pada setiap refresh.

import os

import anthropic
import boto3
from anthropic import WorkloadIdentityCredentials


def get_sts_web_identity_token() -> str:
    sts = boto3.client("sts", region_name="us-east-1")
    resp = sts.get_web_identity_token(
        Audience=["https://api.anthropic.com"],
        SigningAlgorithm="RS256",
        DurationSeconds=900,
    )
    return resp["WebIdentityToken"]


client = anthropic.Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=get_sts_web_identity_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 from AWS"}],
)
print(message.content[0].text)



Memverifikasi pengaturan

Dari dalam workload, tukarkan token yang diterbitkan STS secara langsung dan periksa responsnya:

JWT=$(aws sts get-web-identity-token \
  --region us-east-1 \
  --audience "https://api.anthropic.com" \
  --signing-algorithm RS256 \
  --duration-seconds 900 \
  --query WebIdentityToken --output text)

curl -sS https://api.anthropic.com/v1/oauth/token \
  -H "content-type: application/json" \
  -d "{
    \"grant_type\": \"urn:ietf:params:oauth:grant-type:jwt-bearer\",
    \"assertion\": \"$JWT\",
    \"federation_rule_id\": \"fdrl_...\",
    \"organization_id\": \"00000000-0000-0000-0000-000000000000\",
    \"service_account_id\": \"svac_...\",
    \"workspace_id\": \"wrkspc_...\"
  }" | jq

Pertukaran yang berhasil mengembalikan access_token yang diawali dengan sk-ant-oat01- dan nilai expires_in dalam detik. Jika terjadi 400 invalid_grant, lihat Memecahkan masalah pertukaran yang gagal; penyebab paling umum di sisi AWS adalah ketidakcocokan iss (URL issuer STS per-akun harus cocok persis dengan issuer_url yang terdaftar).



Menggunakan projected service-account token EKS

Jika workload Anda berjalan di pod EKS, Anda dapat melewati panggilan STS dan membaca projected service-account token Kubernetes langsung dari disk. Kubernetes secara native memproyeksikan token yang kompatibel dengan OIDC ke dalam pod, dan SDK dapat membacanya dari path file, sehingga tidak diperlukan callable token-provider. Jalur ini memiliki dua langkah konfigurasi AWS lebih sedikit dibandingkan jalur STS tetapi hanya berfungsi di dalam pod; mekanisme yang mendasarinya sama dengan integrasi Kubernetes generik.

Jalur ini juga memerlukan cluster EKS dengan IAM OIDC provider yang diaktifkan dan akses kubectl ke cluster.



Mengonfigurasi cluster EKS Anda



Mengonfigurasi Anthropic

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

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

Federation issuer: Issuer EKS mengekspos endpoint JWKS publik, jadi gunakan mode discovery. URL issuer harus cocok persis dengan klaim iss token. Daftarkan satu issuer per cluster.

{
  "name": "prod-eks-uswest2",
  "issuer_url": "https://oidc.eks.us-west-2.amazonaws.com/id/6FA42E7BFDE8549CB...",
  "jwks": { "type": "discovery" }
}

Federation rule: Cocokkan klaim sub Kubernetes dan audience Anthropic https://api.anthropic.com. (Proyeksikan service-account token khusus dengan audience tersebut; jangan gunakan kembali token default IRSA sts.amazonaws.com.)

{
  "name": "prod-inference",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "system:serviceaccount:inference:inference-worker",
    "audience": "https://api.anthropic.com"
  },
  "target": { "type": "service_account", "service_account_id": "svac_..." },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

Buat sespesifik yang diizinkan oleh workload. Longgarkan subject_prefix menjadi system:serviceaccount:inference:* (tanda * di akhir menjadikannya pencocokan prefix) hanya jika setiap service account di namespace tersebut harus dipetakan ke service account Anthropic yang sama.



Memperoleh dan menggunakan token

Di dalam pod, projected token berada di /var/run/secrets/anthropic.com/token (diekspos sebagai ANTHROPIC_IDENTITY_TOKEN_FILE di spesifikasi Pod). Berikan file tersebut ke kredensial federasi SDK dan SDK akan menangani pertukaran dan refresh.

import os

import anthropic
from anthropic import IdentityTokenFile, WorkloadIdentityCredentials

client = anthropic.Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=IdentityTokenFile(
            os.environ["ANTHROPIC_IDENTITY_TOKEN_FILE"]
        ),
        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 from EKS"}],
)
print(message.content[0].text)



Memverifikasi pengaturan

Dari dalam pod, tukarkan projected token secara langsung dan periksa responsnya:

JWT=$(cat "$ANTHROPIC_IDENTITY_TOKEN_FILE")

curl -sS https://api.anthropic.com/v1/oauth/token \
  -H "content-type: application/json" \
  -d "{
    \"grant_type\": \"urn:ietf:params:oauth:grant-type:jwt-bearer\",
    \"assertion\": \"$JWT\",
    \"federation_rule_id\": \"$ANTHROPIC_FEDERATION_RULE_ID\",
    \"organization_id\": \"$ANTHROPIC_ORGANIZATION_ID\",
    \"service_account_id\": \"$ANTHROPIC_SERVICE_ACCOUNT_ID\",
    \"workspace_id\": \"$ANTHROPIC_WORKSPACE_ID\"
  }" | jq

Pertukaran yang berhasil mengembalikan access_token yang diawali dengan sk-ant-oat01- dan nilai expires_in dalam detik. Jika terjadi 400 invalid_grant, lihat Memecahkan masalah pertukaran yang gagal; penyebab paling umum di sisi EKS adalah aud pada projected token tidak cocok dengan rule (proyeksikan token dengan audience: https://api.anthropic.com, bukan default IRSA sts.amazonaws.com).



Membatasi cakupan rule Anda

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

• Tetapkan ARN role lengkap: Gunakan subject_prefix: "arn:aws:iam::<account>:role/<role-name>" tanpa * di akhir sehingga role lain di akun tidak cocok.
• Tetapkan ID akun: Cocokkan field aws_account dari klaim https://sts.amazonaws.com/ pada token dengan map claims atau condition CEL sebagai pemeriksaan pertahanan berlapis terhadap prefix yang salah konfigurasi.
• Tetapkan namespace dan service account di EKS: Gunakan nilai system:serviceaccount:<namespace>:<name> yang tepat tanpa * setelah prefix system:serviceaccount:.
• Gunakan rule terpisah per lingkungan: Buat rule yang berbeda untuk workload production, staging, dan development daripada memperluas satu prefix untuk mencakup semuanya.



Langkah selanjutnya

• Tinjau referensi WIF untuk referensi lengkap tentang prioritas kredensial, konfigurasi profil, dan pencocokan rule.
• Untuk cluster Kubernetes yang dikelola sendiri dan bukan di EKS, lihat Menggunakan WIF dengan Kubernetes.