Dodawanie logowania jednokrotnego do bota

Artykuł
10/27/2023

DOTYCZY: ZESTAW SDK w wersji 4

W tym artykule pokazano, jak używać funkcji logowania jednokrotnego w botze. W tym celu ta funkcja używa bota konsumenta , znanego również jako bot główny lub nadrzędny, do interakcji z umiejętnością lub botem podrzędnym. W tym artykule użyto terminów bot główny i bot umiejętności.

Jeśli dołączysz obsługę logowania jednokrotnego, użytkownik może zalogować się do bota głównego przy użyciu dostawcy tożsamości i nie będzie musiał zalogować się ponownie, gdy kontrola przejdzie do umiejętności.

Boty root i skill są oddzielnymi botami działającymi na potencjalnie różnych serwerach, z których każdy ma własną oddzielną pamięć i stan. Aby uzyskać więcej informacji na temat umiejętności, zobacz Omówienie umiejętności i Implementowanie umiejętności. Aby uzyskać więcej informacji na temat uwierzytelniania użytkowników, zobacz Podstawy uwierzytelniania platformy Bot Framework, Uwierzytelnianie użytkowników i Dodawanie uwierzytelniania do bota.

Ważne

W przypadku korzystania z uwierzytelniania usługi Azure AI Bot Service z czat internetowy należy pamiętać o ważnych kwestiach dotyczących zabezpieczeń. Aby uzyskać więcej informacji, zobacz sekcję zagadnienia dotyczące zabezpieczeń w artykule dotyczącym uwierzytelniania REST.

Wymagania wstępne

Znajomość podstaw bota, zarządzanie stanem i informacje o logowaniu jednokrotnym.
Znajomość biblioteki okien dialogowych i sposobu implementowania sekwencyjnego przepływu konwersacji i ponownego używania okien dialogowych
Znajomość programowania na platformie Azure i OAuth 2.0.
Program Visual Studio 2019 lub nowszy dla platformy .NET.
Logowanie jednokrotne z prostym użytkownikiem umiejętności i umiejętnościami w języku C#.

Informacje o przykładzie

W tym artykule odwołuje się dwa boty: RootBot i SkillBot. RootBot przekazuje działania do bota SkillBot. Modelują ten typowy scenariusz umiejętności:

Bot główny wywołuje co najmniej jednego bota umiejętności.
Zarówno boty główne, jak i boty umiejętności implementują podstawowe uwierzytelnianie opisane w artykule Dodawanie uwierzytelniania do bota .
Użytkownik loguje się do bota głównego.
Ze względu na logowanie jednokrotne i już zalogowano się do bota głównego, użytkownik jest zalogowany do bota umiejętności bez konieczności ponownej interakcji z użytkownikiem.

Aby zapoznać się z omówieniem sposobu obsługi uwierzytelniania przez platformę Bot Framework, zobacz Uwierzytelnianie użytkowników. Aby uzyskać informacje dotyczące logowania jednokrotnego, zobacz Logowanie jednokrotne.

RootBot obsługuje logowanie jednokrotne. Komunikuje się z botem SkillBot w imieniu użytkownika bez konieczności ponownego uwierzytelniania użytkownika w _SkillBot.

Dla każdego projektu w przykładzie potrzebne są następujące elementy:

Aplikacja Microsoft Entra ID do rejestrowania zasobu bota na platformie Azure.
Aplikacja dostawcy tożsamości Entra ID firmy Microsoft do uwierzytelniania.

Uwaga

Obecnie obsługiwany jest tylko dostawca tożsamości Entra ID firmy Microsoft.

Tworzenie zasobu usługi Azure RootBot

Utwórz zasób bota platformy Azure w witrynie Azure Portal dla elementu RootBot. Wykonaj kroki opisane w temacie Tworzenie zasobu bota platformy Azure.
Skopiuj i zapisz identyfikator aplikacji rejestracji bota oraz klucz tajny klienta.

Tworzenie tożsamości identyfikatora entra firmy Microsoft dla rootbota

Microsoft Entra ID to usługa tożsamości w chmurze, która umożliwia tworzenie aplikacji, które bezpiecznie logują użytkowników przy użyciu standardowych protokołów branżowych, takich jak OAuth2.0.

Utwórz aplikację tożsamości, która RootBot używa identyfikatora Entra firmy Microsoft do uwierzytelniania użytkownika. Wykonaj kroki opisane w temacie Tworzenie dostawcy tożsamości identyfikatora entra firmy Microsoft.
W okienku po lewej stronie wybierz pozycję Manifest.
Ustaw accessTokenAcceptedVersion wartość 2.
Wybierz pozycję Zapisz.
W okienku po lewej stronie wybierz pozycję Uwidaczniaj interfejs API.
W okienku po prawej stronie wybierz pozycję Dodaj zakres.
Po prawej stronie Dodaj zakres wybierz pozycję Zapisz i kontynuuj.
W wyświetlonym oknie w obszarze KtoTo może wyrazić zgodę?, wybierz pozycję Administracja i użytkowników.
Wprowadź pozostałe wymagane informacje.
Wybierz Dodaj zakres.
Skopiuj i zapisz wartość zakresu.

Tworzenie ustawienia połączenia OAuth dla rootbota

Utwórz połączenie Microsoft Entra ID w RootBot rejestracji bota i wprowadź wartości zgodnie z opisem w temacie Microsoft Entra ID i wartości opisanej poniżej.
Pozostaw pusty adres URL wymiany tokenów.
W polu Zakresy wprowadź wartość zakresu zapisaną RootBot w poprzednich krokach.

Uwaga

Zakresy zawierają adres URL, który użytkownik początkowo loguje się do bota głównego, podczas gdy adres URL wymiany tokenów jest pusty.

Załóżmy na przykład, że identyfikator appid bota głównego to rootAppId, a identyfikator appid bota umiejętności to skillAppId. Zakresy głównego bota będą wyglądać podobnie jak api://rootAppId/customScope, który jest używany do logowania użytkownika. Zakresy tego głównego bota są następnie wymieniane z api://skillAppId/customscope podczas logowania jednokrotnego.
Skopiuj i zapisz nazwę połączenia.

Tworzenie zasobu usługi Azure SkillBot

Utwórz zasób bota platformy Azure w witrynie Azure Portal dla elementu SkillBot. Wykonaj kroki opisane w temacie Tworzenie zasobu bota platformy Azure.
Skopiuj i zapisz identyfikator aplikacji rejestracji bota oraz klucz tajny klienta.

Tworzenie tożsamości identyfikatora entra firmy Microsoft dla usługi SkillBot

Utwórz aplikację tożsamości, która SkillBot używa identyfikatora Entra firmy Microsoft do uwierzytelniania bota. Wykonaj kroki opisane w temacie Tworzenie dostawcy tożsamości identyfikatora entra firmy Microsoft.
W okienku po lewej stronie wybierz pozycję Manifest.
Ustaw accessTokenAcceptedVersion wartość 2.
Wybierz pozycję Zapisz.
W okienku po lewej stronie wybierz pozycję Uwidaczniaj interfejs API.
W okienku po prawej stronie wybierz pozycję Dodaj zakres.
W prawej części Dodaj zakres wybierz pozycję Zapisz i kontynuuj.
W wyświetlonym oknie w obszarze KtoTo może wyrazić zgodę? wybierz pozycję Administracja i użytkowników.
Wprowadź pozostałe wymagane informacje.
Wybierz Dodaj zakres.
Skopiuj i zapisz wartość zakresu.
Wybierz Dodaj aplikację klienta. W prawej sekcji w polu Identyfikator klienta wprowadź wcześniej zapisany identyfikator aplikacji tożsamości RootBot. Upewnij się, że używasz tożsamości RootBot , a nie identyfikatora aplikacji rejestracji.

Uwaga

W przypadku aplikacji klienckich usługa Azure AI Bot Service nie obsługuje pojedynczego sing-on u dostawcy tożsamości Microsoft Entra ID B2C.
W obszarze Zakres autoryzowany zaznacz pole wyboru według wartości zakresu.
Wybierz Dodaj aplikację.
W okienku nawigacji po lewej stronie wybierz pozycję Uprawnienia interfejsu API. Najlepszym rozwiązaniem jest jawne ustawienie uprawnień interfejsu API dla aplikacji.
1. W okienku po prawej stronie wybierz pozycję Dodaj uprawnienie.
2. Wybierz pozycję Microsoft APIs (Interfejsy API firmy Microsoft), a następnie pozycję Microsoft Graph.
3. Wybierz pozycję Uprawnienia delegowane i upewnij się, że wybrano wymagane uprawnienia. Ten przykład wymaga uprawnień wymienionych poniżej.
  
  Uwaga
  
  Każde uprawnienie oznaczone jako WYMAGANA ZGODA ADMINISTRATORA będzie wymagać logowania zarówno użytkownika, jak i administratora dzierżawy.
  - Openid
  - Profil
  - User.Read
  - User.ReadBasic.All
4. Wybierz Przyznaj uprawnienia.

Tworzenie ustawienia połączenia OAuth dla usługi SkillBot

Utwórz połączenie Microsoft Entra ID w SkillBot rejestracji bota i wprowadź wartości zgodnie z opisem w temacie Microsoft Entra ID i wartości opisane poniżej.
W polu Adres URL wymiany tokenów wprowadź wartość zakresu zapisaną SkillBot w poprzednich krokach.
W polu Zakresy wprowadź następujące wartości rozdzielone spacją: profileUser.ReadBasic.AllUser.Readopenid.
Skopiuj i zapisz w pliku nazwę połączenia.

Testowanie połączenia

Wybierz wpis połączenia, aby otworzyć utworzone połączenie.
Wybierz pozycję Test Połączenie ion w górnej części okienka Ustawienia Połączenie dostawcy usług.
Po raz pierwszy powinno to otworzyć nową kartę przeglądarki z listą uprawnień, które aplikacja żąda i wyświetli monit o zaakceptowanie.
Wybierz pozycję Zaakceptuj.
Spowoduje to przekierowanie do strony Test Połączenie ion na <stronie Powodzenie połączenia>.

Aby uzyskać więcej informacji, zobacz Omówienie usługi Microsoft Entra ID dla deweloperów (wersja 1.0) i Platforma tożsamości Microsoft (wersja 2.0). Aby uzyskać informacje o różnicach między punktami końcowymi w wersji 1 i 2, zobacz Dlaczego warto zaktualizować Platforma tożsamości Microsoft (wersja 2.0)?. Aby uzyskać pełne informacje, zobacz Platforma tożsamości Microsoft (dawniej Microsoft Entra ID dla deweloperów).

Przygotowywanie kodu przykładów

Należy zaktualizować appsettings.json plik w obu przykładach, jak opisano poniżej.

Sklonuj przykład logowania jednokrotnego z prostym użytkownikiem umiejętności i umiejętnością z repozytorium GitHub.

SkillBot Otwórz plik projektuappsettings.json. Przypisz następujące wartości z zapisanego pliku:

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

RootBot Otwórz plik projektuappsettings.json. Przypisz następujące wartości z zapisanego pliku:

{
    "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"
            }
        ]
}

Testowanie przykładów

Użyj następujących elementów do testowania:

RootBot Polecenia
- login umożliwia użytkownikowi zalogowanie się do rejestracji identyfikatora Entra firmy Microsoft przy użyciu elementu RootBot. Po zalogowaniu logowanie jednokrotne zajmuje się również logowaniem SkillBot . Użytkownik nie musi się ponownie zalogować.
- token wyświetla token użytkownika.
- logout rejestruje użytkownika poza elementem RootBot.
SkillBot Polecenia
- skill login umożliwia zalogowanie RootBot się do SkillBotobiektu w imieniu użytkownika. Użytkownik nie jest wyświetlany na karcie logowania, jeśli jest już zalogowany, chyba że logowanie jednokrotne nie powiedzie się.
- skill tokenwyświetla token użytkownika z .SkillBot
- skill logout rejestruje użytkownika poza SkillBot

Uwaga

Po pierwszym wypróbowaniu logowania jednokrotnego podczas próby logowania jednokrotnego mogą zostać wyświetlone karty OAuth, aby się zalogować. Dzieje się tak, ponieważ nie udzieliły jeszcze zgody na aplikację Microsoft Entra ID. Aby tego uniknąć, mogą udzielić zgody administratora na wszelkie uprawnienia grafu żądane przez aplikację Microsoft Entra ID.

Emulator
czat internetowy

Jeśli jeszcze tego nie zrobiono, zainstaluj program Bot Framework Emulator. Zobacz też Debugowanie za pomocą emulatora.

Aby przykładowe logowanie bota działało, należy skonfigurować emulator. Wykonaj poniższe kroki: jak pokazano w temacie Konfigurowanie emulatora na potrzeby uwierzytelniania.

Po skonfigurowaniu mechanizmu uwierzytelniania można przeprowadzić rzeczywiste testowanie przykładowe bota.

W programie Visual Studio otwórz SSOWithSkills.sln rozwiązanie i skonfiguruj je, aby rozpocząć debugowanie przy użyciu wielu procesów.
Rozpocznij debugowanie lokalnie na maszynie. Zwróć uwagę, że wRootBot pliku projektu appsettings.json są następujące ustawienia:
```
"SkillHostEndpoint": "http://localhost:3978/api/skills/"
"SkillEndpoint": "http://localhost:39783/api/messages"
```
Uwaga

Te ustawienia oznaczają, że zarówno na RootBot maszynie lokalnej, jak i SkillBot są uruchomione. Emulator komunikuje się z RootBot portem 3978 i RootBot komunikuje się z portem SkillBot 39783. Po rozpoczęciu debugowania otwórz dwa domyślne okna przeglądarki. Jeden na porcie 3978 i drugi na porcie 39783.
Uruchom emulator.
Po nawiązaniu połączenia z botem wprowadź RootBot identyfikator aplikacji rejestracji i hasło.
Wpisz hi , aby rozpocząć konwersację.
Wprowadź nazwę logowania. Zostanie wyświetlona RootBotkarta uwierzytelniania Logowania do usługi AAD .
Wybierz pozycję Zaloguj. Zostanie wyświetlone wyskakujące okno dialogowe Potwierdzanie otwartego adresu URL .
Wybierz pozycję Potwierdź. Nastąpi zalogowanie i RootBot zostanie wyświetlony token.
Wprowadź token , aby ponownie wyświetlić token.

Teraz możesz przystąpić do komunikowania się z programem SkillBot. Po zalogowaniu przy użyciu elementu RootBotnie musisz ponownie podawać poświadczeń, dopóki się nie wylogujesz. Pokazuje to, że logowanie jednokrotne działa.
Wprowadź nazwę logowania umiejętności w polu Emulator. Nie zostanie wyświetlony monit o ponowne zalogowanie się. Zamiast tego zostanie wyświetlony token SkillBot.
Wprowadź token umiejętności, aby ponownie wyświetlić token.
Teraz możesz wprowadzić wylogowywanie umiejętności, aby wylogować się z .SkillBot Następnie wprowadź wylogowywanie się, aby wylogować się z pliku SimpleRootBoot.

Wdróż bota głównego i bota umiejętności na platformie Azure. Aby uzyskać więcej informacji, zobacz Samouczek: aprowizuj bota na platformie Azure i Samouczek: publikowanie podstawowego bota.
W edytorze kodu, na przykład w programie Visual Studio, zastąp adresy localhost w RootBot pliku projektu appsetting.js rzeczywistym identyfikatorem Microsoft Entra IDdresses, jak pokazano poniżej.
```
"SkillHostEndpoint": "https://<your root bot deployed name>.azurewebsites.net/api/skills"
"SkillEndpoint": "https://<your skill bot deployed name>.azurewebsites.net/api/messages"
```
W przeglądarce przejdź do witryny Azure Portal.
Otwórz rejestrację bota głównego. W okienku po lewej stronie wybierz pozycję Testuj w czat internetowy. Okno dialogowe z botem głównym jest wyświetlane z komunikatem powitania bota.
Rozpocznij konwersację z botem, wprowadzając na przykład hi . Bot będzie powtarzać wiadomość z powrotem.
Wprowadź nazwę logowania. Zostanie wyświetlona RootBotkarta uwierzytelniania Logowania do usługi AAD .
Wybierz pozycję Zaloguj. Zostanie wyświetlona strona internetowa z kodem weryfikacji.
Aby zakończyć logowanie, skopiuj kod i wprowadź go w polu wejściowym. Zostanie RootBot wyświetlony token.
Wprowadź token , aby ponownie wyświetlić token.

Teraz możesz przystąpić do komunikowania się z programem SkillBot. Po zalogowaniu się w usłudze RootBotnie musisz ponownie podawać poświadczeń, dopóki się nie wylogujesz. Pokazuje to, że logowanie jednokrotne działa.
Wprowadź identyfikator logowania umiejętności. Zostanie wyświetlony token SkillBot.
Wprowadź token umiejętności, aby ponownie wyświetlić token. Informuje to, że komunikujesz się z elementem bez konieczności ponownego SkillBot logowania. Logowanie jednokrotne w akcji!
Teraz możesz wprowadzić wylogowywanie umiejętności, aby wylogować się z .SkillBot Następnie wprowadź wylogowywanie się, aby wylogować się z pliku SimpleRootBoot.

Dodatkowe informacje

Poniższy diagram sekwencji czasowej dotyczy przykładów używanych w artykule i pokazuje interakcję między różnymi składnikami. ABS to skrót od azure AI Bot Service.

Sequence diagram illustrating the skill token flow.

Po raz pierwszy użytkownik wprowadza login polecenie rootbota.
RootBot wysyła kartę OAuthCard z prośbą o zalogowanie się użytkownika.
Użytkownik wprowadza poświadczenia uwierzytelniania wysyłane do usługi ABS (Azure AI Bot Service).
Abs wysyła token uwierzytelniania wygenerowany na podstawie poświadczeń użytkownika do rootbota.
RootBot wyświetla token główny, który ma być widoczny dla użytkownika.
Użytkownik wprowadza skill login polecenie dla bota SkillBot.
Bot SkillBot wysyła kartę OAuthCard do rootbota.
RootBot prosi o wymianę tokenu z ABS.
Logowanie jednokrotne wysyła token umiejętności SkillBot do rootbota.
RootBot wyświetla token umiejętności, który ma być widoczny dla użytkownika. Zwróć uwagę, że token umiejętności został wygenerowany bez konieczności logowania się do bota SKillBot. Jest to spowodowane logowaniem jednokrotnym.

W poniższym przykładzie pokazano, jak odbywa się wymiana tokenów. Kod pochodzi z pliku 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;
}