Claude Platform Docs
AdminPenyedia identitas

Menggunakan WIF dengan AWS

Autentikasi beban kerja AWS di Lambda, EC2, ECS, atau EKS ke Claude API dengan Workload Identity Federation dan token identitas yang diterbitkan STS.

Beban kerja AWS dapat melakukan autentikasi ke Claude API tanpa kunci API statis dengan menukarkan token identitas OIDC yang ditandatangani AWS. Jalur yang direkomendasikan memanggil API AWS STS GetWebIdentityToken, yang berfungsi di mana pun beban kerja memiliki kredensial AWS: Lambda, EC2, ECS, dan EKS. Beban kerja EKS sebagai alternatif dapat 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.
  • Beban kerja AWS (pod EKS, task ECS, fungsi Lambda, atau instance EC2) dengan IAM role yang terlampir.
  • CLI aws atau AWS SDK yang tersedia di beban kerja.
  • Izin untuk membuat service account, federation issuer, dan federation rule di Claude Console untuk organisasi Anthropic Anda.

API AWS STS GetWebIdentityToken mengembalikan token OIDC yang ditandatangani oleh AWS yang menegaskan identitas IAM pemanggil. Karena menggunakan kredensial AWS ambient milik beban kerja, integrasi yang sama mencakup Lambda, EC2, ECS, dan EKS.

Mengonfigurasi AWS

  1. Aktifkan outbound web identity federation untuk akun

    Ini adalah flag tingkat akun, nonaktif secara default. Di konsol AWS, buka IAM, pilih Account settings, dan aktifkan Outbound web identity federation. Untuk mengaktifkannya secara terprogram:

    python3 -c "import boto3; boto3.client('iam').enable_outbound_web_identity_federation()"

    Jika ini tidak diaktifkan, panggilan ke GetWebIdentityToken gagal dengan OutboundWebIdentityFederationDisabledException.

  2. Berikan izin kepada IAM role beban kerja untuk memanggil API

    Lampirkan kebijakan ini ke IAM role yang digunakan oleh fungsi Lambda, instance EC2, atau task ECS Anda:

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["sts:GetWebIdentityToken"],
      "Resource": "*"
    }
  ]
}

  3. Temukan URL issuer STS akun Anda

    Setelah mengaktifkan outbound federation, halaman IAM > Account settings menampilkan kolom Get Token Issuer URL dengan nilai berbentuk https://<uuid>.tokens.sts.global.api.aws. URL ini unik untuk akun AWS Anda; salin untuk langkah berikutnya. Untuk mengambilnya secara terprogram:

    python3 -c "import boto3; print(boto3.client('iam').get_outbound_web_identity_federation_info())"

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 membuat sumber daya ini untuk Anda. Gunakan nilai-nilai berikut, baik Anda memasukkannya di wizard maupun mengirimkannya ke Admin API:

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": { "type": "discovery" }
}

Federation rule: Cocokkan audience yang Anda teruskan ke GetWebIdentityToken dan ARN IAM role pemanggil dalam klaim sub. Nilai sub adalah ARN IAM role dari beban kerja 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 teruskan; Anda dapat mencocokkannya dengan map claims pada rule atau condition CEL untuk kontrol yang lebih halus.

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

Buatlah sespesifik mungkin sesuai yang diizinkan beban kerja. 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 teruskan hasilnya ke kredensial federasi SDK. Penyedia token adalah 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-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from AWS"}],
)
print(next(block.text for block in message.content if block.type == "text"))

Memverifikasi penyiapan

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

cURL
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

Penukaran yang berhasil mengembalikan access_token yang diawali dengan sk-ant-oat01- dan nilai expires_in dalam detik. Jika penukaran gagal dengan respons 401 authentication_error yang tidak transparan (pesan Authentication failed), periksa halaman riwayat autentikasi untuk alasan penolakan dan lihat Memecahkan masalah penukaran yang gagal; penyebab paling umum di sisi AWS adalah ketidakcocokan iss (URL issuer STS per-akun harus sama persis dengan issuer_url yang terdaftar).

Menggunakan projected service-account token EKS

Jika beban kerja Anda berjalan di pod EKS, Anda dapat melewati panggilan STS dan membaca service-account token yang diproyeksikan 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 penyedia token. Jalur ini memiliki dua langkah konfigurasi AWS lebih sedikit daripada 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

  1. Temukan URL issuer OIDC klaster Anda

    Setiap klaster EKS memiliki issuer OIDC yang unik. Ambil dengan AWS CLI:

    CLI
    aws eks describe-cluster \
  --name <cluster-name> \
  --query "cluster.identity.oidc.issuer" \
  --output text

    Outputnya terlihat seperti https://oidc.eks.us-west-2.amazonaws.com/id/6FA42E7BFDE8549CB.... Anda akan mendaftarkan URL ini sebagai federation issuer di bagian berikutnya.

  2. Buat service account dan proyeksikan token dengan audience Anthropic

    Webhook pod identity EKS mendeteksi anotasi eks.amazonaws.com/role-arn dan secara otomatis memproyeksikan token dengan aud: sts.amazonaws.com, mengekspos path-nya sebagai AWS_WEB_IDENTITY_TOKEN_FILE. Token tersebut untuk asumsi role AWS. Untuk penukaran Anthropic, proyeksikan token kedua dengan audience: https://api.anthropic.com dan mount di path khusus.

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: inference-worker
  namespace: inference
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/inference-worker
    apiVersion: v1
kind: Pod
metadata:
  name: inference-worker
  namespace: inference
spec:
  serviceAccountName: inference-worker
  volumes:
    - name: anthropic-token
      projected:
        sources:
          - serviceAccountToken:
              audience: https://api.anthropic.com
              expirationSeconds: 3600
              path: token
  containers:
    - name: app
      image: your-registry/inference-worker:latest
      env:
        - name: ANTHROPIC_IDENTITY_TOKEN_FILE
          value: /var/run/secrets/anthropic.com/token
        - name: ANTHROPIC_FEDERATION_RULE_ID
          value: fdrl_...
        - name: ANTHROPIC_ORGANIZATION_ID
          value: 00000000-0000-0000-0000-000000000000
        - name: ANTHROPIC_SERVICE_ACCOUNT_ID
          value: svac_...
        - name: ANTHROPIC_WORKSPACE_ID  # required when the rule covers multiple workspaces
          value: wrkspc_...
      volumeMounts:
        - name: anthropic-token
          mountPath: /var/run/secrets/anthropic.com
          readOnly: true

  3. Perhatikan bentuk klaim token

    Token yang diproyeksikan adalah JSON Web Token (JWT) yang ditandatangani oleh issuer OIDC klaster Anda. Klaim sub-nya mengikuti konvensi Kubernetes system:serviceaccount:<namespace>:<service-account-name>:

    {
  "iss": "https://oidc.eks.us-west-2.amazonaws.com/id/6FA42E7BFDE8549CB...",
  "sub": "system:serviceaccount:inference:inference-worker",
  "aud": ["https://api.anthropic.com"],
  "kubernetes.io": {
    "namespace": "inference",
    "serviceaccount": { "name": "inference-worker", "uid": "..." }
  },
  "exp": 1775527120,
  "iat": 1775523520
}

    Proyeksi serviceAccountToken menetapkan aud ke https://api.anthropic.com. Token terpisah yang diinjeksi IRSA di AWS_WEB_IDENTITY_TOKEN_FILE membawa aud: sts.amazonaws.com dan ditujukan untuk panggilan API AWS, bukan penukaran ini.

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 membuat sumber daya ini untuk Anda. Gunakan nilai-nilai berikut, baik Anda memasukkannya di wizard maupun mengirimkannya ke Admin API:

Federation issuer: Issuer EKS mengekspos endpoint JWKS publik, jadi gunakan mode discovery. URL issuer harus sama 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": { "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 ulang 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
}

Buatlah sespesifik mungkin sesuai yang diizinkan beban kerja. Longgarkan subject_prefix menjadi system:serviceaccount:inference:* (tanda * di akhir menjadikannya pencocokan prefiks) hanya jika setiap service account di namespace tersebut harus dipetakan ke service account Anthropic yang sama.

Memperoleh dan menggunakan token

Di dalam pod, token yang diproyeksikan berada di /var/run/secrets/anthropic.com/token (diekspos sebagai ANTHROPIC_IDENTITY_TOKEN_FILE dalam spesifikasi Pod). Teruskan file tersebut ke kredensial federasi SDK dan SDK akan menangani penukaran 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-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from EKS"}],
)
print(next(block.text for block in message.content if block.type == "text"))

Memverifikasi penyiapan

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

cURL
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

Penukaran yang berhasil mengembalikan access_token yang diawali dengan sk-ant-oat01- dan nilai expires_in dalam detik. Jika penukaran gagal dengan respons 401 authentication_error yang tidak transparan (pesan Authentication failed), periksa halaman riwayat autentikasi untuk alasan penolakan dan lihat Memecahkan masalah penukaran yang gagal; penyebab paling umum di sisi EKS adalah aud token yang diproyeksikan 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:

  • Sematkan ARN role lengkap: Gunakan subject_prefix: "arn:aws:iam::<account>:role/<role-name>" tanpa * di akhir sehingga role lain di akun tidak cocok.
  • Sematkan ID akun: Cocokkan kolom aws_account dari klaim https://sts.amazonaws.com/ token dengan map claims atau condition CEL sebagai pemeriksaan defense-in-depth terhadap prefiks yang salah dikonfigurasi.
  • Sematkan namespace dan service account di EKS: Gunakan nilai system:serviceaccount:<namespace>:<name> yang tepat tanpa * setelah prefiks system:serviceaccount:.
  • Gunakan rule terpisah per lingkungan: Buat rule yang berbeda untuk beban kerja produksi, staging, dan pengembangan daripada memperluas satu prefiks untuk mencakup semuanya.

Langkah selanjutnya

Was this page helpful?