WIF mit Okta verwenden

Okta kann als Workload-Identity-Provider fungieren, indem es OIDC-Access-Tokens an eine Service Application über den OAuth 2.0 client_credentials-Grant ausstellt. Dein Workload authentifiziert sich bei Okta (typischerweise mit private_key_jwt, sodass kein gemeinsames Secret gespeichert wird), erhält ein signiertes JSON Web Token (JWT) und tauscht dieses JWT bei Anthropic gegen ein kurzlebiges Access-Token ein.

Die Issuer-URL des Okta-Authorization-Servers hat die Form https://<your-domain>.okta.com/oauth2/<auth-server-id>. Wenn du den integrierten Default-Server verwendest, lautet der Pfad /oauth2/default.

Es gibt viele Möglichkeiten, Okta zu konfigurieren und sich dort zu authentifizieren, die außerhalb des Umfangs dieser Dokumentation liegen. Stelle sicher, dass deine Konfiguration und Authentifizierungsmechanismen den Richtlinien und Sicherheitspraktiken deines Unternehmens entsprechen.



Voraussetzungen

• Vertrautheit mit WIF-Konzepten: Service Accounts, Federation Issuers und Federation Rules.
• Eine Okta-Organisation mit aktiviertem API Access Management (erforderlich für Custom Authorization Server).
• Berechtigung zum Erstellen von Service Accounts, Federation Issuers und Federation Rules in der Claude Console für deine Anthropic-Organisation.
• Ein Workload, der ein Token vom Okta-/v1/token-Endpunkt anfordern und api.anthropic.com erreichen kann.



Okta konfigurieren

Auf hoher Ebene musst du:

1. Eine Okta-Service-Application erstellen.
2. Deinen Default-Authorization-Server konfigurieren (oder einen neuen Custom Authorization Server erstellen) mit einer Audience, einem Scope, einer Access Policy und allen Custom Claims, auf die du matchen möchtest.

Die genaue Navigation hängt von deiner Okta-Org-Konfiguration und der Version der Admin-Konsole ab. Die folgenden nummerierten Schritte führen durch einen gängigen Pfad:

1. Erstelle eine Service-App-Integration. Erstelle in der Okta Admin Console eine neue App-Integration vom Typ API Services (OIDC, Machine-to-Machine). Notiere dir die generierte Client ID.
2. Konfiguriere die Client-Authentifizierung. Für ein schlüsselloses Setup wähle Public key / Private key (private_key_jwt) und registriere den öffentlichen JWK deines Workloads. Alternativ kannst du ein Client Secret verwenden, wenn deine Umgebung eines sicher speichern kann. Für das folgende Beispiel musst du möglicherweise die DPoP-Anforderung für die Application deaktivieren; stelle sicher, dass dein Produktions-Setup den Sicherheitsanforderungen deiner Organisation entspricht.
3. Lege die Audience fest. Setze auf deinem Custom Authorization Server die Audience auf https://api.anthropic.com, damit ausgestellte Access-Tokens diesen aud-Claim enthalten. Anthropic validiert aud gegen diesen festen Wert.
4. Gewähre einen Scope. Stelle auf deinem Custom Authorization Server sicher, dass mindestens ein Scope existiert, den die Service-App anfordern darf (zum Beispiel anthropic.access). Okta lehnt client_credentials-Anfragen ab, die keinen gewährten Scope enthalten.
5. Erstelle eine Access Policy. Erstelle auf deinem Custom Authorization Server eine Access Policy mit mindestens einer Regel, die deiner Service-App erlaubt, den in Schritt 4 gewährten Scope anzufordern.
6. (Optional) Füge Custom Claims hinzu. Wenn du auf etwas anderes als die Client ID matchen möchtest, füge im Claims-Tab deines Authorization Servers einen Claim zum Access-Token hinzu.

Für eine Service-App, die client_credentials verwendet, setzt Okta den sub-Claim des ausgestellten Access-Tokens auf die Client ID der Application und iss auf die Issuer-URL des Authorization Servers.



Anthropic konfigurieren

Öffne in der Claude Console Settings → Workload identity, klicke auf Connect workload und wähle Custom OIDC. Der Assistent führt dich durch die Registrierung des Issuers, das Erstellen eines Service Accounts und das Erstellen einer Federation Rule.

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:

Federation Issuer: Verwende die URL deines Okta Custom Authorization Servers und den Discovery-Modus. Anthropic liest das .well-known/openid-configuration-Discovery-Dokument von Okta und ruft das JWKS von der dort angegebenen jwks_uri ab.

{
  "name": "okta-prod",
  "issuer_url": "https://acme.okta.com/oauth2/aus1a2b3c4d5e6f7g8h9",
  "jwks": { "type": "discovery" }
}

Federation Rule: Matche auf den Okta-sub-Claim, der die Client ID der Service-App ist. Wenn du Custom Claims in Okta definiert hast, kannst du stattdessen mit der claims-Map oder einer CEL-condition auf diese matchen.

{
  "name": "okta-pipeline",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "0oa1b2c3d4e5f6g7h8i9",
    "audience": "https://api.anthropic.com"
  },
  "target": { "type": "service_account", "service_account_id": "svac_..." },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}



Ein Token abrufen und die Claude API aufrufen

Im Gegensatz zu plattformnativen Providern (AWS, Google Cloud, Kubernetes), die ein Token innerhalb der Laufzeitumgebung des Workloads verfügbar machen (über eine projizierte Datei oder einen lokalen Metadaten-Endpunkt), tut Okta dies nicht. Dein Workload muss den Token-Endpunkt von Okta aufrufen, um ein JWT zu erhalten, und dieses JWT dann als Identity-Token an das Anthropic-SDK übergeben.

import os
import httpx
import anthropic
from anthropic import WorkloadIdentityCredentials


def fetch_okta_token() -> str:
    response = httpx.post(
        f"{os.environ['OKTA_ISSUER']}/v1/token",
        data={
            "grant_type": "client_credentials",
            "scope": "anthropic.access",
            "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
            # Erstelle das RFC 7523 client_assertion JWT, signiert mit dem privaten Schlüssel deiner Okta-App
            "client_assertion": build_signed_client_assertion(),
        },
    )
    response.raise_for_status()
    return response.json()["access_token"]


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

Jeder SDK-Tab zeigt das Callable-Pattern: Das Anthropic-SDK ruft deinen Identity-Token-Provider erneut auf, sobald das Anthropic-Access-Token sich dem Ablauf nähert, daher sollte dein Okta-Fetcher bei jedem Aufruf ein frisches Token zurückgeben, anstatt eines unbegrenzt zu cachen. Die ant-CLI liest ANTHROPIC_IDENTITY_TOKEN_FILE bei jedem Austausch neu ein, aktualisiere diese Datei also per Timer für langlaufende Shells.



Das Setup verifizieren

Ein erfolgreicher Austausch gibt ein access_token zurück, das mit sk-ant-oat01- beginnt, sowie einen expires_in-Wert in Sekunden. Bei 400 invalid_grant siehe Fehlerbehebung bei einem fehlgeschlagenen Austausch; die häufigste Ursache auf Okta-Seite ist eine nicht übereinstimmende issuer_url (sie muss den Pfad /oauth2/<auth-server-id> enthalten; der Okta-Org-Authorization-Server ist nicht verwendbar).



Deine Rule eingrenzen

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

• Pinne die exakte Client ID: Setze subject_prefix auf die vollständige Client ID der Service-App ohne abschließendes *.
• Pinne die Audience: Matche auf den audience-Wert, den du auf dem Authorization Server konfiguriert hast, damit Tokens, die für eine andere Audience ausgestellt wurden, abgelehnt werden.
• Matche auf Custom Claims: Für eine feinere Eingrenzung füge Claims im Claims-Tab des Authorization Servers hinzu und matche sie mit der claims-Map der Rule oder einer CEL-condition.
• Verwende eine Rule pro Service-App: Erstelle für jede Service-App eine separate Federation Rule, anstatt eine Rule über mehrere Apps hinweg zu teilen.



Nächste Schritte

• Sieh dir die WIF-Referenz für die vollständige Credential-Auflösungsreihenfolge und Profilkonfiguration an.
• Siehe die WIF-Referenz, um mit CEL-Ausdrücken auf Custom Okta Claims zu matchen.