Condividi tramite

Aggiungere l'accesso Single Sign-On a un bot

  • Articolo

SI APPLICA A: SDK v4

Questo articolo illustra come usare la funzionalità Single Sign-On (SSO) in un bot. A tale scopo, questa funzionalità usa un bot consumer, noto anche come bot radice o padre, per interagire con una competenza o un bot figlio. Questo articolo usa i termini bot radice e bot di competenza.

Se si include il supporto SSO, un utente può accedere al bot radice usando un provider di identità e non dovrà eseguire di nuovo l'accesso quando il controllo passa a una competenza.

I bot radice e competenza sono bot separati, in esecuzione su server potenzialmente diversi, ognuno con la propria memoria e stato separati. Per altre informazioni sulle competenze, vedere Panoramica delle competenze e Implementare una competenza. Per altre informazioni sull'autenticazione utente, vedere Nozioni di base sull'autenticazione di Bot Framework, Autenticazione utente e Aggiungere l'autenticazione a un bot.

Importante

Quando si usa l'autenticazione servizio Bot di Intelligenza artificiale di Azure con chat Web, è necessario tenere presenti alcune importanti considerazioni sulla sicurezza. Per altre informazioni, vedere la sezione relativa alle considerazioni sulla sicurezza nell'articolo sull'autenticazione REST.

Prerequisiti

Informazioni sull'esempio

Questo articolo fa riferimento a due bot: RootBot e SkillBot. RootBot inoltra le attività a SkillBot. Tali esempi costituiscono la base per lo scenario di competenze tipico seguente:

  • Un bot radice chiama uno o più bot competenza.
  • I bot radice e competenza implementano l'autenticazione di base descritta nell'articolo Aggiungere l'autenticazione a un bot.
  • L'utente esegue l'accesso al bot radice.
  • A causa dell'accesso Single Sign-On e già connesso al bot radice, questi vengono connessi al bot di competenza senza richiedere di nuovo l'interazione dell'utente.

Per una panoramica del modo in cui Bot Framework gestisce l'autenticazione, vedere Autenticazione utente. Per informazioni generali sull'accesso Single Sign-On, vedere Single Sign-On.

RootBot supporta l'accesso SSO. Comunica con SkillBot per conto dell'utente, senza che l'utente sia necessario eseguire di nuovo l'autenticazione nel _SkillBot.

Per ogni progetto dell'esempio sono necessari gli elementi seguenti:

  1. Un'applicazione Microsoft Entra ID per registrare una risorsa bot in Azure.
  2. Applicazione del provider di identità Microsoft Entra ID per l'autenticazione.

    Nota

    Attualmente è supportato solo il provider di identità Microsoft Entra ID .

Creare la risorsa Azure RootBot

  1. Creare una risorsa bot di Azure nel portale di Azure per .RootBot Seguire la procedura descritta in Creare una risorsa bot di Azure.
  2. Copiare e salvare l'ID app e il segreto client della registrazione del bot.

Creare l'identità dell'ID Microsoft Entra per RootBot

Microsoft Entra ID è un servizio di gestione delle identità cloud che consente di creare applicazioni che accedono in modo sicuro agli utenti usando protocolli standard di settore come OAuth2.0.

  1. Creare un'applicazione di identità per che RootBot usa l'ID Microsoft Entra per autenticare l'utente. Seguire i passaggi descritti in Creare il provider di identità Microsoft Entra ID.

  2. Nel riquadro sinistro selezionare Manifesto.

  3. Impostare accessTokenAcceptedVersion su 2.

  4. Seleziona Salva.

  5. Nel riquadro sinistro selezionare Esporre un'API.

  6. Nel riquadro destro selezionare Aggiungi un ambito.

  7. Nella sezione Aggiungi un ambito all'estrema destra selezionare Salva e continua.

  8. Nella finestra visualizzata, in Chi può fornire il consenso? selezionare Amministratori e utenti.

  9. Immettere le informazioni obbligatorie rimanenti.

  10. Seleziona Aggiungi ambito.

  11. Copiare e salvare il valore dell'ambito.

Creare un'impostazione di connessione OAuth per RootBot

  1. Creare una connessione Microsoft Entra ID nella registrazione del RootBot bot e immettere i valori come descritto in Microsoft Entra ID e il valore descritto di seguito.

  2. Lasciare vuoto il campo relativo all'URL di scambio token.

  3. Nella casella Ambiti immettere il RootBot valore di ambito salvato nei passaggi precedenti.

    Nota

    Gli ambiti contengono l'URL che l'utente accede inizialmente al bot radice, mentre l'URL di scambio di token viene lasciato vuoto.

    Si supponga, ad esempio, che il bot radice appid sia rootAppId e che il bot di competenza appid sia skillAppId. Gli ambiti del bot radice saranno simili a api://rootAppId/customScope, che viene usato per accedere all'utente. Gli ambiti del bot radice vengono quindi scambiati con api://skillAppId/customscope durante l'accesso SSO.

  4. Copiare e salvare il nome della connessione.

Creare la risorsa SkillBot di Azure

  1. Creare una risorsa bot di Azure nel portale di Azure per .SkillBot Seguire la procedura descritta in Creare una risorsa bot di Azure.
  2. Copiare e salvare l'ID app e il segreto client della registrazione del bot.

Creare l'identità dell'ID Microsoft Entra per SkillBot

Microsoft Entra ID è un servizio di gestione delle identità cloud che consente di creare applicazioni che accedono in modo sicuro agli utenti usando protocolli standard di settore come OAuth2.0.

  1. Creare un'applicazione di identità per SkillBot che usa l'ID Microsoft Entra per autenticare il bot. Seguire i passaggi descritti in Creare il provider di identità Microsoft Entra ID.

  2. Nel riquadro sinistro selezionare Manifesto.

  3. Impostare accessTokenAcceptedVersion su 2.

  4. Seleziona Salva.

  5. Nel riquadro sinistro selezionare Esporre un'API.

  6. Nel riquadro destro selezionare Aggiungi un ambito.

  7. Nella sezione Aggiungi un ambito all'estrema destra selezionare Salva e continua.

  8. Nella finestra visualizzata selezionare Amministratori e utenti in Utenti che possono fornire il consenso.

  9. Immettere le informazioni obbligatorie rimanenti.

  10. Seleziona Aggiungi ambito.

  11. Copiare e salvare il valore dell'ambito.

  12. Seleziona Aggiungi applicazione client. Nella sezione all'estrema destra immettere l'ID app dell'identità di RootBot salvato in precedenza nella casella ID client. Assicurarsi di usare l'identità RootBot e non l'ID app di registrazione.

    Nota

    Per le applicazioni client, Azure AI servizio Bot non supporta il singolo sing-on con il provider di identità B2C Microsoft Entra ID.

  13. In Ambiti autorizzati selezionare la casella accanto al valore dell'ambito.

  14. Seleziona Aggiungi applicazione.

  15. Nel riquadro di spostamento a sinistra selezionare Autorizzazioni API. È consigliabile impostare in modo esplicito le autorizzazioni API per l'app.

    1. Nel riquadro destro selezionare Aggiungi un'autorizzazione.

    2. Selezionare API Microsoft e quindi Microsoft Graph.

    3. Scegliere Autorizzazioni delegate e assicurarsi che le autorizzazioni necessarie siano selezionate. Per questo esempio sono richieste le autorizzazioni elencate di seguito.

      Nota

      Qualsiasi autorizzazione contrassegnata come CONSENSO AMMINISTRATORE OBBLIGATORIO richiederà l'accesso sia di un utente che di un amministratore del tenant.

      • openid
      • profile
      • User.Read
      • User.ReadBasic.All

    4. Selezionare Aggiungi autorizzazioni.

Creare un'impostazione di connessione OAuth per SkillBot

  1. Creare una connessione Microsoft Entra ID nella registrazione del SkillBot bot e immettere i valori come descritto in Microsoft Entra ID e i valori descritti di seguito.

  2. Nella casella Token Exchange URL (URL scambio token) immettere il SkillBot valore di ambito salvato nei passaggi precedenti.

  3. Nella casella Ambiti immettere i valori seguenti separati da uno spazio vuoto: openidprofile User.Read User.ReadBasic.All .

  4. Copiare e salvare in un file il nome della connessione.

Testare la connessione

  1. Selezionare la voce di connessione per aprire la connessione creata.
  2. Selezionare Test connessione nella parte superiore del riquadro Impostazioni connessione provider di servizi.
  3. La prima volta si dovrebbe aprire una nuova scheda del browser che elenca le autorizzazioni che l'app richiede e chiede di accettarle.
  4. Selezionare Accetto.
  5. Verrà quindi eseguito il reindirizzamento a una connessione di test alla <pagina Nome-connessione> completata.

Per altre informazioni, vedere Panoramica di Microsoft Entra ID for developers (v1.0) e Panoramica di Microsoft Identity Platform (v2.0). Per informazioni sulle differenze tra gli endpoint versione 1 e 2, vedere Perché eseguire l'aggiornamento a Microsoft Identity Platform (v2.0)?. Per informazioni complete, vedere Microsoft Identity Platform (in precedenza MICROSOFT Entra ID for developers).

Preparare il codice per gli esempi

È necessario aggiornare il file appsettings.json in entrambi gli esempi come descritto di seguito.

  1. Clonare l'accesso SSO con l'esempio Simple Skill Consumer e Skill dal repository GitHub.

  2. Aprire il file appsettings.json del progetto SkillBot. Assegnare i valori seguenti dal file salvato:

    {
    "MicrosoftAppId": "<SkillBot registration app ID>",
    "MicrosoftAppPassword": "<SkillBot registration password>",
    "ConnectionName": "<SkillBot connection name>",
    "AllowedCallers": [ "<RootBot registration app ID>" ]
}

  3. Aprire il file appsettings.json del progetto RootBot. Assegnare i valori seguenti dal file salvato:

    {
    "MicrosoftAppId": "<RootBot registration app ID>",
    "MicrosoftAppPassword": "<RootBot registration password>",
    "ConnectionName": "<RootBot connection name>",
    "SkillHostEndpoint": "http://localhost:3978/api/skills/",
    "BotFrameworkSkills": [
            {
            "Id": "SkillBot",
            "AppId": "<SkillBot registration app ID>",
            "SkillEndpoint": "http://localhost:39783/api/messages"
            }
        ]
}

Testare gli esempi

Per il test usare i comandi seguenti:

  • Comandi di RootBot

    • loginconsente all'utente di accedere alla registrazione dell'ID di Microsoft Entra usando .RootBot Dopo aver eseguito l'accesso, SSO si occupa anche dell'accesso SkillBot a . L'utente non deve eseguire di nuovo l'accesso.
    • token visualizza il token dell'utente.
    • logout disconnette l'utente da RootBot.

  • Comandi di SkillBot

    • skill login consente a RootBot di accedere a SkillBot per conto dell'utente. L'utente non visualizza una scheda di accesso, se già connesso, a meno che l'accesso SSO non riesca.
    • skill token visualizza il token dell'utente da SkillBot.
    • skill logout disconnette l'utente da SkillBot.

Nota

La prima volta che gli utenti provano a eseguire l'accesso Single Sign-On in un bot competenza è possibile che venga visualizzata una scheda OAuth per l'accesso. Ciò è dovuto al fatto che non hanno ancora dato il consenso all'app Microsoft Entra ID della competenza. Per evitare questo problema, possono concedere il consenso amministratore per le autorizzazioni del grafo richieste dall'app Microsoft Entra ID.

Se non è già stato fatto, installare Bot Framework Emulator. Vedere anche Eseguire il debug con l'emulatore.

Sarà necessario configurare l'emulatore per il funzionamento dell'account di accesso di esempio del bot. Seguire questa procedura: come illustrato in Configurare l'emulatore per l'autenticazione.

Dopo aver configurato il meccanismo di autenticazione, è possibile eseguire il test effettivo dell'esempio di bot.

  1. In Visual Studio aprire la soluzione SSOWithSkills.sln e configurarla per avviare il debug con più processi.

  2. Avviare il debug in locale nel computer. Si noti che nel file diRootBot progetto appsettings.json sono disponibili le impostazioni seguenti:

    "SkillHostEndpoint": "http://localhost:3978/api/skills/"
"SkillEndpoint": "http://localhost:39783/api/messages"

    Nota

    Queste impostazioni implicano che RootBot e SkillBot sono in esecuzione nel computer locale. L'emulatore comunica con RootBot sulla porta 3978 e RootBot comunica con SkillBot sulla porta 39783. Non appena si avvia il debug, vengono aperte due finestre del browser predefinite, una per la porta 3978 e l'altra per la porta 39783.

  3. Avviare l'emulatore.

  4. Quando ci si connette al bot, immettere l'ID e la RootBot password dell'app di registrazione.

  5. Digitare hi per iniziare la conversazione.

  6. Immettere login. RootBot visualizzerà una scheda di autenticazione Sign In to AAD (Accedi ad AAD).

    Esempio di scheda di accesso.

  7. Selezionare Accedi. Viene visualizzata la finestra di dialogo popup Confirm Open URL (Conferma apertura URL).

    Screenshot del messaggio di conferma 'open URL'.

  8. Seleziona Conferma. Verrà eseguito l'accesso e verrà visualizzato il RootBot token.

  9. Immettere token per visualizzare di nuovo il token.

    Esempio di messaggio che visualizza il token radice.

    A questo momento è possibile comunicare con .SkillBot Dopo aver eseguito l'accesso con , RootBotnon è necessario fornire di nuovo le credenziali fino a quando non si esce. Ciò dimostra che l'accesso Single Sign-On funziona.

  10. Immettere l'account di accesso alle competenze nella casella Emulator .Enter skill login in the Emulator box. Non verrà chiesto di eseguire di nuovo l'accesso. e verrà invece visualizzato il token di SkillBot.

  11. Immettere il token di competenza per visualizzare di nuovo il token.

  12. A questo punto è possibile immettere skill logout per disconnettersi da SkillBot. Immettere quindi logout per disconnettersi da SimpleRootBoot.

Informazioni aggiuntive

Il diagramma di sequenza temporale seguente si applica agli esempi usati nell'articolo e mostra l'interazione tra i vari componenti coinvolti. ABS è l'acronimo di Azure AI servizio Bot.

Diagramma di sequenza che illustra il flusso del token di competenza.

  1. La prima volta, l'utente immette il comando login per RootBot.
  2. RootBot invia un messaggio OAuthCard per chiedere all'utente di eseguire l'accesso.
  3. L'utente immette le credenziali di autenticazione inviate all'abs (Azure AI servizio Bot).
  4. SAB invia il token di autenticazione, generato in base alle credenziali dell'utente, a RootBot.
  5. RootBot visualizza il token del bot radice per l'utente.
  6. L'utente immette il comando skill login per SkillBot.
  7. SkillBot invia un messaggio OAuthCard a RootBot.
  8. RootBot chiede un token interscambiabile a SAB.
  9. SSO invia il token di competenza SkillBot a RootBot.
  10. RootBot visualizza il token del bot competenza per l'utente. Si noti che il token del bot competenza è stato generato senza che l'utente abbia dovuto accedere a SKillBot. Tale comportamento dipende dall'accesso Single Sign-On.

Nell'esempio seguente viene illustrato come avviene lo scambio di token. Il codice proviene dal file TokenExchangeSkillHandler.cs .

private async Task<bool> InterceptOAuthCards(ClaimsIdentity claimsIdentity, Activity activity)
{
    var oauthCardAttachment = activity.Attachments?.FirstOrDefault(a => a?.ContentType == OAuthCard.ContentType);
    if (oauthCardAttachment != null)
    {
        var targetSkill = GetCallingSkill(claimsIdentity);
        if (targetSkill != null)
        {
            var oauthCard = ((JObject)oauthCardAttachment.Content).ToObject<OAuthCard>();

            if (!string.IsNullOrWhiteSpace(oauthCard?.TokenExchangeResource?.Uri))
            {
                using (var context = new TurnContext(_adapter, activity))
                {
                    context.TurnState.Add<IIdentity>("BotIdentity", claimsIdentity);

                    // AAD token exchange
                    try
                    {
                        var result = await _tokenExchangeProvider.ExchangeTokenAsync(
                            context,
                            _connectionName,
                            activity.Recipient.Id,
                            new TokenExchangeRequest() { Uri = oauthCard.TokenExchangeResource.Uri }).ConfigureAwait(false);

                        if (!string.IsNullOrEmpty(result?.Token))
                        {
                            // If token above is null, then SSO has failed and hence we return false.
                            // If not, send an invoke to the skill with the token. 
                            return await SendTokenExchangeInvokeToSkill(activity, oauthCard.TokenExchangeResource.Id, result.Token, oauthCard.ConnectionName, targetSkill, default).ConfigureAwait(false);
                        }
                    }
                    catch
                    {
                        // Show oauth card if token exchange fails.
                        return false;
                    }

                    return false;
                }
            }
        }
    }
    return false;
}