Aggiungere l'autorizzazione dell'utente utilizzando credenziali di identità federata

Il Servizio di Azure AI Bot ti aiuta a creare agenti che possono accedere a risorse online che richiedono l'autenticazione degli utenti. Il tuo agente non deve gestire i token di autenticazione perché Azure gestisce questo processo. Azure utilizza OAuth 2.0 per generare un token basato sulle credenziali di ogni utente. Il tuo agente utilizza il token generato da Azure per accedere a quelle risorse. Utilizzando questo approccio, l'utente non deve fornire un ID e una password all'agente per accedere a una risorsa protetta, ma deve solo fornirli a un provider di identità attendibile.

Per configurare OAuth su un agente, registra un'istanza del bot di Azure se non lo hai già fatto.

Servizio di identità Microsoft Entra ID

Microsoft Entra ID è un servizio di identità cloud che puoi utilizzare per creare applicazioni che consentono agli utenti di effettuare un accesso sicuro utilizzando protocolli standard di settore come OAuth 2.0.

Usa uno di questi tre servizi di identità:

1. Piattaforma di identità Microsoft (v2.0): nota anche come endpoint Azure Active Directory v2, che rappresenta un'evoluzione della piattaforma Azure AD (v1.0).
2. Credenziali federate: note anche come AAD v2 con credenziali federate.
3. Certificati: noti anche come AAD v2 con certificati.

Utilizzando questi servizi, puoi creare applicazioni che si autenticano presso tutti i provider di identità Microsoft e ricevono token per accedere alle API Microsoft, come Microsoft Graph, o ad altre API create da sviluppatori.

Creare il provider di identità di Microsoft Entra ID

Questa sezione mostra come creare un provider di identità Microsoft Entra ID che utilizza OAuth 2.0 per autenticare l'agente per Microsoft Graph.

Creare una registrazione app

1. Apri il pannello Microsoft Entra ID nel portale di Azure. Se non sei nel tenant corretto, seleziona Cambia directory per passare al tenant corretto. Per informazioni su come creare un tenant, consulta Accedi al portale e crea un tenant.

2. Apri il pannello Registrazioni app.

3. Configura la registrazione dell'app:

   1. Per Teams SSO, apri la registrazione dell'app esistente per l'agente/bot di Azure:

      1. Nel riquadro Autenticazione, se non vedi una piattaforma Web, seleziona Aggiungi una piattaforma.

      2. Selezionare Web.

      3. Inserisci l'URI di reindirizzamento dalla tabella nel passaggio successivo.

      4. Seleziona Configura.

         

   2. Per altri canali o OAuth:

      1. Nel pannello Registrazioni app, seleziona Nuova registrazione.

      2. Compila i campi obbligatori e crea la registrazione dell'app:

         1. Assegnare un nome all'applicazione.

         2. Seleziona i tipi di account supportati per la tua applicazione. Seleziona Tenant singolo.

         3. Per URI di reindirizzamento, seleziona Web e imposta l'URL su uno degli URL di reindirizzamento OAuth supportati:

            Residenza dei dati	Cloud	URL OAuth	URL di reindirizzamento OAuth
            Nessuna	Pubblica	https://token.botframework.com	https://token.botframework.com/.auth/web/redirect
            Europa	Pubblica	https://europe.token.botframework.com	https://europe.token.botframework.com/.auth/web/redirect
            Stati Uniti	Pubblica	https://unitedstates.token.botframework.com	https://unitedstates.token.botframework.com/.auth/web/redirect
            India	Pubblica	https://india.token.botframework.com	https://india.token.botframework.com/.auth/web/redirect
            Nessuna	Azure per enti pubblici	https://token.botframework.azure.us	https://token.botframework.azure.us/.auth/web/redirect
            Nessuna	Azure gestita da 21Vianet	https://token.botframework.azure.cn	https://token.botframework.azure.cn/.auth/web/redirect

         4. Selezionare Registrazione. Una volta completata la registrazione dell'app, Azure visualizza la pagina Panoramica dell'app.

         5. Registra il valore ID applicazione (client). Utilizzerai questo valore in un secondo momento come l'ID client quando crei la stringa di connessione e registri il provider Microsoft Entra ID con la registrazione dell'agente.

         6. Registrare il valore ID della Directory (tenant). Utilizzi questo valore per registrare questa applicazione provider con il tuo bot.

Aggiungere credenziali per la tua app

1. Nel riquadro di spostamento, seleziona Certificati e segreti per aggiungere le credenziali alla tua applicazione.

2. In Credenziali federate, seleziona Aggiungi credenziali.

   

3. In Aggiungi credenziali, scegli lo scenario delle credenziali federate come Altro emittente.

   

4. Inserisci i valori nei campi obbligatori e verifica e aggiorna le impostazioni:

   1. Fornisci informazioni in Collega il tuo account.

      

   2. Emittente: https://login.microsoftonline.com/{customer-tenant-ID}/v2.0.

   3. Identificatore del soggetto: /eid1/c/pub/t/{base64 encoded customer tenant ID}/a/{base64 encoded 1-P app client ID}/{unique-identifier-for-projected-identity}.

      La seguente tabella contiene rappresentazioni in byte-array codificate in Base64url degli ID delle applicazioni di prima parte supportate. Usa il valore che rappresenta l'app proprietaria.

      Valore codificato	Descrizione
      9ExAW52n_ky4ZiS_jhpJIQ	Codifica Base64url dell'Archivio Token del servizio bot
      ND1y8_Vv60yhSNmdzSUR_A	Valore codificato Base64url del portale per sviluppatori di Bot Framework

      La tabella seguente contiene le rappresentazioni in byte-array codificate in Base64url di alcuni ID tenant supportati. Usa il valore che rappresenta il tenant della tua app.

      Valore codificato	Descrizione
      v4j5cvGGr0GRqy180BHbRw	ID tenant MSIT con codifica Base64url (aaaabbbb-0000-cccc-1111-dddd2222eeee)
      PwFflyR_6Een06vEdSvzRg	ID tenant PME con codifica Base64url (bbbbcccc-1111-dddd-2222-eeee3333ffffff)
      6q7FzcUVtk2wefyt0lBdwg	ID tenant Torus codificato Base64url (ccccddddd-2222-eeee-3333-ffff4444aa)
      IRngM2RNjE-gVVva_9XjPQ	ID tenant AME con codifica Base64url (ddddeeee-3333-ffff-4444-aaaa5555bbbb)

      I principali proprietari del servizio di identità calcolano questo valore una volta e lo forniscono ai loro utenti.

   4. Identificatore univoco per identità proiettata: un identificatore univoco, a tua scelta, che utilizzi nell'impostazione di connessione OAuth sul bot di Azure.

   5. Nome: nome a tua scelta, ad esempio "agent oauth".

   6. Gruppo di destinatari: api://AzureADTokenExchange (usa valori specifici del cloud).

5. Fornisci informazioni in Dettagli credenziali.

   

6. Seleziona Aggiungi per aggiungere le credenziali.

Esponi un endpoint API

1. Seleziona Esponi un API nella barra di scorrimento sinistra.

   • Per un bot del servizio Azure Bot: il valore predefinitoapi://{appid} è adatto.
   • Per un bot di Teams: questo formato è OBBLIGATORIOapi://botid-{appid}.

2. Aggiungi un ambito:

   1. Seleziona Aggiungi un ambito nella sezione Ambiti definiti da questa API.

      

   2. Inserisci i dettagli per configurare l'ambito.

      

   3. Immetti il nome dell'ambito defaultScopes.

   4. Seleziona l'utente che può dare il consenso per questo ambito. L'opzione predefinita è Solo amministratori.

   5. Immetti il nome visualizzato del consenso amministratore.

   6. Immetti la descrizione del consenso dell'amministratore.

   7. Immetti il nome visualizzato del consenso utente.

   8. Inserisci la descrizione del consenso dell'utente.

   9. Seleziona l'opzione Abilitato per lo stato.

   10. Seleziona Aggiungi ambito.

3. Solo per Teams, configura un'applicazione client autorizzata:

   1. Seleziona Aggiungi applicazione client.

      

   2. Inserisci l'ID client Microsoft 365 appropriato per le applicazioni che vuoi autorizzare per l'app web della tua applicazione.

      

   3. Seleziona uno dei seguenti ID clienti:

      ID client da utilizzare	Tipo di app da autorizzare
      1fec8e78-bce4-4aaf-ab1b-5451cc387264	Applicazione per dispositivi mobili o desktop di Teams
      5e3ce6c0-2b1f-4285-8d4b-75ee78787346	Applicazione Web Teams
      4765445b-32c6-49b0-83e6-1d93765276ca	Applicazione web Microsoft 365
      0ec893e0-5785-4de6-99da-4ed124e5296c	Applicazione desktop Microsoft 365
      d3590ed6-52b3-4102-aeff-aad2292ab01c	Applicazione per dispositivi mobili Microsoft 365/Applicazione desktop Outlook
      bc59ab01-8403-45c6-8796-ac3ef710b3e3	Applicazione web Outlook
      27922004-5251-4030-b22d-91ecd9a37ea4	Applicazione per dispositivi mobili Outlook

   4. Seleziona l'URI ID applicazione creato per l'app in Ambiti autorizzati per aggiungere l'ambito all'API Web esposta.

   5. Seleziona Aggiungi applicazione.

      

Impostare le autorizzazioni API per l'app

1. Nel riquadro di spostamento, seleziona Autorizzazioni API per aprire il pannello Autorizzazioni API. Imposta le autorizzazioni API per l'app:

2. Seleziona Aggiungi un'autorizzazione per mostrare il riquadro Richiedi autorizzazioni API.

3. Per questo esempio, seleziona API Microsoft e Microsoft Graph.

4. Seleziona Autorizzazioni delegate e verifica che siano selezionate le autorizzazioni necessarie. Questo esempio richiede le autorizzazioni User.Read.

   Suggerimento

   Evita le autorizzazioni contrassegnate come CONSENSO AMMINISTRATORE OBBLIGATORIO perché richiedono sia l'accesso di un utente che di un amministratore tenant.

Ora hai un'applicazione OAuth configurata.

Creare una connessione OAuth per il bot di Azure

Successivamente, registra il provider di identità con l'agente:

1. Apri la pagina della risorsa bot di Azure del tuo bot nel portale di Azure.

2. Seleziona Impostazioni, quindi seleziona Configurazione.

3. Seleziona il pulsante Impostazioni connessione OAuth nella parte inferiore della pagina.

4. Compila il modulo nel modo seguente:

   1. Nome. immettere un nome per la connessione. Usalo nel codice dell'agente.

   2. Provider di servizi. Seleziona AAD v2 con credenziali federate per visualizzare i campi specifici del provider di servizi.

   3. ID client. Immetti l'ID (client) dell'applicazione che hai registrato per il provider di identità Microsoft Entra ID (solo tenant singolo supportato).

   4. Identificatore univoco. Inserisci l'identificatore unico che hai registrato per il tuo provider di identità Microsoft Entra ID quando hai creato le credenziali federate.

   5. URL di scambio del token. Per SSO di Teams, inserisci l'endpoint API creato in precedenza: api://botid-{appId}. Altrimenti, lascia vuoto il campo.

   6. ID tenant. Inserisci l'ID della directory (tenant) che hai registrato in precedenza per la tua app Microsoft Entra ID o common, a seconda dei tipi di account supportati selezionati quando hai creato l'app Azure DD. Per decidere quale valore assegnare, segui questi criteri:

      • Quando crei l'app Microsoft Entra ID, se selezioni Account solo in questa directory organizzativa (solo Microsoft - Tenant singolo), inserisci l'ID tenant annotato in precedenza per l'app Microsoft Entra ID.
      • Tuttavia, se è stato selezionato Account in qualsiasi directory dell'organizzazione (qualsiasi directory Microsoft Entra ID - Multitenant e account Microsoft personali, ad esempio Xbox, Outlook.com) o Account in qualsiasi directory dell'organizzazione (directory Microsoft Entra ID - Multitenant), immetti common anziché un ID tenant. Altrimenti, l'app Microsoft Entra ID verifica attraverso il tenant il cui ID hai selezionato ed esclude gli account Microsoft personali.

      Nota

      Questo tenant è associato agli utenti che possono essere autenticati. Per altre informazioni, vedi Creare un tenant in Microsoft Entra ID.

   7. In Ambiti, inserisci i nomi delle autorizzazioni scelte dalla registrazione dell'applicazione. Per scopi di test, puoi semplicemente inserire: User.Read. Se devi utilizzare questo token per OBO verso un altro servizio (un token interscambiabile), usa api://botid-{{appId}}/defaultScopes.

   Nota

   Per Microsoft Entra ID, il campo Ambiti accetta un elenco di valori con distinzione tra maiuscole e minuscole, separati da spazi.

5. Seleziona Salva.

Test della connessione

1. Seleziona la voce della connessione per aprire la connessione che hai creato.

2. Seleziona Test connessione nella parte superiore del riquadro Impostazioni connessione del provider di servizi.

3. La prima volta, questa azione apre una nuova scheda del browser che elenca le autorizzazioni che la tua app richiede e ti invita ad accettarli.

4. Seleziona Accetta.

5. Questa azione ti reindirizza alla pagina Connessione di test a nome-connessione completato, dove your-connection-succeeded è il nome di connessione specifico.

6. Solo per token interscambiabili:

   1. Copia il token JSON Web (JWT).

   2. Decodifica il token usando https://jwt.io/.

   3. Il valore dell'attestazione aud dovrebbe iniziare con api://.