Dodawanie uwierzytelniania do bota

  • Artykuł

DOTYCZY: ZESTAW SDK w wersji 4

Zestaw SDK usługi Azure AI Bot Service w wersji 4 ułatwia opracowywanie botów, które mogą uzyskiwać dostęp do zasobów online wymagających uwierzytelniania użytkowników. Bot nie musi zarządzać tokenami uwierzytelniania, ponieważ platforma Azure wykonuje je za pomocą protokołu OAuth 2.0 w celu wygenerowania tokenu na podstawie poświadczeń każdego użytkownika. Bot używa tokenu wygenerowanego przez platformę Azure do uzyskiwania dostępu do tych zasobów. W ten sposób użytkownik nie musi podać identyfikatora i hasła do bota, aby uzyskać dostęp do zabezpieczonego zasobu, ale tylko do zaufanego dostawcy tożsamości.

Aby zapoznać się z omówieniem sposobu obsługi tego rodzaju uwierzytelniania przez platformę Bot Framework, zobacz Uwierzytelnianie użytkowników.

Ten artykuł odwołuje się do dwóch przykładów. Pokazano, jak uzyskać token uwierzytelniania. Drugi jest bardziej złożony i pokazuje, jak uzyskać dostęp do programu Microsoft Graph w imieniu użytkownika. W obu przypadkach możesz użyć usługi Azure AD w wersji 1 lub 2 jako dostawcy tożsamości, aby uzyskać token OAuth dla bota. W tym artykule opisano, jak:

  • Tworzenie zasobu usługi Azure Bot
  • Tworzenie dostawcy tożsamości Entra ID firmy Microsoft
  • Rejestrowanie dostawcy tożsamości entra firmy Microsoft za pomocą bota
  • Przygotowywanie kodu bota

Po zakończeniu tego artykułu będziesz mieć bota, który może odpowiedzieć na kilka prostych zadań. W przykładzie programu Microsoft Graph możesz wysłać wiadomość e-mail, wyświetlić, kim jesteś, i sprawdzić ostatnie wiadomości e-mail. Nie musisz publikować bota, aby przetestować funkcje protokołu OAuth; bot będzie jednak potrzebować prawidłowego identyfikatora i hasła aplikacji platformy Azure.

Uwaga

Zestawy SDK języka JavaScript, C# i Python platformy Bot Framework będą nadal obsługiwane, jednak zestaw SDK języka Java jest wycofywany z ostatecznym długoterminowym wsparciem kończącym się w listopadzie 2023 r. Zostaną podjęte tylko krytyczne poprawki zabezpieczeń i usterek w tym repozytorium.

Istniejące boty utworzone za pomocą zestawu JAVA SDK będą nadal działać.

W przypadku tworzenia nowego bota rozważ użycie agentów usługi Power Virtual Agents i przeczytaj o wyborze odpowiedniego rozwiązania czatbota.

Aby uzyskać więcej informacji, zobacz Przyszłość tworzenia botów.

zagadnienia dotyczące czat internetowy i linii bezpośredniej

Ważne

Należy użyć funkcji Direct Line z włączonym rozszerzonym uwierzytelnianiem, aby ograniczyć zagrożenia bezpieczeństwa podczas nawiązywania połączenia z botem przy użyciu kontroli czat internetowy. Aby uzyskać więcej informacji, zobacz Uwierzytelnianie rozszerzone direct line.

Wymagania wstępne

  • Znajomość podstaw bota, zarządzania stanem, biblioteki okien dialogowych i sposobu implementowania sekwencyjnego przepływu konwersacji oraz sposobu ponownego używania okien dialogowych.

  • Znajomość programowania na platformie Azure i OAuth 2.0.

  • Program Visual Studio 2017 lub nowszy dla platformy .NET.

  • Node.js dla języka JavaScript.

  • Język Python w wersji 3.8 lub nowszej dla języka Python.

  • Jeden z przykładów wymienionych poniżej.

    Przykład Wersja botBuilder Demonstracje
    Uwierzytelnianie w języku C# lub JavaScript, Java lub Python Wersja 4 Obsługa protokołu OAuthCard
    Uwierzytelnianie dla programu Microsoft Graph w języku C# lub JavaScript, Java lub Python Wersja 4 Obsługa interfejsu API programu Microsoft Graph przy użyciu protokołu OAuth 2.0
    Uwierzytelnianie dla usługi Microsoft Teams w języku C# lub JavaScript, Java lub Python Wersja 4 Obsługa interfejsu API programu Microsoft Graph przy użyciu protokołu OAuth 2.0

    Aby uruchomić przykłady, o których mowa w tym artykule, potrzebne są następujące elementy:

    • Aplikacja Microsoft Entra ID, za pomocą której można zarejestrować zasób bota na platformie Azure. Ta aplikacja umożliwia botowi dostęp do zewnętrznego zabezpieczonego zasobu, takiego jak Microsoft Graph. Umożliwia również użytkownikowi komunikowanie się z botem za pośrednictwem kilku kanałów, takich jak czat internetowy.
    • Oddzielna aplikacja Microsoft Entra ID, która będzie działać jako dostawca tożsamości. Ta aplikacja udostępnia poświadczenia wymagane do nawiązania połączenia OAuth między botem a zabezpieczonym zasobem. Zwróć uwagę, że ten artykuł używa usługi Active Directory jako dostawcy tożsamości. Wielu innych dostawców jest również obsługiwanych.

Ważne

Za każdym razem, gdy zarejestrujesz bota na platformie Azure, zostanie przypisana aplikacja Microsoft Entra ID. Jednak ta aplikacja zabezpiecza dostęp typu channel-to-bot. Potrzebujesz dodatkowej aplikacji Microsoft Entra ID dla każdego zewnętrznego zabezpieczonego zasobu, do którego bot ma uzyskać dostęp w imieniu użytkownika.

Tworzenie zasobu

Utwórz zasób usługi Azure Bot, który umożliwi zarejestrowanie bota w usłudze Azure AI Bot Service.

Napiwek

Nie można utworzyć nowych zasobów rejestracji bota aplikacji internetowej i kanałów bota, jednak wszystkie takie zasoby, które są skonfigurowane i wdrożone, będą nadal działać. Boty utworzone na podstawie szablonu VSIX lub Yeoman z zestawu SDK w wersji 4.14.1.2 lub nowszej zawierają szablony usługi ARM, które wygenerują zasób usługi Azure Bot.

  1. Przejdź do portalu Azure Portal.

  2. W okienku po prawej stronie wybierz pozycję Utwórz zasób.

  3. W polu wyszukiwania wprowadź ciąg bot, a następnie naciśnij klawisz Enter.

  4. Wybierz kartę Azure Bot .

    Select Azure bot resource

  5. Wybierz pozycję Utwórz.

  6. Wprowadź wartości w wymaganych polach i przejrzyj i zaktualizuj ustawienia.

    1. Podaj informacje w obszarze Szczegóły projektu. Wybierz, czy bot będzie miał globalną, czy lokalną rezydencję danych. Obecnie funkcja lokalnego przechowywania danych jest dostępna dla zasobów w regionie "westeurope" i "centralindia". Aby uzyskać więcej informacji, zobacz Regionalizacja w usłudze Azure AI Bot Service.

      The project details settings for an Azure Bot resource

    2. Podaj informacje w obszarze Identyfikator aplikacji microsoft. Wybierz sposób zarządzania tożsamością bota na platformie Azure i określ, czy chcesz utworzyć nową tożsamość, czy użyć istniejącej.

      The Microsoft app ID settings for an Azure Bot resource

  7. Wybierz pozycję Przejrzyj i utwórz.

  8. Jeśli walidacja zakończy się pomyślnie, wybierz pozycję Utwórz.

  9. Po zakończeniu wdrażania wybierz pozycję Przejdź do zasobu. Powinien zostać wyświetlony bot i powiązane zasoby wymienione w wybranej grupie zasobów.

  10. Jeśli nie masz jeszcze zestawu SDK platformy Bot Framework, wybierz pozycję Pobierz z usługi GitHub , aby dowiedzieć się, jak korzystać z pakietów dla preferowanego języka.

    Create bot in SDK

Teraz możesz przystąpić do kompilowania bota przy użyciu zestawu Sdk platformy Bot Framework.

Napiwek

Gdy platforma Azure tworzy nowy zasób usługi Azure Bot z jedną dzierżawą lub wieloma dzierżawami z nowym identyfikatorem aplikacji, generuje również hasło.

Informacje o tożsamości bota

Wykonaj następujące kroki, aby dodać informacje o tożsamości do pliku konfiguracji bota. Plik różni się w zależności od języka programowania używanego do utworzenia bota.

Ważne

Wersje języka Java i Python zestawu Bot Framework SDK obsługują tylko boty wielodostępne. Wersje języków C# i JavaScript obsługują wszystkie trzy typy aplikacji do zarządzania tożsamością bota.

Język Nazwa pliku Uwagi
C# appsettings.json Obsługuje wszystkie trzy typy aplikacji do zarządzania tożsamością bota.
JavaScript .Env Obsługuje wszystkie trzy typy aplikacji do zarządzania tożsamością bota.
Java application.properties Obsługuje tylko boty z wieloma dzierżawami.
Python config.py Obsługuje tylko boty z wieloma dzierżawami. Podaj właściwości tożsamości jako argumenty wywołań os.environ.get metody.

Informacje o tożsamości, które należy dodać, zależą od typu aplikacji bota. Podaj następujące wartości w pliku konfiguracji.

Dostępne tylko dla botów języka C# i JavaScript.

Właściwości Wartość
MicrosoftAppType UserAssignedMSI
MicrosoftAppId Identyfikator klienta tożsamości zarządzanej przypisanej przez użytkownika.
MicrosoftAppPassword Nie dotyczy. Pozostaw to pole puste dla bota tożsamości zarządzanej przypisanej przez użytkownika.
MicrosoftAppTenantId Identyfikator dzierżawy tożsamości zarządzanej przypisanej przez użytkownika.

Aby zaktualizować usługę App Service

Jeśli masz istniejący zasób usługi App Service (aplikację internetową) dla bota, a bot jest aplikacją tożsamości zarządzanej przypisanej przez użytkownika, może być konieczne zaktualizowanie usługi aplikacji bota:

  1. Przejdź do bloku App Service dla aplikacji internetowej bota.
  2. W obszarze Ustawienia wybierz pozycję Tożsamość.
  3. W bloku Tożsamość wybierz kartę Przypisane przez użytkownika i Dodaj (+).
  4. W bloku Dodawanie tożsamości zarządzanej przypisanej przez użytkownika:

    1. Wybierz subskrypcję.

    2. W obszarze Tożsamości zarządzane przypisane przez użytkownika wybierz tożsamość zarządzaną bota. Jeśli tożsamość zarządzana została wygenerowana automatycznie, będzie miała taką samą nazwę jak bot.

    3. Wybierz pozycję Dodaj , aby użyć tej tożsamości dla bota.

      The App Service Identity blade with the managed identity for the bot selected.

Aby uzyskać identyfikator aplikacji lub dzierżawy

Aby uzyskać identyfikator aplikacji lub dzierżawy bota:

  1. Przejdź do bloku zasobów usługi Azure Bot dla bota.
  2. Przejdź do bloku Konfiguracja bota. W tym bloku możesz skopiować identyfikator aplikacji firmy Microsoft lub identyfikator dzierżawy aplikacji bota.

Aby wygenerować nowe hasło

Boty z jedną dzierżawą i wieloma dzierżawami mają klucz tajny aplikacji lub hasło potrzebne do niektórych operacji. Usługa Azure AI Bot Service ukrywa wpis tajny bota. Jednak właściciel zasobu usługi App Service bota może wygenerować nowe hasło:

  1. Przejdź do bloku zasobów usługi Azure Bot dla bota.
  2. Przejdź do bloku Konfiguracja bota.
  3. Wybierz pozycję Zarządzaj obok pozycji Identyfikator aplikacji firmy Microsoft, aby przejść do bloku Certyfikaty i wpisy tajne dla usługi App Service.
  4. Postępuj zgodnie z instrukcjami w bloku, aby utworzyć nowy klucz tajny klienta i zarejestrować wartość w bezpiecznym miejscu.

Usługa tożsamości identyfikatora entra firmy Microsoft

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 OAuth 2.0.

Możesz użyć jednej z tych dwóch usług tożsamości:

  1. Platforma dewelopera Microsoft Entra ID (wersja 1.0). Znany również jako punkt końcowy usługi Azure AD w wersji 1 , który umożliwia tworzenie aplikacji, które bezpiecznie logują użytkowników przy użyciu konta służbowego firmy Microsoft. Aby uzyskać więcej informacji, zobacz Omówienie identyfikatora Entra firmy Microsoft dla deweloperów (wersja 1.0).
  2. Platforma tożsamości Microsoft (wersja 2.0). Znany również jako punkt końcowy microsoft Entra ID , który jest ewolucją platformy Azure AD (wersja 1.0). Umożliwia tworzenie aplikacji logujących się do wszystkich dostawców tożsamości firmy Microsoft i uzyskiwanie tokenów w celu wywoływania interfejsów API firmy Microsoft, takich jak Microsoft Graph, lub innych interfejsów API utworzonych przez deweloperów. Aby uzyskać więcej informacji, zobacz omówienie 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).

Tworzenie dostawcy tożsamości Entra ID firmy Microsoft

W tej sekcji pokazano, jak utworzyć dostawcę tożsamości entra firmy Microsoft, który używa protokołu OAuth 2.0 do uwierzytelniania bota. Możesz użyć punktów końcowych usługi Azure AD w wersji 1 lub Microsoft Entra ID.

Napiwek

Musisz utworzyć i zarejestrować aplikację Microsoft Entra ID w dzierżawie, w której możesz wyrazić zgodę na delegowanie uprawnień żądanych przez aplikację.

  1. Otwórz panel Microsoft Entra ID w witrynie Azure Portal. Jeśli nie jesteś w odpowiedniej dzierżawie, wybierz pozycję Przełącz katalog , aby przełączyć się do odpowiedniej dzierżawy. (Aby uzyskać informacje na temat tworzenia dzierżawy, zobacz Uzyskaj dostęp do portalu i utwórz dzierżawę).

  2. Otwórz panel Rejestracje aplikacji.

  3. W panelu Rejestracje aplikacji wybierz pozycję Nowa rejestracja.

  4. Wypełnij wymagane pola i utwórz rejestrację aplikacji.

    1. Nadaj nazwę aplikacji.

    2. Wybierz obsługiwane typy kont dla aplikacji. (Każda z tych opcji będzie działać z tym przykładem).

    3. W polu Identyfikator URI przekierowania wybierz pozycję Sieć Web i ustaw adres URL na jeden z obsługiwanych adresów URL przekierowania OAuth.

    4. Wybierz pozycję Zarejestruj.

      • Po utworzeniu platforma Azure wyświetli stronę Przegląd aplikacji.
      • Zapisz wartość identyfikatora aplikacji (klienta). Ta wartość zostanie użyta później jako identyfikator klienta podczas tworzenia parametry połączenia i zarejestrowania dostawcy identyfikatora Entra firmy Microsoft przy użyciu rejestracji bota.
      • Zapisz wartość identyfikatora katalogu (dzierżawy). Użyjesz tej wartości, aby zarejestrować tę aplikację dostawcy za pomocą bota.

  5. W okienku nawigacji wybierz pozycję Certyfikaty i wpisy tajne , aby utworzyć wpis tajny dla aplikacji.

    1. W obszarze Wpisy tajne klienta wybierz pozycję Nowy klucz tajny klienta.
    2. Dodaj opis, aby zidentyfikować ten wpis tajny od innych osób, które mogą być konieczne do utworzenia dla tej aplikacji, na przykład bot login.
    3. W obszarze Wygasa wybierz czas wygaśnięcia wpisu tajnego.
    4. Wybierz Dodaj.
    5. Przed opuszczeniem certyfikatów i wpisów tajnych zapisz wpis tajny. Ta wartość będzie używana później jako klucz tajny klienta podczas rejestrowania aplikacji Microsoft Entra ID za pomocą bota.

  6. W okienku nawigacji wybierz pozycję Uprawnienia interfejsu API, aby otworzyć panel uprawnień interfejsu API. Najlepszym rozwiązaniem jest jawne ustawienie uprawnień interfejsu API dla aplikacji.

    1. Wybierz pozycję Dodaj uprawnienie , aby wyświetlić okienko Uprawnienia interfejsu API żądania.

    2. W tym przykładzie wybierz pozycję Interfejsy API firmy Microsoft i program Microsoft Graph.

    3. Wybierz pozycję Uprawnienia delegowane i upewnij się, że wybrano wymagane uprawnienia. Ten przykład wymaga tych uprawnień.

      Uwaga

      Każde uprawnienie oznaczone jako WYMAGANA ZGODA ADMINISTRATORA będzie wymagać zarówno użytkownika, jak i administratora dzierżawy do zalogowania się, więc w przypadku bota zwykle pozostają z dala od nich.

      • Openid
      • Profil
      • Mail.Read
      • Mail.Send
      • User.Read
      • User.ReadBasic.All

    4. Wybierz Przyznaj uprawnienia. (Gdy użytkownik po raz pierwszy uzyskuje dostęp do tej aplikacji za pośrednictwem bota, musi udzielić zgody).

Masz teraz skonfigurowaną aplikację Microsoft Entra ID.

Uwaga

Przypiszesz identyfikator aplikacji (klienta) i klucz tajny klienta podczas tworzenia parametry połączenia i zarejestrujesz dostawcę tożsamości przy użyciu rejestracji bota. Zobacz następną sekcję.

Rejestrowanie dostawcy tożsamości entra firmy Microsoft za pomocą bota

Następnym krokiem jest zarejestrowanie dostawcy tożsamości za pomocą bota.

  1. Otwórz stronę zasobu bota usługi Azure Bot w witrynie Azure Portal.

  2. Wybierz Ustawienia.

  3. W obszarze OAuth Połączenie ion Ustawienia w dolnej części strony wybierz pozycję Dodaj ustawienie.

  4. Wypełnij formularz w następujący sposób:

    1. Name. Wprowadź nazwę połączenia. Użyjesz go w kodzie bota.

    2. Dostawca usług. Wybierz pozycję Microsoft Entra ID , aby wyświetlić pola specyficzne dla identyfikatora firmy Microsoft.

    3. Identyfikator klienta. Wprowadź identyfikator aplikacji (klienta) zarejestrowany dla dostawcy tożsamości Microsoft Entra ID.

    4. Klucz tajny klienta. Wprowadź wpis tajny zarejestrowany dla dostawcy tożsamości entra firmy Microsoft.

      Napiwek

      Jeśli chcesz używać certyfikatów, możesz wybrać dostawcę usługi AAD w wersji 2 z certyfikatami . Musisz przyznać magazyn tokenów usługi Bot Service (appid: 5b404cf4-a79d-4cfe-b866-24bf8e1a4921) uprawnienie do uzyskania certyfikatu.

    5. Adres URL wymiany tokenów. Pozostaw to pole puste, ponieważ jest ono używane tylko do logowania jednokrotnego w usłudze Microsoft Entra ID.

    6. Identyfikator dzierżawy. Wprowadź identyfikator katalogu (dzierżawy) zarejestrowany wcześniej dla aplikacji Microsoft Entra ID lub typową w zależności od obsługiwanych typów kont wybranych podczas tworzenia aplikacji usługi Azure DD. Aby zdecydować, która wartość ma zostać przypisana, wykonaj następujące kryteria:

      • Jeśli podczas tworzenia aplikacji Microsoft Entra ID wybrano pozycję Konta tylko w tym katalogu organizacyjnym (tylko firma Microsoft — pojedyncza dzierżawa), wprowadź wcześniej zarejestrowany identyfikator dzierżawy dla aplikacji Microsoft Entra ID.
      • Jeśli jednak wybrano pozycję Konta w dowolnym katalogu organizacyjnym (Dowolny katalog Microsoft Entra ID — wielodostępne i osobiste konta Microsoft, np. Xbox, Outlook.com) lub Konta w dowolnym katalogu organizacyjnym (katalog Microsoft Entra ID — wiele dzierżaw), wprowadź common zamiast identyfikatora dzierżawy. W przeciwnym razie aplikacja Microsoft Entra ID zweryfikuje się za pośrednictwem dzierżawy, której identyfikator został wybrany i wykluczy osobiste konta Microsoft.

      Będzie to dzierżawa skojarzona z użytkownikami, którzy mogą być uwierzytelniani. Aby uzyskać więcej informacji, zobacz Dzierżawa w usłudze Microsoft Entra ID.

    7. W polu Zakresy wprowadź nazwy uprawnień wybranego w ramach rejestracji aplikacji. W celach testowych możesz po prostu wprowadzić: openid profile.

      Uwaga

      W przypadku identyfikatora Entra firmy Microsoft pole Zakresy uwzględnia wielkość liter, rozdziela spacją listę wartości.

  5. Wybierz pozycję Zapisz.

Uwaga

Te wartości umożliwiają aplikacji uzyskiwanie dostępu do danych usługi Office 365 za pośrednictwem interfejsu API programu Microsoft Graph. Ponadto adres URL wymiany tokenów powinien być pusty, ponieważ jest on używany tylko do logowania jednokrotnego w usłudze Microsoft Entra ID.

Testowanie połączenia

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

Teraz możesz użyć tej nazwy połączenia w kodzie bota, aby pobrać tokeny użytkownika.

Przygotowywanie kodu bota

Aby ukończyć ten proces, musisz mieć identyfikator aplikacji i hasło bota.

  1. Sklonuj z repozytorium GitHub przykład, z którym chcesz pracować: uwierzytelnianie bota lub uwierzytelnianie bota dla programu Microsoft Graph.

  2. Zaktualizuj plik appsettings.json:

    • Ustaw ConnectionName nazwę ustawienia połączenia OAuth dodanego do bota.

    • Ustaw MicrosoftAppId identyfikator MicrosoftAppPassword aplikacji i wpis tajny aplikacji bota.

      W zależności od znaków w kluczu tajnym bota może być konieczne uniknienie hasła przez kod XML. Na przykład wszystkie ampersandy (&) muszą być zakodowane jako &amp;.

    {
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "MicrosoftAppTenantId": "",
  "ConnectionName": ""
}

    Aby używać protokołu OAuth w botze z miejscem przechowywania danych w chmurze publicznej, należy dodać następujące konfiguracje w swoich ustawieniach aplikacji

    "OAuthUrl": "<Regional-OAuth-Uri>",
"ToChannelFromBotOAuthScope": "https://api.botframework.com",
"ToChannelFromBotLoginUrlTemplate": "https://api.botframework.com",
"PublicAzureChannel": "https://api.botframework.com",
"ToBotFromChannelOpenIdMetadataUrl": "https://login.botframework.com/v1/.well-known/openidconfiguration",
"ToBotFromEmulatorOpenIdMetadataUrl": "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
"ToBotFromChannelTokenIssuer": "https://api.botframework.com",
"ToChannelFromBotLoginUrl": "https://login.microsoftonline.com/botframework.com",

    Gdzie <Regional-OAuth-Url> jest jednym z następujących identyfikatorów URI:

    Identyfikator URI opis
    https://europe.api.botframework.com W przypadku botów chmury publicznej z miejscem przechowywania danych w Europie.
    https://unitedstates.api.botframework.com W przypadku botów chmury publicznej z miejscem przechowywania danych w Stany Zjednoczone.
    https://india.api.botframework.com W przypadku botów chmury publicznej z miejscem przechowywania danych w Indiach.

  3. Aktualizuj plik Startup.cs:

    Aby korzystać z protokołu OAuth w chmurach platformy Azure innych niż publiczne, podobnie jak w chmurze dla instytucji rządowych, należy dodać następujący kod w pliku Startup.cs .

    string uri = "<uri-to-use>";
MicrosoftAppCredentials.TrustServiceUrl(uri);
OAuthClientConfig.OAuthEndpoint = uri;

    Gdzie <identyfikator URI-to-use> jest jednym z następujących identyfikatorów URI:

    Identyfikator URI opis
    https://api.botframework.azure.us W przypadku Stany Zjednoczone botów chmury dla instytucji rządowych bez rezydencji danych.
    https://api.botframework.com W przypadku botów chmury publicznej bez przechowywania danych. Jest to domyślny identyfikator URI i nie wymaga zmiany pliku Startup.cs.

Aby uzyskać wartości identyfikatora aplikacji firmy Microsoft i hasła aplikacji firmy Microsoft, zobacz Uzyskiwanie hasła rejestracji.

Uwaga

Teraz możesz opublikować ten kod bota w subskrypcji platformy Azure (wybierz prawym przyciskiem myszy projekt i wybierz polecenie Publikuj), ale nie jest to konieczne w tym artykule. Należy skonfigurować konfigurację publikowania, która używa aplikacji i planu hostingu używanego podczas konfigurowania bota w witrynie Azure Portal.

Testowanie bota przy użyciu emulatora

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, jak pokazano w temacie Konfigurowanie emulatora na potrzeby uwierzytelniania.

Testowanie

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

Uwaga

Może zostać wyświetlony monit o wprowadzenie kodu magicznego, ponieważ sposób implementacji przykładu bota. Ten kod magiczny jest częścią RFC#7636 i jest tam, aby dodać dodatkowy element zabezpieczeń. Usunięcie kodu magicznego zwiększa ryzyko bezpieczeństwa. Można temu zapobiec przy użyciu funkcji Direct Line z włączonym rozszerzonym uwierzytelnianiem. Aby uzyskać więcej informacji, zobacz Bot Framework enhanced authentication (Ulepszone uwierzytelnianie w usłudze Bot Framework).

  1. Uruchom przykład bota lokalnie na maszynie.
  2. Uruchom emulator.
  3. Podczas nawiązywania połączenia z botem musisz podać identyfikator aplikacji i hasło bota.
    • Otrzymasz identyfikator aplikacji i hasło z rejestracji aplikacji platformy Azure. Są to te same wartości przypisane do aplikacji bota w appsettings.json pliku lub .env . W emulatorze przypiszesz te wartości w pliku konfiguracji lub po raz pierwszy połączysz się z botem.
    • Jeśli konieczne jest ucieczka kodu XML hasła w kodzie bota, należy to zrobić również tutaj.
  4. Wpisz help , aby wyświetlić listę dostępnych poleceń bota i przetestować funkcje uwierzytelniania.
  5. Po zalogowaniu nie musisz ponownie podawać poświadczeń, dopóki się nie wylogujesz.
  6. Aby się wylogować i anulować uwierzytelnianie, wpisz logout.

Uwaga

Uwierzytelnianie bota wymaga użycia usługi bota Połączenie or. Usługa uzyskuje dostęp do informacji z zasobu usługi Azure Bot.

Przykład uwierzytelniania

W przykładzie uwierzytelniania bota okno dialogowe jest przeznaczone do pobierania tokenu użytkownika po zalogowaniu użytkownika.

Sample conversation with the authentication sample bot.

Przykład uwierzytelniania dla programu Microsoft Graph

W przykładzie uwierzytelniania bota dla programu Microsoft Graph okno dialogowe jest przeznaczone do akceptowania ograniczonego zestawu poleceń po zalogowaniu użytkownika.

Sample conversation with the Microsoft Graph authentication sample bot.

Dodatkowe informacje

Gdy użytkownik prosi bota o zrobienie czegoś, co wymaga zalogowania użytkownika przez bota, bot może użyć elementu do OAuthPrompt zainicjowania pobierania tokenu dla danego połączenia. Element OAuthPrompt tworzy przepływ pobierania tokenu, który składa się z następujących elementów:

  1. Sprawdź, czy usługa Azure AI Bot Service ma już token dla bieżącego użytkownika i połączenia. Jeśli istnieje token, zostanie zwrócony token.
  2. Jeśli usługa Azure AI Bot Service nie ma buforowanego tokenu, OAuthCard zostanie utworzony przycisk logowania, który użytkownik może wybrać.
  3. Gdy użytkownik wybierze OAuthCard przycisk logowania, usługa Azure AI Bot Service wyśle bota token użytkownika bezpośrednio lub przedstawi użytkownikowi 6-cyfrowy kod uwierzytelniania w celu wprowadzenia w oknie czatu.
  4. Jeśli użytkownik jest wyświetlany z kodem uwierzytelniania, bot wymienia ten kod uwierzytelniania dla tokenu użytkownika.

W poniższych sekcjach opisano sposób implementowania niektórych typowych zadań uwierzytelniania.

Użyj monitu OAuth, aby zalogować użytkownika i uzyskać token

Architecture diagram for the C# sample.

Dialogs\MainDialog.cs

Dodaj monit OAuth do pliku MainDialog w konstruktorze. W tym miejscu wartość nazwy połączenia została pobrana z pliku appsettings.json .

AddDialog(new OAuthPrompt(
    nameof(OAuthPrompt),
    new OAuthPromptSettings
    {
        ConnectionName = ConnectionName,
        Text = "Please Sign In",
        Title = "Sign In",
        Timeout = 300000, // User has 5 minutes to login (1000 * 60 * 5)
    }));

W kroku okna dialogowego użyj polecenia BeginDialogAsync , aby uruchomić monit OAuth, który prosi użytkownika o zalogowanie się.

  • Jeśli użytkownik jest już zalogowany, spowoduje to wygenerowanie zdarzenia odpowiedzi tokenu bez monitowania użytkownika.
  • W przeciwnym razie spowoduje to wyświetlenie monitu użytkownika o zalogowanie się. Usługa Azure AI Bot Service wysyła zdarzenie odpowiedzi tokenu po próbie zalogowania się przez użytkownika.
return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);

W poniższym kroku okna dialogowego sprawdź obecność tokenu w wyniku z poprzedniego kroku. Jeśli nie ma wartości null, użytkownik pomyślnie się zalogował.

// Get the token from the previous step. Note that we could also have gotten the
// token directly from the prompt itself. There is an example of this in the next method.
var tokenResponse = (TokenResponse)stepContext.Result;

Czekaj na tokenResponseEvent

Po uruchomieniu monitu OAuth oczekuje ono na zdarzenie odpowiedzi tokenu, z którego pobierze token tokenu tokenu.

Bots\AuthBot.cs

AuthBot pochodzi z ActivityHandler i jawnie obsługuje działania zdarzeń odpowiedzi tokenu. W tym miejscu kontynuujemy aktywne okno dialogowe, które umożliwia monit OAuth o przetworzenie zdarzenia i pobranie tokenu.

protected override async Task OnTokenResponseEventAsync(ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with Token Response Event Activity.");

    // Run the Dialog with the new Token Response Event Activity.
    await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
}

Wyloguj użytkownika

Najlepszym rozwiązaniem jest jawne wylogowanie użytkowników zamiast polegać na przekroczeniu limitu czasu połączenia.

Dialogs\LogoutDialog.cs

private async Task<DialogTurnResult> InterruptAsync(DialogContext innerDc, CancellationToken cancellationToken = default(CancellationToken))
{
    if (innerDc.Context.Activity.Type == ActivityTypes.Message)
    {
        var text = innerDc.Context.Activity.Text.ToLowerInvariant();

        if (text == "logout")
        {
            // The UserTokenClient encapsulates the authentication processes.
            var userTokenClient = innerDc.Context.TurnState.Get<UserTokenClient>();
            await userTokenClient.SignOutUserAsync(innerDc.Context.Activity.From.Id, ConnectionName, innerDc.Context.Activity.ChannelId, cancellationToken).ConfigureAwait(false);

            await innerDc.Context.SendActivityAsync(MessageFactory.Text("You have been signed out."), cancellationToken);
            return await innerDc.CancelAllDialogsAsync(cancellationToken);
        }
    }

    return null;
}

Dodawanie uwierzytelniania usługi Teams

Uwierzytelnianie OAuth jest obsługiwane inaczej w usłudze Teams niż w innych kanałach. Przykład bota uwierzytelniania usługi Teams (w języku C#, JavaScript, Java lub Python) pokazuje, jak prawidłowo zaimplementować uwierzytelnianie dla usługi Teams.

Dalsze informacje

  • Dodatkowe zasoby platformy Bot Framework zawierają linki do dodatkowej pomocy technicznej.
  • Repozytorium Zestawu SDK platformy Bot Framework zawiera więcej informacji na temat repozytoriów, przykładów, narzędzi i specyfikacji skojarzonych z zestawem Bot Builder SDK.