Usa WIF con Okta

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

L'URL dell'issuer del server di autorizzazione 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 e autenticarsi su Okta che esulano dall'ambito di questa documentazione. Assicurati che i tuoi meccanismi di configurazione e autenticazione seguano le linee guida e le pratiche di sicurezza della tua azienda.



Prerequisiti

• Familiarità con i concetti di WIF: account di servizio, issuer di federazione e regole di federazione.
• Un'organizzazione Okta con API Access Management abilitato (richiesto per i server di autorizzazione personalizzati).
• Autorizzazione a creare account di servizio, issuer di federazione e regole di federazione nella Claude Console per la tua organizzazione Anthropic.
• Un workload che possa richiedere un token dall'endpoint /v1/token di Okta e raggiungere api.anthropic.com.



Configura Okta

Ad alto livello devi:

1. Creare un'applicazione di servizio Okta.
2. Configurare il tuo server di autorizzazione predefinito (o creare un nuovo server di autorizzazione personalizzato) con un'audience, uno scope, una policy di accesso e qualsiasi claim personalizzato su cui vuoi effettuare il match.

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ò memorizzarne uno in modo sicuro. Per l'esempio seguente potrebbe essere necessario 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 server di autorizzazione personalizzato, 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 server di autorizzazione personalizzato, assicurati che esista almeno uno scope che l'app di servizio è autorizzata a richiedere (ad esempio, anthropic.access). Okta rifiuta le richieste client_credentials che non includono uno scope concesso.
5. Crea una policy di accesso. Sul tuo server di autorizzazione personalizzato, crea una policy di accesso con almeno una regola che consenta alla tua app di servizio di richiedere lo scope concesso al passaggio 4.
6. (Facoltativo) Aggiungi claim personalizzati. Se vuoi effettuare il match su qualcosa di diverso dal client ID, aggiungi un claim al token di accesso nella scheda Claims del tuo server di autorizzazione.

Per un'app di servizio 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 del server di autorizzazione.



Configura 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 account di servizio e nella creazione di una regola di federazione.

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:

Issuer di federazione: Usa l'URL del tuo server di autorizzazione personalizzato 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 questo pubblicizza.

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

Regola di federazione: Effettua il match sul claim sub di Okta, che è il Client ID dell'app di servizio. Se hai definito claim personalizzati in Okta, puoi effettuare il match su quelli invece, usando 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
}



Acquisisci un token e chiama la Claude API

A differenza dei provider nativi delle piattaforme (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 dei token di Okta per ottenere un JWT, quindi passare quel JWT all'SDK di Anthropic come token di identità.

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",
            # 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 dell'SDK mostra il pattern con callable: l'SDK di Anthropic richiama il tuo provider di token di identità 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 invece di memorizzarne uno nella cache indefinitamente. La CLI ant rilegge ANTHROPIC_IDENTITY_TOKEN_FILE a ogni scambio, quindi aggiorna quel file con un timer per le shell a lunga esecuzione.



Verifica la configurazione

Uno scambio riuscito restituisce un access_token che inizia con sk-ant-oat01- e un valore expires_in in secondi. In caso di 400 invalid_grant, consulta Risolvere i problemi di uno scambio non riuscito; la causa più comune lato Okta è una mancata corrispondenza di issuer_url (deve includere il percorso /oauth2/<auth-server-id>; il server di autorizzazione dell'organizzazione Okta non è utilizzabile).



Limita l'ambito della tua regola

Limita 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 dell'app di servizio senza * finale.
• Fissa l'audience: Effettua il match sul valore audience che hai configurato sul server di autorizzazione in modo che i token emessi per un'audience diversa vengano rifiutati.
• Effettua il match su claim personalizzati: Per un ambito più granulare, aggiungi claim nella scheda Claims del server di autorizzazione ed effettua il match con la mappa claims della regola o una condition CEL.
• Usa una regola per ogni app di servizio: Crea una regola di federazione separata per ogni app di servizio invece di condividere una regola tra più app.



Prossimi passi

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