Usare WIF con Okta

Okta può agire come provider di identità per workload emettendo token di accesso OIDC a una service application (applicazione di servizio) tramite il grant OAuth 2.0 client_credentials. Il tuo workload si autentica presso Okta (tipicamente con private_key_jwt, così non viene memorizzato alcun segreto condiviso), riceve un JSON Web Token (JWT) firmato e scambia quel JWT con Anthropic per ottenere un token di accesso di breve durata.

L'URL dell'issuer dell'authorization server di Okta ha la forma https://<your-domain>.okta.com/oauth2/<auth-server-id>. Se usi il server predefinito integrato, il percorso è /oauth2/default.

Esistono molti modi per configurare Okta e autenticarsi presso di esso che esulano dall'ambito di questa documentazione. Assicurati che la tua configurazione e i tuoi meccanismi di autenticazione seguano le linee guida e le pratiche di sicurezza della tua azienda.

Prerequisiti

• Familiarità con i concetti di WIF: service account, federation issuer e federation rule.
• Un'organizzazione Okta con API Access Management abilitato (necessario per i custom authorization server).
• Permesso di creare service account, federation issuer e federation rule nella Claude Console per la tua organizzazione Anthropic.
• Un workload in grado di richiedere un token dall'endpoint /v1/token di Okta e di raggiungere api.anthropic.com.

Configurare Okta

Ad alto livello devi:

1. Creare una service application Okta.
2. Configurare il tuo authorization server predefinito (o creare un nuovo custom authorization server) con un'audience, uno scope, una access policy e qualsiasi claim personalizzato su cui vuoi effettuare la corrispondenza.

La navigazione esatta dipende dalla configurazione della tua organizzazione Okta e dalla versione della console di amministrazione. I seguenti passaggi numerati illustrano un percorso comune:

1. Crea un'integrazione di app di servizio. Nella Okta Admin Console, crea una nuova integrazione di app di tipo API Services (OIDC, machine-to-machine). Prendi nota del Client ID generato.
2. Configura l'autenticazione del client. Per una configurazione senza chiavi, scegli Public key / Private key (private_key_jwt) e registra la JWK pubblica del tuo workload. In alternativa, usa un client secret se il tuo ambiente può memorizzarlo in modo sicuro. Per l'esempio seguente potresti dover disabilitare il requisito DPoP sull'applicazione; assicurati che la tua configurazione di produzione rispetti i requisiti di sicurezza della tua organizzazione.
3. Imposta l'audience. Sul tuo custom authorization server, imposta l'audience su https://api.anthropic.com in modo che i token di accesso emessi contengano quel claim aud. Anthropic valida aud rispetto a questo valore fisso.
4. Concedi uno scope. Sul tuo custom authorization server, assicurati che esista almeno uno scope che la service app sia autorizzata a richiedere (ad esempio, anthropic.access). Okta rifiuta le richieste client_credentials che non includono uno scope concesso.
5. Crea una access policy. Sul tuo custom authorization server, crea una access policy con almeno una regola che consenta alla tua service app di richiedere lo scope concesso al passaggio 4.
6. (Facoltativo) Aggiungi claim personalizzati. Se vuoi effettuare la corrispondenza su qualcosa di diverso dal client ID, aggiungi un claim al token di accesso nella scheda Claims del tuo authorization server.

Per una service app che usa client_credentials, Okta imposta il claim sub del token di accesso emesso sul Client ID dell'applicazione, e iss sull'URL dell'issuer dell'authorization server.

Configurare Anthropic

Nella Claude Console, apri Settings → Workload identity, fai clic su Connect workload e seleziona Custom OIDC. La procedura guidata ti accompagna nella registrazione dell'issuer, nella creazione di un service account e nella creazione di una federation rule.

La procedura guidata crea queste risorse per te. Usa i seguenti valori sia che tu li inserisca nella procedura guidata sia che li invii all'Admin API:

Federation issuer: Usa l'URL del tuo custom authorization server Okta e la modalità discovery. Anthropic legge il documento di discovery .well-known/openid-configuration di Okta e recupera il JWKS dal jwks_uri che esso pubblica.

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

Federation rule: Effettua la corrispondenza sul claim sub di Okta, che è il Client ID della service app. Se hai definito claim personalizzati in Okta, puoi invece effettuare la corrispondenza su quelli con la mappa claims o una condition CEL.

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

Acquisire un token e chiamare la Claude API

A differenza dei provider nativi della piattaforma (AWS, Google Cloud, Kubernetes), che rendono disponibile un token all'interno del runtime del workload (tramite un file proiettato o un endpoint di metadati locale), Okta non lo fa. Il tuo workload deve chiamare l'endpoint token di Okta per ottenere un JWT, quindi passare quel JWT all'SDK Anthropic come identity token.

import os
import httpx2
import anthropic
from anthropic import WorkloadIdentityCredentials


def fetch_okta_token() -> str:
    response = httpx2.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",
            # Costruisci il JWT client_assertion RFC 7523 firmato con la chiave privata della tua app Okta
            "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"))

Ogni scheda SDK mostra il pattern callable: l'SDK Anthropic richiama il tuo provider di identity token ogni volta che il token di accesso Anthropic si avvicina alla scadenza, quindi il tuo fetcher Okta dovrebbe restituire un token nuovo a ogni chiamata anziché memorizzarne uno in cache indefinitamente. La CLI ant rilegge ANTHROPIC_IDENTITY_TOKEN_FILE a ogni scambio, quindi aggiorna quel file con un timer per le shell di lunga durata.

Verificare la configurazione

Uno scambio riuscito restituisce un access_token che inizia con sk-ant-oat01- e un valore expires_in in secondi. Se lo scambio fallisce con la risposta opaca 401 authentication_error (messaggio Authentication failed), controlla la pagina della cronologia di autenticazione per il motivo del rifiuto e consulta Risolvere i problemi di uno scambio fallito; la causa più comune lato Okta è una mancata corrispondenza di issuer_url (deve includere il percorso /oauth2/<auth-server-id>; l'authorization server dell'organizzazione Okta non è utilizzabile).

Delimitare l'ambito della regola

Vincola il blocco match della regola all'ambito più ristretto adatto al tuo caso d'uso:

• Fissa il Client ID esatto: Imposta subject_prefix sul Client ID completo della service app senza * finale.
• Fissa l'audience: Fai corrispondere il valore audience che hai configurato sull'authorization server in modo che i token emessi per un'audience diversa vengano rifiutati.
• Effettua la corrispondenza su claim personalizzati: Per una delimitazione più granulare, aggiungi claim nella scheda Claims dell'authorization server e falli corrispondere con la mappa claims della regola o una condition CEL.
• Usa una regola per service app: Crea una federation rule separata per ogni service app anziché condividere una regola tra più app.

Passaggi successivi

• Consulta il riferimento WIF per l'ordine completo di risoluzione delle credenziali e la configurazione dei profili.
• Consulta il riferimento WIF per effettuare la corrispondenza su claim Okta personalizzati con espressioni CEL.