Managed AgentsConfigurazione aziendale

Single sign-on

Copy page



Consenti a persone e servizi di chiamare il tuo server Claude Managed Agents self-hosted con token emessi dal tuo provider di identità.

Per impostazione predefinita, il tuo server accetta una sola chiave condivisa, la chiave API del server. Con il “single sign-on” (accesso unico), ogni persona o servizio può anche chiamare il server con un token emesso dal tuo provider di identità OpenID Connect (OIDC). Il server assegna al chiamante un ruolo in base ai gruppi presenti nel token. La chiave API del server continua a funzionare come credenziale di amministratore.

Questa pagina mostra come aggiungere il tuo provider di identità, cosa può fare ciascun ruolo e come consentire agli sviluppatori di accedere da un terminale.

Aggiungere il tuo provider di identità

1. 1

   Registra il server nel tuo provider di identità

   Registra il server come API con un identificatore come api://cma-server e fai in modo che i client richiedano token per esso.

2. 2

   Elenca il provider di identità nel file delle impostazioni

   Aggiungi una voce sotto auth.issuers nel file delle impostazioni:

   auth:
     issuers:
       - name: okta
         issuer_url: https://login.example.com/oauth2/default
         audiences: [api://cma-server]
         roles:
           - group: cma-admins
             role: admin
           - group: "eng-*"
             role: developer

   

   • name etichetta l’issuer nelle righe di log, e il server lo registra come parte del creatore di ciascuna risorsa. Non modificarlo dopo che le persone hanno creato risorse.
   • issuer_url deve essere uguale alla claim iss dei tuoi token.
   • audiences elenca i valori che la claim aud di un token può contenere, come l’identificatore del primo passaggio.
   • roles mappa un gruppo su admin, developer o user. Prevale il ruolo corrispondente più alto.

   Per gli altri campi, consulta Voci degli issuer. Se il tuo provider è Microsoft Entra ID, consulta anche Microsoft Entra ID.

3. 3

   Riavvia il server e verifica l’accesso

   Riavvia il server. Un chiamante invia il token come Authorization: Bearer <token>, su qualsiasi route che accetta la chiave API del server.

   Per ogni richiesta autenticata da un token, il server registra nel log auth=oidc, il name dell’issuer e il subject del chiamante (sub=).

Se l’accesso non riesce

Microsoft Entra ID

Entra ID differisce dagli altri provider in due modi. Entrambe le impostazioni vanno nella voce dell’issuer:

• La persona: Entra ID assegna a una persona un sub diverso in ciascuna applicazione client, quindi con l’impostazione predefinita una stessa persona verrebbe registrata come più creatori. Imposta subject_claim: oid.
• I gruppi: Entra ID omette la claim groups da un token se la persona appartiene a molti gruppi. Quella persona quindi non corrisponde ad alcuna voce di roles. Per evitarlo, fai in modo che Entra ID emetta solo i gruppi assegnati all’applicazione. Oppure assegna gli app role alle persone in Entra ID e imposta groups_claim: roles in modo che il server legga gli app role al posto dei gruppi.

Cosa può fare ciascun ruolo

developer e user hanno lo stesso accesso. Un chiamante con uno dei due ruoli:

• Non può vedere una risorsa creata da qualcun altro. La risorsa è assente dagli elenchi, e una richiesta per il suo ID riceve la stessa risposta di una richiesta per un ID sconosciuto. Questo include tutto ciò che è stato creato con la chiave API del server prima che attivassi il single sign-on.
• Non può condividere una risorsa con un altro chiamante o con un gruppo.

Mappa admin su nomi di gruppo esatti. Un amministratore può anche avviare una sessione che utilizza il vault di qualsiasi utente. Quindi assegna il ruolo solo a gruppi a cui affideresti i token MCP di ogni utente.

Consentire agli sviluppatori di accedere da un terminale

Gli sviluppatori possono accedere tramite il tuo provider di identità e poi usare la CLI ant con la propria identità, senza la chiave API del server. Tu esegui i primi due passaggi, e ciascuno sviluppatore esegue il terzo.

1. 1

   Registra un’applicazione nel tuo provider di identità

   Registra un’applicazione nativa (“public”) che abbia:

   • Nessun client secret
   • Il flusso con codice di autorizzazione (authorization code grant) con PKCE
   • L’URI di reindirizzamento http://127.0.0.1/callback

   Alcuni provider richiedono uno degli altri URI di reindirizzamento.

2. 2

   Aggiungi l’applicazione alla voce dell’issuer

   Aggiungi login_client_id e login_scopes alla voce dell’issuer e riavvia il server:

   login_client_id: 0oa1b2c3d4e5f6g7h8i9
   login_scopes: [openid, cma-server.access]

   

   login_scopes elenca gli scope di cui il tuo provider ha bisogno per emettere un token la cui claim aud sia nell’elenco audiences della voce dell’issuer.

3. 3

   Accedi

   Ogni sviluppatore esegue il login dalla radice dell’archivio estratto:

   ./cma-server-admin login https://cma.example.com

   

   L’URL del server deve essere https://, oppure http:// verso localhost, 127.0.0.1 o ::1. Con uno degli altri URI di reindirizzamento, aggiungi il relativo flag al comando.

   Il comando apre la pagina di accesso del provider in un browser e poi scrive un profilo della CLI ant denominato cma-server. Passa --profile cma-server a qualsiasi comando ant, oppure esegui ant profile activate cma-server per rendere il profilo quello predefinito.

Quando il token scade, lo sviluppatore esegue di nuovo login. Per fare in modo che sia invece la CLI ant a rinnovare il token, aggiungi offline_access a login_scopes.

Altri URI di reindirizzamento

Per elencare gli altri flag, aggiungi -h al comando login.

Consentire alle persone di accedere alla console sul tuo server

La console sul tuo server fa accedere le persone tramite l’applicazione che hai registrato per il login da terminale. Per completarne la configurazione, consulta Configurare l’accesso.