Menggunakan WIF dengan GitHub Actions

Setiap eksekusi workflow GitHub Actions dapat meminta token identitas bertanda tangan dari issuer yang di-host GitHub di https://token.actions.githubusercontent.com. Dengan Workload Identity Federation, workflow Anda menukar token tersebut dengan token akses Anthropic berumur pendek, sehingga job CI Anda dapat memanggil Claude API tanpa secret ANTHROPIC_API_KEY yang disimpan di repositori Anda.

Klaim sub pada token mengodekan repositori dan konteks pemicu. Untuk push ke sebuah branch, bentuknya adalah repo:<owner>/<repo>:ref:refs/heads/<branch>. Eksekusi pull-request menggunakan repo:<owner>/<repo>:pull_request, dan deployment yang dibatasi environment menggunakan repo:<owner>/<repo>:environment:<name>. Aturan federasi Anda mencocokkan klaim ini (dan klaim lainnya, seperti repository_owner dan ref) untuk menentukan eksekusi workflow mana yang diizinkan untuk melakukan autentikasi.

Prasyarat

• Pemahaman tentang konsep WIF: service account, federation issuer, dan federation rule (aturan federasi).
• Repositori GitHub tempat Anda dapat mengedit file workflow dan memberikan izin id-token: write.
• Izin untuk membuat service account, federation issuer, dan aturan federasi di Claude Console untuk organisasi Anthropic Anda.
• ID organisasi Anthropic Anda. Anda dapat menemukannya di Claude Console pada Settings → Organization.

Konfigurasikan workflow Anda

GitHub hanya menerbitkan token identitas untuk job yang secara eksplisit memintanya. Tambahkan izin id-token: write di tingkat workflow atau job:

permissions:
  id-token: write
  contents: read

Di dalam job, runner mengekspos dua variabel lingkungan: ACTIONS_ID_TOKEN_REQUEST_URL dan ACTIONS_ID_TOKEN_REQUEST_TOKEN. Panggil URL permintaan dengan token permintaan sebagai kredensial bearer dan audience pilihan Anda sebagai parameter query, lalu tulis "JSON Web Token" (token web JSON), atau JWT, yang dikembalikan ke sebuah file:

- name: Fetch GitHub OIDC token
  run: |
    curl -sS -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
      "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://api.anthropic.com" \
      | jq -r .value > /tmp/gha-jwt

Jika Anda lebih suka JavaScript, actions/github-script mengekspos kemampuan yang sama melalui core.getIDToken(audience):

- name: Fetch GitHub OIDC token
  uses: actions/github-script@v8
  with:
    script: |
      const fs = require('fs');
      const token = await core.getIDToken('https://api.anthropic.com');
      fs.writeFileSync('/tmp/gha-jwt', token);

Token yang telah didekode membawa klaim yang mendeskripsikan eksekusi workflow. Aturan federasi Anda mencocokkan klaim-klaim ini:

{
  "iss": "https://token.actions.githubusercontent.com",
  "sub": "repo:your-org/your-repo:ref:refs/heads/main",
  "aud": "https://api.anthropic.com",
  "repository": "your-org/your-repo",
  "repository_owner": "your-org",
  "ref": "refs/heads/main",
  "sha": "abc123...",
  "workflow": "CI",
  "actor": "octocat",
  "event_name": "push"
}

Lihat referensi klaim subject OIDC GitHub untuk daftar lengkap format sub.

Konfigurasikan Anthropic

Di Claude Console, buka Settings → Workload identity, klik Connect workload, dan pilih tile GitHub Actions. Wizard akan memandu Anda mendaftarkan issuer, membuat service account, dan membuat aturan federasi.

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

Federation issuer: GitHub memublikasikan dokumen discovery OIDC dan JWKS-nya secara publik, jadi gunakan mode discovery. Anthropic memperbarui kunci secara otomatis ketika GitHub merotasinya.

{
  "name": "github-actions",
  "issuer_url": "https://token.actions.githubusercontent.com",
  "jwks": { "type": "discovery" }
}

Federation rule: Cocokkan hanya eksekusi workflow yang memang ingin Anda percayai. Lihat Batasi workflow mana yang dapat melakukan autentikasi untuk cara membatasi cakupan klaim ini dengan aman.

{
  "name": "gha-main",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "repo:your-org/your-repo:ref:refs/heads/main",
    "audience": "https://api.anthropic.com",
    "claims": {
      "repository_owner": "your-org"
    }
  },
  "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 workload. Longgarkan subject_prefix menjadi repo:your-org/your-repo:* (dipasangkan dengan batasan claims.ref) hanya jika aturan harus mencocokkan beberapa jenis event dari repositori yang sama, karena segmen akhir sub bervariasi antara event ref:..., environment:..., dan pull_request.

Peroleh dan gunakan token

Atur variabel lingkungan federasi pada job dan panggil SDK seperti biasa. Anthropic() membaca ANTHROPIC_IDENTITY_TOKEN_FILE, menukar JWT pada permintaan pertama, dan memperbarui token akses secara otomatis sebelum kedaluwarsa.

import anthropic

# Membaca ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID,
# ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID, dan ANTHROPIC_IDENTITY_TOKEN_FILE
# dari environment job.
client = anthropic.Anthropic()

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 token identitas yang diterbitkan GitHub kedaluwarsa kira-kira lima menit setelah diterbitkan. Endpoint permintaan token (ACTIONS_ID_TOKEN_REQUEST_URL) tetap valid selama seluruh job berjalan, sehingga Anda dapat mengambil token baru kapan saja. SDK menukar token pada penggunaan pertama dan menyimpan token akses Anthropic yang dihasilkan dalam cache. Untuk job yang berjalan lebih lama daripada masa berlaku token Anthropic, SDK membaca ulang ANTHROPIC_IDENTITY_TOKEN_FILE pada setiap pembaruan, jadi jalankan ulang langkah pengambilan secara berkala (atau bungkus dalam loop latar belakang) agar file tetap terkini. Sebagai alternatif, berikan callback penyedia token ke SDK yang memanggil ACTIONS_ID_TOKEN_REQUEST_URL secara langsung alih-alih menggunakan path file.

Verifikasi penyiapan

Pertukaran yang berhasil mengembalikan access_token yang diawali dengan sk-ant-oat01- dan nilai expires_in dalam detik. Pertukaran yang ditolak mengembalikan 401 authentication_error yang tidak transparan dengan pesan tetap Authentication failed, apa pun pemeriksaan yang gagal; dalam kebanyakan kasus alasan penolakan dicatat pada entri percobaan tersebut di halaman riwayat autentikasi, dan Memecahkan masalah pertukaran yang gagal menelusuri pemeriksaan secara berurutan. Penyebab paling umum di sisi GitHub Actions adalah format klaim sub yang tidak cocok (segmen akhirnya bervariasi antara event ref:..., environment:..., dan pull_request); entri riwayat menampilkan alasan match_subject_prefix.

Batasi workflow mana yang dapat melakukan autentikasi

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

• Sematkan ke satu repositori: Gunakan subject_prefix: "repo:your-org/your-repo:*" agar repositori lain di organisasi tidak cocok.
• Sematkan ke branch yang dilindungi: Tambahkan "ref": "refs/heads/main" (atau branch rilis Anda) di bawah claims agar eksekusi pull-request dan feature branch tidak cocok.
• Sematkan owner secara eksplisit: Tambahkan "repository_owner": "your-org" di bawah claims sebagai pemeriksaan defense-in-depth terhadap kasus tepi parsing sub.
• Sematkan ke environment deployment: Untuk job deploy, cocokkan subject_prefix: "repo:your-org/your-repo:environment:production" dan batasi environment tersebut dengan reviewer wajib di GitHub.

Langkah selanjutnya

• Workload Identity Federation: panduan penyiapan lengkap, variabel lingkungan, dan prioritas kredensial.
• Autentikasi: perbandingan federasi dengan kunci API.