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 secara alternatif menggunakan 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

Ikuti panduan penyiapan untuk mendaftarkan federation issuer, membuat service account Anthropic, dan membuat federation rule di Claude Console. Gunakan nilai-nilai khusus STS berikut.

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

{
  "name": "aws-sts",
  "issuer_url": "https://<uuid>.tokens.sts.global.api.aws",
  "jwks_source": "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 mungkin sesuai yang diizinkan 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 penyiapan

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. Pada 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 klaster EKS dengan IAM OIDC provider yang diaktifkan dan akses kubectl ke klaster.

Mengonfigurasi klaster EKS Anda

Mengonfigurasi Anthropic

Ikuti panduan penyiapan untuk mendaftarkan federation issuer, membuat service account Anthropic, dan membuat federation rule di Claude Console. Gunakan nilai-nilai khusus EKS berikut.

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 klaster.

{
  "name": "prod-eks-uswest2",
  "issuer_url": "https://oidc.eks.us-west-2.amazonaws.com/id/6FA42E7BFDE8549CB...",
  "jwks_source": "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 mungkin sesuai yang diizinkan 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 dalam 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 penyiapan

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. Pada 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/ token melalui map claims atau condition CEL sebagai pemeriksaan defense-in-depth 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 klaster Kubernetes yang dikelola sendiri dan bukan di EKS, lihat Menggunakan WIF dengan Kubernetes.