Configurare l'accesso Single Sign-On con Microsoft Entra ID

Creare registrazioni app per il sito Web personalizzato

Per configurare SSO, crea due registrazioni separate per app:

• Registrazione di un'app di autenticazione per l'autenticazione dell'utente Microsoft Entra ID nel tuo agente.
• Una registrazione dell'app Canvas per la tua pagina web personalizzata.

Per motivi di sicurezza, non riutilizzare la stessa registrazione dell'app sia per l'agente che per il sito Web personalizzato.

1. Per creare una registrazione dell'app di autenticazione, seguire le istruzioni in Configurare l'autenticazione utente con Microsoft Entra ID.

2. Crea una seconda registrazione dell'app da utilizzare come registrazione dell'app canvas.

Aggiungere un URL di scambio di token

Usa l'URI dell'ambito completo che la registrazione dell'app di autenticazione espone come URL di scambio dei token. Se non hai creato un ambito personalizzato, segui prima Configura l'autenticazione utente con Microsoft Entra ID.

1. Nella pagina di registrazione dell'app di autenticazione del portale di Azure passare a Esporre un'API.

2. Sotto Ambiti, seleziona l'icona Copia negli appunti.

3. In Copilot Studio, nel menu di navigazione sotto Impostazioni, selezionare Sicurezza e quindi selezionare il riquadro Autenticazione.

4. Per URL di scambio token (richiesto per SSO), incolla l'ambito che hai copiato in precedenza.

5. Seleziona Salva, poi pubblica il tuo agente.

Autorizza l'app Canvas a utilizzare l'ambito dell'app di autenticazione

1. Nel portale Azure, apri la registrazione dell'app Canvas e vai su Panoramica.

2. Copiare il valore ID applicazione (client) in Informazioni di base.

3. Apri la registrazione dell'app e poi seleziona Gestisci>, quindi Esporre un'API.

4. In Applicazioni client autorizzate selezionare Aggiungi applicazione client.

5. In Client ID, incolla l'ID client dell'app Canvas.

6. In Ambiti autorizzati, seleziona l'ambito che hai creato per lo scambio dei token e poi seleziona Aggiungi applicazione.

Configurare la registrazione dell'app canvas

1. Apri la registrazione dell'app Canvas e vai su Autenticazione.

2. In Configurazioni della piattaforma, seleziona Aggiungi una piattaforma, quindi seleziona SPA.

3. In URI di reindirizzamento immettere l'URL per la pagina Web. Ad esempio: https://www.contoso.com/index.html.

4. Nella sezione Concessione implicita e flussi ibridi, attiva Token di accesso (usati per flussi impliciti) e Token ID (usati per i flussi impliciti ed ibridi).

5. Seleziona Configura.

Configurare SSO nella pagina web

Usa l'esempio completo di SSO di Microsoft Entra ID, inclusi le sue librerie e il middleware chat Web. Segui il README dell'esempio e aggiorna i segnaposto di configurazione in index.html.

1. Nel portale Azure, apri la registrazione dell'app Canvas.

2. In Panoramica, copia ID applicazione (client) e ID directory (tenant).

   

3. Sostituisci i segnaposto dell'ID client e tenant ID dell'esempio con i valori della registrazione dell'app Canvas. Non usare qui l'ID client dell'app di autenticazione.

4. Sostituisci il segnaposto del token endpoint con l'URL dell'endpoint del token dell'agente.

5. Se personalizzate l'ID utente, mantinetelo entro il limite di 64 caratteri del campione.

6. Salvare le modifiche.

7. Ospita la pagina all'URL di reindirizzamento che hai registrato. Accedi usando il pulsante di accesso dell'esempio, poi avvia una conversazione che richiede autenticazione.

   Quando lo scambio di token ha successo, l'agente non ti chiede di accedere di nuovo né di copiare un codice di validazione nella chat. Se sì, controlla gli identificatori dell'app canvas, l'ambito autorizzato, l'URL dello scambio di token e la pubblicazione dell'agente.

   Note

   Il pulsante di accesso dell'esempio avvia la sessione iniziale dopo l'accesso. In produzione, la tua app deve gestire quell'accesso iniziale. Mantieni disponibile la scheda di accesso di fallback se lo scambio dei token fallisce.

Le seguenti procedure configurano un canvas del sito Web personalizzato per un agente creato nel piano Teams. Non è la procedura di configurazione per il canale Microsoft Teams.

Panoramica tecnica

SSO in una canvas personalizzata utilizza il seguente flusso di scambio di token:

1. L'utente dell'agente inserisce una frase che attiva un argomento di autenticazione. Il tema di accesso è progettato per consentire all'utente di accedere e utilizzare il token autenticato (variabile User.AccessToken) dell'utente.

2. Copilot Studio invia un prompt di accesso per consentire all'utente di accedere usando il provider di identità configurato.

3. Il canvas personalizzato dell'agente intercetta la richiesta di accesso e richiede un token OBO da Microsoft Entra ID. Il canvas invia il token all'agente.

4. L'agente scambia il token OBO con un token di accesso e lo memorizza in User.AccessToken. Anche la variabile User.IsLoggedIn è impostata in questo momento.

Creare una registrazione dell'applicazione in Microsoft Entra ID per il canvas personalizzato

Per configurare SSO, servono due registrazioni separate per le app:

• Una per l'autenticazione utente del tuo agente con Microsoft Entra ID.
• Uno per SSO nel tuo canvas personalizzato.

Creare una registrazione di app per il canvas dell'agente

1. Accedi al portale di Azure.

2. Passare a Registrazioni app selezionando l'icona o cercando nella barra di ricerca superiore.

3. Seleziona Nuova registrazione.

4. Immetti un nome per la registrazione. Usa il nome dell'agente di cui stai registrando il canvas e includere "canvas" per separarlo dalla registrazione dell'app per l'autenticazione.

   Ad esempio, se l'agente si chiama "Contoso sales help", potresti denominare la registrazione dell'app come "ContosoSalesCanvas" o qualcosa di simile.

5. In Tipi di account supportati, seleziona Account in qualsiasi tenant organizzativo (qualsiasi directory Microsoft Entra ID - Multitenant) e account personali Microsoft (ad esempio, Skype, XBOX).

6. Lascia la sezione URI di reindirizzamento vuota per il momento, poiché inserirai le informazioni nei passaggi successivi. Seleziona Registro.

7. Una volta completata la registrazione, viene aperta la pagina Panoramica. Vai a Manifesto. Verifica che accessTokenAcceptedVersion sia impostato su 2. In caso contrario, modificalo in 2 e seleziona Salva.

Aggiungi l'URL di reindirizzamento

1. Con la registrazione aperta, vai a Autenticazione e seleziona Aggiungi una piattaforma.

2. Nel pannello Configura piattaforme selezionare Web.

3. In URL di reindirizzamento, aggiungi l'URL completo alla pagina in cui è ospitato il canvas della chat. Nella sezione Concessione implicita, seleziona le caselle di controllo Token di ID e Token di accesso.

4. Seleziona Configura per confermare le modifiche.

5. Vai ad Autorizzazioni API. Seleziona Concedi consenso amministratore per il <nome del tenant> e quindi Sì.

   Importante

   Per evitare che gli utenti debbano fornire il consenso per ciascuna applicazione, qualcuno con il ruolo di amministratore dell'applicazione o amministratore dell'applicazione cloud può concedere il consenso a livello di tenant alle registrazioni dell'applicazione.

Definire un ambito d'applicazione personalizzato per l'agente

Definisci uno scope personalizzato per la registrazione dell'app di autenticazione e autorizza l'app canvas a utilizzarlo. Scopri di più sugli scope nel glossario per sviluppatori della Microsoft Identity Platform.

Questo passaggio ti consente di creare una relazione di trust tra la registrazione dell'app di autenticazione per l'autenticazione e la registrazione dell'app per il canvas personalizzato.

1. Apri la registrazione dell'app che hai creato quando hai configurato l'autenticazione.

2. Vai su Permessi API e assicurati di aggiungere i permessi corretti per il tuo agente. Seleziona Concedi consenso amministratore per il <nome del tenant> e quindi Sì.

   Importante

   Per evitare che gli utenti debbano fornire il consenso per ciascuna applicazione, qualcuno con il ruolo di amministratore dell'applicazione o amministratore dell'applicazione cloud può concedere il consenso a livello di tenant alle registrazioni dell'applicazione.

3. Vai a Esponi un'API e seleziona Aggiungi un ambito.

4. Immettere un nome per l'ambito, insieme alle informazioni di visualizzazione visualizzate dagli utenti quando accedono alla schermata SSO. Seleziona Aggiungi ambito.

5. Selezionare Aggiungere un'applicazione client.

6. Inserisci l'ID applicazione (client) dalla pagina Panoramica per la registrazione dell'app canvas nel campo ID client. Selezionare la casella di controllo per l'ambito elencato creato.

7. Seleziona Aggiungi applicazione.

Configura l'autenticazione in Copilot Studio per SSO

Usa l'URL di scambio dei token nella configurazione di autenticazione di Copilot Studio per scambiare il token OBO con il token di accesso richiesto tramite Bot Framework.

Copilot Studio fa una chiamata a Microsoft Entra ID per eseguire lo scambio effettivo.

1. Accedi a Copilot Studio.

2. Apri l'agente che vuoi configurare.

3. Nel menu di navigazione, in Impostazioni seleziona Sicurezza. Quindi, seleziona la scheda Autenticazione.

4. Nell'URL dello scambio di token, inserisci l'URI dell'ambito completo dalla pagina Esporre un'API della registrazione dell'app di autenticazione. Il formato è api://<AuthenticationAppClientId>/<ScopeName>.

5. Seleziona Salva e pubblica il contenuto dell'agente.

Configura il tuo HTML personalizzato di canvas per SSO

Usa l'esempio completo di SSO di Microsoft Entra ID invece di combinare frammenti parziali di script. L'esempio include la configurazione della Libreria di Autenticazione Microsoft (MSAL), il middleware chat Web e la gestione dello scambio di token.

1. Segui il README dell'esempio per configurare l'ID Application (client) e l'ID della directory (tenant) dell'app canvas.

2. Configura l'URL del token endpoint per il tuo agente. Non costruire un endpoint token dall'ID dell'agente.

3. Mantieni il fallback della scheda di accesso quando l'acquisizione silenziosa del token o lo scambio di token falliscono.

4. Ospita la pagina all'URL di reindirizzamento che hai registrato. Accedi usando il pulsante del campione e poi attiva un topic dell'agente che richiede autenticazione. Conferma che lo scambio di token riuscito evita un secondo prompt di accesso o un codice di validazione.

Codice di esempio completo

Scopri di più sull'esempio SSO di Microsoft Entra ID. Usa le istruzioni di registrazione e configurazione dell'app che corrispondono alla versione dell'esempio che distribuisci.