AdminIdentitätsanbieter

WIF mit GitHub Actions verwenden

Authentifiziere GitHub-Actions-Workflows gegenüber der Claude API mit kurzlebigen Identitätstoken anstelle langlebiger API-Keys.

Jeder Lauf eines GitHub-Actions-Workflows kann ein signiertes Identitätstoken von GitHubs gehostetem Issuer unter https://token.actions.githubusercontent.com anfordern. Mit „Workload Identity Federation“ (Workload-Identitätsföderation), oder WIF, tauscht dein Workflow dieses Token gegen ein kurzlebiges Anthropic-Zugriffstoken ein, sodass deine CI-Jobs die Claude API aufrufen können, ohne dass ein ANTHROPIC_API_KEY-Secret in deinem Repository gespeichert ist.

Der sub-Claim des Tokens kodiert das Repository und den Auslösekontext. Bei einem Push auf einen Branch hat er die Form repo:<owner>/<repo>:ref:refs/heads/<branch>. Pull-Request-Läufe verwenden repo:<owner>/<repo>:pull_request, und durch Environments abgesicherte Deployments verwenden repo:<owner>/<repo>:environment:<name>. Deine Föderationsregel gleicht diesen Claim (und andere, wie repository_owner und ref) ab, um zu entscheiden, welche Workflow-Läufe sich authentifizieren dürfen.

Voraussetzungen

Vertrautheit mit den WIF-Konzepten: Service-Accounts, Föderations-Issuer und Föderationsregeln.
Ein GitHub-Repository, in dem du Workflow-Dateien bearbeiten und die Berechtigung id-token: write erteilen kannst.
Die Berechtigung, in der Claude Console Service-Accounts, Föderations-Issuer und Föderationsregeln für deine Anthropic-Organisation zu erstellen.
Deine Anthropic-Organisations-ID. Du findest sie in der Claude Console unter Settings → Organization.

Deinen Workflow konfigurieren

GitHub stellt ein Identitätstoken nur für Jobs aus, die es explizit anfordern. Füge die Berechtigung id-token: write auf Workflow- oder Job-Ebene hinzu:

permissions:
  id-token: write
  contents: read

Innerhalb des Jobs stellt der Runner zwei Umgebungsvariablen bereit: ACTIONS_ID_TOKEN_REQUEST_URL und ACTIONS_ID_TOKEN_REQUEST_TOKEN. Rufe die Request-URL mit dem Request-Token als Bearer-Credential und deiner gewählten Audience als Query-Parameter auf und schreibe dann das zurückgegebene „JSON Web Token“, oder JWT, in eine Datei:

- 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

Wenn du JavaScript bevorzugst, stellt actions/github-script dieselbe Funktionalität über core.getIDToken(audience) bereit:

- 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);

Das dekodierte Token enthält Claims, die den Workflow-Lauf beschreiben. Deine Föderationsregel gleicht gegen diese ab:

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

Siehe GitHubs Referenz zum OIDC-Subject-Claim für die vollständige Liste der sub-Formate.

Anthropic konfigurieren

Öffne in der Claude Console Settings → Workload identity, klicke auf Connect workload und wähle die Kachel GitHub Actions aus. Der Assistent führt dich durch die Registrierung des Issuers, das Erstellen eines Service-Accounts und das Erstellen einer Föderationsregel.

Der Assistent erstellt diese Ressourcen für dich. Verwende die folgenden Werte, unabhängig davon, ob du sie im Assistenten eingibst oder an die Admin API sendest:

Föderations-Issuer: GitHub veröffentlicht sein OIDC-Discovery-Dokument und JWKS öffentlich, verwende daher den Discovery-Modus. Anthropic aktualisiert die Schlüssel automatisch, wenn GitHub sie rotiert.

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

Föderationsregel: Gleiche nur die Workflow-Läufe ab, denen du vertrauen möchtest. Siehe Einschränken, welche Workflows sich authentifizieren können, um zu erfahren, wie du diese Claims sicher eingrenzt.

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

Sei so spezifisch, wie es der Workload erlaubt. Lockere subject_prefix nur dann auf repo:your-org/your-repo:* (kombiniert mit einer claims.ref-Einschränkung), wenn die Regel mehrere Ereignistypen aus demselben Repository abgleichen muss, da das abschließende Segment von sub zwischen ref:...-, environment:...- und pull_request-Ereignissen variiert.

Ein Token beziehen und verwenden

Setze die Föderations-Umgebungsvariablen im Job und rufe das SDK wie gewohnt auf. Anthropic() liest ANTHROPIC_IDENTITY_TOKEN_FILE, tauscht das JWT bei der ersten Anfrage ein und erneuert das Zugriffstoken automatisch, bevor es abläuft.

import anthropic

# Liest ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID,
# ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID und ANTHROPIC_IDENTITY_TOKEN_FILE
# aus der Job-Umgebung.
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"))

Jedes von GitHub ausgestellte Identitätstoken läuft etwa fünf Minuten nach der Ausstellung ab. Der Token-Request-Endpunkt (ACTIONS_ID_TOKEN_REQUEST_URL) bleibt für den gesamten Job gültig, sodass du jederzeit ein frisches Token abrufen kannst. Das SDK tauscht das Token bei der ersten Verwendung ein und cacht das resultierende Anthropic-Zugriffstoken. Bei Jobs, die länger laufen als die Lebensdauer des Anthropic-Tokens, liest das SDK ANTHROPIC_IDENTITY_TOKEN_FILE bei jeder Erneuerung erneut ein; führe daher den Abrufschritt regelmäßig erneut aus (oder verpacke ihn in eine Hintergrundschleife), um die Datei aktuell zu halten. Alternativ kannst du dem SDK einen Token-Provider-Callback übergeben, der ACTIONS_ID_TOKEN_REQUEST_URL direkt aufruft, anstatt den Dateipfad zu verwenden.

Die Einrichtung überprüfen

Ein erfolgreicher Austausch gibt ein access_token zurück, das mit sk-ant-oat01- beginnt, sowie einen expires_in-Wert in Sekunden. Ein abgelehnter Austausch gibt einen undurchsichtigen 401 authentication_error mit der festen Meldung Authentication failed zurück, unabhängig davon, welche Prüfung fehlgeschlagen ist; in den meisten Fällen wird der Ablehnungsgrund im Eintrag des Versuchs auf der Seite mit dem Authentifizierungsverlauf festgehalten, und Fehlerbehebung bei einem fehlgeschlagenen Austausch geht die Prüfungen der Reihe nach durch. Die häufigste Ursache auf Seiten von GitHub Actions ist, dass das Format des sub-Claims nicht übereinstimmt (sein abschließendes Segment variiert zwischen ref:...-, environment:...- und pull_request-Ereignissen); der Verlaufseintrag zeigt den Grund match_subject_prefix.

Einschränken, welche Workflows sich authentifizieren können

Beschränke den match-Block der Regel auf den engsten Geltungsbereich, der zu deinem Anwendungsfall passt:

Auf ein einzelnes Repository festlegen: Verwende subject_prefix: "repo:your-org/your-repo:*", damit andere Repositories in der Organisation nicht passen.
Auf einen geschützten Branch festlegen: Füge "ref": "refs/heads/main" (oder deinen Release-Branch) unter claims hinzu, damit Pull-Request-Läufe und Feature-Branches nicht passen.
Den Owner explizit festlegen: Füge "repository_owner": "your-org" unter claims als Defense-in-Depth-Prüfung gegen Grenzfälle beim Parsen von sub hinzu.
Auf ein Deployment-Environment festlegen: Gleiche für Deploy-Jobs subject_prefix: "repo:your-org/your-repo:environment:production" ab und sichere dieses Environment in GitHub mit erforderlichen Reviewern ab.

Nächste Schritte

Workload Identity Federation: vollständige Einrichtungsanleitung, Umgebungsvariablen und Rangfolge der Anmeldedaten.
Authentifizierung: wie sich Föderation im Vergleich zu API-Keys verhält.

Voraussetzungen

Deinen Workflow konfigurieren

Anthropic konfigurieren

Ein Token beziehen und verwenden

Die Einrichtung überprüfen

Einschränken, welche Workflows sich authentifizieren können

Nächste Schritte