Utilizzare 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 con Okta (tipicamente con private_key_jwt, così 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 di breve durata.

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

Esistono molti modi per configurare e autenticarsi con Okta 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: account di servizio, issuer di federazione e regole di federazione.
• Un'organizzazione Okta con API Access Management abilitato (necessario 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 in grado di richiedere un token dall'endpoint /v1/token di Okta e di raggiungere api.anthropic.com.

Configurare Okta

A grandi linee 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 desideri effettuare il matching.

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

1. Crea un'integrazione app di servizio. Nella Okta Admin Console, crea una nuova integrazione 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 sia autorizzata a richiedere (ad esempio, anthropic.access). Okta rifiuta le richieste client_credentials che non includono uno scope concesso.

Per un'app di servizio che utilizza 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.

Configurare Anthropic

Segui la procedura di configurazione per registrare un issuer di federazione, creare un account di servizio Anthropic e creare una regola di federazione nella Claude Console. Usa questi valori specifici per Okta.

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 esso pubblica.

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

Regola di federazione: Effettua il matching sul claim sub di Okta, che corrisponde al Client ID dell'app di servizio. Se hai definito claim personalizzati in Okta, puoi effettuare il matching 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
}

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 token di identità.

Ogni scheda SDK mostra il pattern callable: l'SDK Anthropic richiama nuovamente 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 anziché memorizzarne uno nella cache a tempo indeterminato. La CLI ant rilegge ANTHROPIC_IDENTITY_TOKEN_FILE a ogni scambio, quindi aggiorna quel file con un timer per le shell a lunga esecuzione.

Verificare 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).

Definire l'ambito della 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 matching sul valore audience che hai configurato sul server di autorizzazione, in modo che i token emessi per un audience diverso vengano rifiutati.
• Effettua il matching su claim personalizzati: Per una definizione dell'ambito più granulare, aggiungi claim nella scheda Claims del server di autorizzazione ed effettua il matching su di essi 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 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 il matching su claim Okta personalizzati con espressioni CEL.