WIF mit Okta verwenden

Okta kann als Workload-Identity-Provider fungieren, indem es OIDC-Access-Tokens über den OAuth 2.0 client_credentials-Grant an eine Service Application 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 Standard-Server verwendest, lautet der Pfad /oauth2/default.

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



Voraussetzungen

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



Okta konfigurieren

Auf hoher Ebene musst du:

1. Eine Okta Service Application erstellen.
2. Deinen Standard-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 der Konfiguration deiner Okta-Org und der Version der Admin Console ab. Die folgenden nummerierten Schritte führen durch einen gängigen Weg:

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 die generierte Client ID.
2. Konfiguriere die Client-Authentifizierung. Für ein Setup ohne Schlüsselgeheimnis 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 in der Anwendung 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 tragen. 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 es 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 Tab Claims 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 Anwendung 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, die Erstellung eines Service Accounts und die Erstellung 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 in Okta Custom Claims 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 beziehen und die Claude API aufrufen

Anders als plattformnative Provider (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-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "text"))

Jeder SDK-Tab zeigt das Callable-Muster: Das Anthropic SDK ruft deinen Identity-Token-Provider erneut auf, wann immer das Anthropic-Access-Token sich dem Ablauf nähert. Dein Okta-Fetcher sollte daher 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, also aktualisiere diese Datei bei lang laufenden Shells über einen Timer.



Das Setup überprüfen

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 Regel eingrenzen

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

• Fixiere die exakte Client ID: Setze subject_prefix auf die vollständige Client ID der Service App ohne abschließendes *.
• Fixiere 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 Tab Claims des Authorization Servers hinzu und matche sie mit der claims-Map der Regel oder einer CEL-condition.
• Verwende eine Regel pro Service App: Erstelle für jede Service App eine separate Federation Rule, anstatt eine Regel über mehrere Apps hinweg zu teilen.



Nächste Schritte

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