---
title: Single sign-on
url: https://platform.claude.com/docs/it/managed-agents/self-hosted/configure
description: Consenti a persone e servizi di chiamare il tuo server Claude Managed Agents self-hosted con token emessi dal tuo provider di identità.
---

<Note>
  Per richiedere l’accesso a Claude Managed Agents self-hosted, contatta il tuo team di riferimento Anthropic.
</Note>

Per impostazione predefinita, il tuo server accetta una sola chiave condivisa, la [chiave API del server](https://platform.claude.com/docs/it/managed-agents/self-hosted#the-three-credentials). 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à

<Steps>
  <Step title="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.
  </Step>

  <Step title="Elenca il provider di identità nel file delle impostazioni">
    Aggiungi una voce sotto `auth.issuers` nel [file delle impostazioni](https://platform.claude.com/docs/it/managed-agents/self-hosted/configuration-reference#where-settings-go):

    ```yaml
    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](https://platform.claude.com/docs/it/managed-agents/self-hosted/configuration-reference#issuer-entries). Se il tuo provider è Microsoft Entra ID, consulta anche [Microsoft Entra ID](https://platform.claude.com/docs/it/managed-agents/self-hosted/configure#microsoft-entra-id).
  </Step>

  <Step title="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=`).
  </Step>
</Steps>

### Se l’accesso non riesce

| Risposta                                  | Causa                                                                    | La riga di log del server contiene |
| ----------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------- |
| `401`, lo stesso di una chiave API errata | Il token non ha superato un controllo. La riga di log riporta il motivo. | `oidc token`                       |
| `403`                                     | I gruppi del token non corrispondono ad alcuna voce di `roles`           | `token holds no role`              |

### 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

| Ruolo                              | Agenti, skill, sessioni, vault e memory store         | Ambienti                                               |
| ---------------------------------- | ----------------------------------------------------- | ------------------------------------------------------ |
| `admin` e la chiave API del server | Vede e modifica tutto                                 | Li crea, modifica ed elimina, e crea le loro chiavi    |
| `developer` o `user`               | Vede e modifica solo ciò che quel chiamante ha creato | Li elenca, li legge ed esegue sessioni al loro interno |

`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.

<Steps>
  <Step title="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](https://platform.claude.com/docs/it/managed-agents/self-hosted/configure#other-redirect-uris).
  </Step>

  <Step title="Aggiungi l’applicazione alla voce dell’issuer">
    Aggiungi `login_client_id` e `login_scopes` alla voce dell’issuer e riavvia il server:

    ```yaml
    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.
  </Step>

  <Step title="Accedi">
    Ogni sviluppatore esegue il login dalla radice dell’archivio estratto:

    ```bash
    ./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](https://platform.claude.com/docs/it/managed-agents/self-hosted/configure#other-redirect-uris), 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.
  </Step>
</Steps>

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

| Provider                                               | URI di reindirizzamento da registrare                             | Flag che gli sviluppatori aggiungono al comando `login` |
| ------------------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------- |
| Microsoft Entra ID                                     | `http://localhost/callback`                                       | `-listen localhost:0`                                   |
| Uno che richiede la porta nell’URI di reindirizzamento | Un URI con una porta fissa, come `http://127.0.0.1:8123/callback` | `-listen 127.0.0.1:8123`                                |

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](https://platform.claude.com/docs/it/managed-agents/self-hosted/configure#let-developers-log-in-from-a-terminal). Per completarne la configurazione, consulta [Configurare l’accesso](https://platform.claude.com/docs/it/managed-agents/self-hosted/console#set-up-sign-in).