Delen via

Verificatie toevoegen aan een bot

  • Artikel

VAN TOEPASSING OP: SDK v4

De Azure AI Bot Service v4 SDK vereenvoudigt de ontwikkeling van bots die toegang hebben tot onlinebronnen waarvoor gebruikersverificatie is vereist. Uw bot hoeft geen verificatietokens te beheren omdat Azure dit voor u doet met OAuth 2.0 om een token te genereren op basis van de referenties van elke gebruiker. Uw bot gebruikt het token dat door Azure wordt gegenereerd om toegang te krijgen tot deze resources. Op deze manier hoeft de gebruiker geen id en wachtwoord voor de bot op te geven voor toegang tot een beveiligde resource, maar alleen voor een vertrouwde id-provider.

Zie Gebruikersverificatie voor een overzicht van hoe het Bot Framework dit soort verificatie afhandelt.

Dit artikel verwijst naar twee voorbeelden. U ziet hoe u een verificatietoken kunt verkrijgen. De andere is complexer en laat zien hoe u namens de gebruiker toegang krijgt tot Microsoft Graph . In beide gevallen kunt u Azure AD v1 of v2 als id-provider gebruiken om een OAuth-token voor de bot te verkrijgen. In dit artikel wordt beschreven hoe u:

  • Een Azure Bot-resource maken
  • De Id-provider van Microsoft Entra-id maken
  • De Microsoft Entra ID-id-provider registreren bij de bot
  • De botcode voorbereiden

Zodra u dit artikel hebt voltooid, hebt u een bot die kan reageren op een paar eenvoudige taken. In het Voorbeeld van Microsoft Graph kunt u een e-mailbericht verzenden, weergeven wie u bent en recente e-mailberichten controleren. U hoeft de bot niet te publiceren om de OAuth-functies te testen. De bot heeft echter een geldige Azure-app-id en -wachtwoord nodig.

Notitie

De Sdk's voor Bot Framework JavaScript, C# en Python blijven ondersteund, maar de Java SDK wordt buiten gebruik gesteld met definitieve langetermijnondersteuning die eindigt op november 2023.

Bestaande bots die zijn gebouwd met de Java SDK blijven functioneren.

Voor het bouwen van nieuwe bots kunt u Microsoft Copilot Studio gebruiken en lezen over het kiezen van de juiste copilot-oplossing.

Zie De toekomst van botbouw voor meer informatie.

overwegingen voor Webchat en Directe lijn

Belangrijk

U moet Direct Line met verbeterde verificatie gebruiken om beveiligingsrisico's te beperken bij het maken van verbinding met een bot met behulp van het Webchat-besturingselement. Zie Verbeterde verificatie via Direct Line voor meer informatie.

Vereisten

  • Kennis van de basisprincipes van bots, het beheren van de status, de dialoogvensterbibliotheek en het implementeren van de sequentiële gespreksstroom en het hergebruik van dialoogvensters.

  • Kennis van Azure- en OAuth 2.0-ontwikkeling.

  • Visual Studio 2017 of hoger voor .NET.

  • Node.js voor JavaScript.

  • Python 3.8+ voor Python.

  • Een van de onderstaande voorbeelden.

    Voorbeeld BotBuilder-versie Demonstreert
    Verificatie in C# of JavaScript of Java of Python v4 Ondersteuning voor OAuthCard
    Verificatie voor Microsoft Graph in C# of JavaScript of Java of Python v4 Microsoft Graph API-ondersteuning met OAuth 2.0
    Verificatie voor Microsoft Teams in C# of JavaScript of Java of Python v4 Microsoft Graph API-ondersteuning met OAuth 2.0

    Als u de voorbeelden wilt uitvoeren waarnaar in dit artikel wordt verwezen, hebt u het volgende nodig:

    • Een Microsoft Entra ID-toepassing waarmee een botresource in Azure moet worden geregistreerd. Met deze toepassing heeft de bot toegang tot een externe beveiligde resource, zoals Microsoft Graph. Hiermee kan de gebruiker ook communiceren met de bot via verschillende kanalen, zoals Webchat.
    • Een afzonderlijke Microsoft Entra ID-toepassing om te functioneren als id-provider. Deze toepassing biedt de referenties die nodig zijn om een OAuth-verbinding tot stand te brengen tussen de bot en de beveiligde resource. In dit artikel wordt Active Directory gebruikt als id-provider. Veel andere providers worden ook ondersteund.

Belangrijk

Wanneer u een bot registreert in Azure, krijgt deze een Microsoft Entra ID-toepassing toegewezen. Deze toepassing beveiligt echter toegang tot kanalen naar bot. U hebt een extra Microsoft Entra ID-toepassing nodig voor elke externe beveiligde resource die u wilt dat de bot namens de gebruiker toegang heeft.

De resource maken

Maak de Azure Bot-resource , waarmee u uw bot kunt registreren bij de Azure AI Bot Service.

Tip

Er kunnen geen nieuwe web-app-bot - en botkanalen-registratiebronnen worden gemaakt. Bestaande resources die zijn geconfigureerd en geïmplementeerd, blijven echter werken. Bots die zijn gemaakt op basis van een VSIX- of Yeoman-sjabloon op basis van SDK-versie 4.14.1.2 of hoger, bevatten ARM-sjablonen waarmee een Azure Bot-resource wordt gegenereerd.

  1. Ga naar de Azure Portal.

  2. Selecteer een resource maken in het rechterdeelvenster.

  3. Druk in het zoekvak op Enter.bot

  4. Selecteer de Azure Bot-kaart .

    Azure-botresource selecteren

  5. Selecteer Maken.

  6. Voer waarden in de vereiste velden in en controleer en werk instellingen bij.

    1. Geef informatie op onder Project-details. Selecteer of uw bot een globale of lokale gegevenslocatie heeft. Momenteel is de functie voor lokale gegevenslocatie beschikbaar voor resources in de regio 'westeurope' en 'centralindia'. Zie Regionalization in Azure AI Bot Service voor meer informatie.

      De instellingen voor projectdetails voor een Azure Bot-resource

    2. Geef informatie op onder Microsoft App ID. Selecteer hoe uw bot-identiteit wordt beheerd in Azure en of u een nieuwe identiteit wilt maken of een bestaande identiteit wilt gebruiken.

      De microsoft-app-id-instellingen voor een Azure Bot-resource

  7. Selecteer Controleren + maken.

  8. Als de validatie is geslaagd, selecteert u Maken.

  9. Zodra de implementatie is voltooid, selecteert u Ga naar de resource. De bot en gerelateerde resources worden weergegeven in de resourcegroep die u hebt geselecteerd.

  10. Als u de Bot Framework SDK nog niet hebt, selecteert u Downloaden vanuit GitHub om te leren hoe u de pakketten voor uw voorkeurstaal kunt gebruiken.

    Bot maken in SDK

U bent nu klaar om uw bot te bouwen met de Bot Framework SDK.

Tip

Wanneer Azure een nieuwe Azure Bot-resource met één tenant of meerdere tenants met een nieuwe app-id maakt, wordt er ook een wachtwoord gegenereerd.

Informatie over botidentiteit

Volg deze stappen om identiteitsgegevens toe te voegen aan het configuratiebestand van uw bot. Het bestand verschilt, afhankelijk van de programmeertaal die u gebruikt om de bot te maken.

Belangrijk

De Java-versie van de Bot Framework SDK ondersteunt alleen bots met meerdere tenants. De C#-, JavaScript- en Python-versies ondersteunen alle drie de toepassingstypen voor het beheren van de identiteit van de bot.

Taal Bestandsnaam Opmerkingen
C# appsettings.json Ondersteunt alle drie de toepassingstypen voor het beheren van de identiteit van uw bot.
JavaScript .env Ondersteunt alle drie de toepassingstypen voor het beheren van de identiteit van uw bot.
Java application.properties Ondersteunt alleen bots met meerdere tenants.
Python config.py Ondersteunt alle drie de toepassingstypen voor het beheren van de identiteit van uw bot.

De identiteitsgegevens die u moet toevoegen, zijn afhankelijk van het toepassingstype van de bot. Geef de volgende waarden op in uw configuratiebestand.

Beschikbaar voor C#-, JavaScript- en Python-bots.

Eigenschappen Weergegeven als
MicrosoftAppType UserAssignedMSI
MicrosoftAppId De client-id van de door de gebruiker toegewezen beheerde identiteit.
MicrosoftAppPassword Niet van toepassing. Laat dit leeg voor een door de gebruiker toegewezen beheerde identiteit-bot.
MicrosoftAppTenantId De tenant-id van de door de gebruiker toegewezen beheerde identiteit.

Uw app-service bijwerken

Als u een bestaande App Service-resource (web-app) voor uw bot hebt en uw bot een door de gebruiker toegewezen beheerde identiteitstoepassing is, moet u mogelijk de app-service van uw bot bijwerken:

  1. Ga naar de blade App Service voor de web-app van uw bot.
  2. Selecteer Identiteit onder Instellingen.
  3. Selecteer op de blade Identiteit het tabblad Door de gebruiker toegewezen en voeg (+) toe .
  4. Op de blade Door de gebruiker toegewezen beheerde identiteit toevoegen:

    1. Selecteer uw abonnement.

    2. Selecteer voor door de gebruiker toegewezen beheerde identiteiten de beheerde identiteit voor uw bot. Als de beheerde identiteit automatisch voor u is gegenereerd, heeft deze dezelfde naam als uw bot.

    3. Selecteer Toevoegen om deze identiteit voor uw bot te gebruiken.

      De blade App Service Identity met de beheerde identiteit voor de bot geselecteerd.

Uw app- of tenant-id ophalen

Ga als volgt te werk om de app of tenant-id van uw bot op te halen:

  1. Ga naar de resourceblade azure-bot voor uw bot.
  2. Ga naar de blade Configuratie van de bot. Vanaf deze blade kunt u de Microsoft App ID of app-tenant-id van de bot kopiëren.

Een nieuw wachtwoord genereren

Bots met één tenant en meerdere tenants hebben een app-geheim of wachtwoord dat u nodig hebt voor bepaalde bewerkingen. Azure AI Bot Service verbergt uw botgeheim. De eigenaar van de App Service-resource van de bot kan echter een nieuw wachtwoord genereren:

  1. Ga naar de resourceblade azure-bot voor uw bot.
  2. Ga naar de blade Configuratie van de bot.
  3. Selecteer Beheren, naast De Microsoft-app-id, om naar de blade Certificaten en geheimen voor de app-service te gaan.
  4. Volg de instructies op de blade om een nieuw clientgeheim te maken en de waarde op een veilige plaats vast te leggen.

Microsoft Entra ID Identity Service

De Microsoft Entra-id is een cloudidentiteitsservice waarmee u toepassingen kunt bouwen die gebruikers veilig aanmelden met behulp van industriestandaardprotocollen zoals OAuth 2.0.

U kunt een van deze twee identiteitsservices gebruiken:

  1. Microsoft Entra ID-ontwikkelaarsplatform (v1.0). Dit wordt ook wel het Azure AD v1-eindpunt genoemd, waarmee u apps kunt bouwen die gebruikers veilig aanmelden met een Microsoft-werk- of schoolaccount. Zie het overzicht van de Microsoft Entra-id voor ontwikkelaars (v1.0) voor meer informatie.
  2. Microsoft Identity Platform (v2.0). Dit wordt ook wel het Microsoft Entra ID-eindpunt genoemd. Dit is een evolutie van het Azure AD-platform (v1.0). Hiermee kunt u toepassingen bouwen die zich aanmelden bij alle Microsoft-id-providers en tokens ophalen om Microsoft-API's aan te roepen, zoals Microsoft Graph of andere API's die ontwikkelaars hebben gebouwd. Zie het overzicht van het Microsoft Identity Platform (v2.0) voor meer informatie.

Zie Waarom bijwerken naar Het Microsoft Identity Platform (v2.0)? voor informatie over de verschillen tussen de v1- en v2-eindpunten. Zie Microsoft Identity Platform (voorheen Microsoft Entra ID voor ontwikkelaars) voor volledige informatie.

De Id-provider van Microsoft Entra-id maken

In deze sectie wordt beschreven hoe u een Microsoft Entra ID-id-id-provider maakt die gebruikmaakt van OAuth 2.0 om de bot te verifiëren. U kunt Azure AD v1- of Microsoft Entra ID-eindpunten gebruiken.

Tip

U moet de Microsoft Entra ID-toepassing maken en registreren in een tenant waarin u toestemming kunt geven voor het delegeren van machtigingen die zijn aangevraagd door een toepassing.

  1. Open het deelvenster Microsoft Entra ID in Azure Portal. Als u zich niet in de juiste tenant bevindt, selecteert u Schakelen tussen mappen om over te schakelen naar de juiste tenant. (Zie voor meer informatie over het maken van een tenant Open de portal en maak een tenant.)

  2. Open het deelvenster App-registraties.

  3. Selecteer nieuwe registratie in het deelvenster App-registraties.

  4. Vul de vereiste velden in en maak de app-registratie.

    1. Geef uw toepassing een naam.

    2. Selecteer de ondersteunde accounttypen voor uw toepassing. (Elk van deze opties werkt met dit voorbeeld.)

    3. Voor de omleidings-URI selecteert u Web en stelt u de URL in op een van de ondersteunde OAuth-omleidings-URL's.

    4. Selecteer Registreren.

      • Zodra deze is gemaakt, wordt in Azure de pagina Overzicht voor de app weergegeven.
      • Noteer de waarde van de toepassings-id (client). U gebruikt deze waarde later als de client-id wanneer u de verbindingsreeks maakt en de Microsoft Entra ID-provider registreert bij de botregistratie.
      • Noteer de id-waarde van de map (tenant ). U gebruikt deze waarde om deze providertoepassing te registreren bij uw bot.

  5. Selecteer certificaten en geheimen in het navigatiedeelvenster om een geheim voor uw toepassing te maken.

    1. Selecteer onder Clientgeheimen het nieuwe clientgeheim.
    2. Voeg een beschrijving toe om dit geheim te identificeren van anderen die u mogelijk moet maken voor deze app, zoals bot login.
    3. Kies voor Verlopen een tijdsduur waarna het geheim verloopt.
    4. Selecteer Toevoegen.
    5. Voordat u Certificaten en geheimen verlaat, moet u het geheim vastleggen. U gebruikt deze waarde later als het clientgeheim wanneer u uw Microsoft Entra ID-toepassing registreert bij uw bot.

  6. Selecteer API-machtigingen in het navigatiedeelvenster om het deelvenster API-machtigingen te openen. Het is een best practice om expliciet de API-machtigingen voor de app in te stellen.

    1. Selecteer Een machtiging toevoegen om het deelvenster Api-machtigingen aanvragen weer te geven.

    2. Voor dit voorbeeld selecteert u Microsoft-API's en Microsoft Graph.

    3. Kies Gedelegeerde machtigingen en zorg ervoor dat de machtigingen die u nodig hebt, zijn geselecteerd. Voor dit voorbeeld zijn deze machtigingen vereist.

      Notitie

      Voor elke machtiging die is gemarkeerd als BEHEERDERSTOESTEMMING VEREIST , moeten zowel een gebruiker als een tenantbeheerder zich aanmelden, dus voor uw bot blijven deze meestal weg.

      • openid
      • profiel
      • Mail.Read
      • Mail.Send
      • User.Read
      • User.ReadBasic.All

    4. Selecteer Machtigingen toevoegen. (De eerste keer dat een gebruiker deze app opent via de bot, moet deze toestemming verlenen.)

U hebt nu een Microsoft Entra ID-toepassing geconfigureerd.

Notitie

U wijst de toepassings-id (client) en het clientgeheim toe wanneer u de verbindingsreeks maakt en de id-provider registreert bij de botregistratie. Zie de volgende sectie.

De Microsoft Entra ID-id-provider registreren bij de bot

De volgende stap is het registreren van uw id-provider bij uw bot.

  1. Open de azure-botresourcepagina van uw bot in Azure Portal.

  2. Selecteer Instellingen.

  3. Selecteer Onder OAuth-verbindingsinstellingen onder aan de pagina de optie Instelling toevoegen.

  4. Vul het formulier als volgt in:

    1. Name. Geef een naam voor uw verbinding op. U gebruikt deze in uw botcode.

    2. Serviceprovider. Selecteer Microsoft Entra-id om microsoft Entra ID-specifieke velden weer te geven.

    3. Client-id. Voer de toepassings-id (client) in die u hebt geregistreerd voor uw Microsoft Entra ID-id-provider.

    4. Clientgeheim. Voer het geheim in dat u hebt vastgelegd voor uw Microsoft Entra ID-id-provider.

      Tip

      Als u certificaten wilt gebruiken, kunt u de AAD v2 selecteren met de certificaatprovider . U moet Bot Service Token Store (appid: 00001111-aaaa-2222-bbbb-3333cccc44444) de machtiging geven om het certificaat op te halen.

    5. Exchange-URL van token. Laat dit veld leeg omdat deze alleen wordt gebruikt voor eenmalige aanmelding in Microsoft Entra-id.

    6. Tenant-id. Voer de map-id (tenant) in die u eerder hebt vastgelegd voor uw Microsoft Entra ID-app of algemeen , afhankelijk van de ondersteunde accounttypen die zijn geselecteerd bij het maken van de Azure DD-app. Volg deze criteria om te bepalen welke waarde u wilt toewijzen:

      • Als u bij het maken van de Microsoft Entra ID-app alleen Accounts in deze organisatiemap hebt geselecteerd (alleen Microsoft - één tenant), voert u de tenant-id in die u eerder hebt vastgelegd voor de Microsoft Entra ID-app.
      • Als u echter Accounts hebt geselecteerd in een organisatiedirectory (Elke Microsoft Entra ID-map - Multitenant- en persoonlijke Microsoft-accounts, zoals Xbox, Outlook.com) of Accounts in een organisatiemap (Microsoft Entra ID-map - Multitenant), voert u common in plaats van een tenant-id in. Anders controleert de Microsoft Entra ID-app via de tenant waarvan de id is geselecteerd en persoonlijke Microsoft-accounts uitsluiten.

      Dit is de tenant die is gekoppeld aan de gebruikers die kunnen worden geverifieerd. Zie Tenancy in Microsoft Entra ID voor meer informatie.

    7. Voer voor Bereiken de namen in van de machtiging die u hebt gekozen in de toepassingsregistratie. Voor testdoeleinden kunt u gewoon het volgende invoeren: openid profile.

      Notitie

      Voor Microsoft Entra-id heeft het veld Scopes een hoofdlettergevoelige, door spaties gescheiden lijst met waarden.

  5. Selecteer Opslaan.

Notitie

Met deze waarden heeft uw toepassing toegang tot Office 365-gegevens via de Microsoft Graph API. De Exchange-URL van het token moet ook leeg blijven, omdat deze alleen wordt gebruikt voor eenmalige aanmelding in Microsoft Entra-id.

Uw verbinding testen

  1. Selecteer de verbindingsvermelding om de verbinding te openen die u hebt gemaakt.
  2. Selecteer Verbinding testen bovenaan het deelvenster Verbindingsinstelling van de serviceprovider.
  3. De eerste keer opent u een nieuw browsertabblad met de machtigingen die uw app aanvraagt en vraagt u om te accepteren.
  4. Selecteer Accepteren.
  5. U wordt dan omgeleid naar een pagina Test connection naar <de pagina Geslaagde verbinding>.

U kunt deze verbindingsnaam nu gebruiken in uw botcode om gebruikerstokens op te halen.

De botcode voorbereiden

U hebt de app-id en het wachtwoord van uw bot nodig om dit proces te voltooien.

  1. Kloon vanuit de GitHub-opslagplaats het voorbeeld waarmee u wilt werken: Botverificatie of Bot-verificatie voor Microsoft Graph.

  2. Werk appsettings.json bij:

    • Ingesteld ConnectionName op de naam van de OAuth-verbindingsinstelling die u aan uw bot hebt toegevoegd.

    • Stel MicrosoftAppId de MicrosoftAppPassword app-id en het app-geheim van uw bot in.

      Afhankelijk van de tekens in uw botgeheim moet u mogelijk een XML-escape-wachtwoord hebben. Zo moeten alle ampersanden (&) bijvoorbeeld worden gecodeerd als &amp;.

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

    Als u OAuth wilt gebruiken in een bot met gegevenslocatie in de openbare cloud, moet u de volgende configuraties toevoegen in uw appsettings

    "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",

    Waar <Regional-OAuth-URL> een van de volgende URI's is:

    URI Beschrijving
    https://europe.api.botframework.com Voor bots in de openbare cloud met gegevenslocatie in Europa.
    https://unitedstates.api.botframework.com Voor bots in de openbare cloud met gegevenslocatie in de Verenigde Staten.
    https://india.api.botframework.com Voor openbare-cloudbots met gegevenslocatie in India.

  3. Startup.cs bijwerken:

    Als u OAuth wilt gebruiken in niet-openbare Azure-clouds, zoals de overheidscloud, moet u de volgende code toevoegen in het Startup.cs-bestand .

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

    Waarbij <URI-to-use> een van de volgende URI's is:

    URI Beschrijving
    https://api.botframework.azure.us Voor Verenigde Staten overheidscloudbots zonder gegevenslocatie.
    https://api.botframework.com Voor bots in de openbare cloud zonder gegevenslocatie. Dit is de standaard-URI en vereist geen wijziging in Startup.cs.

Zie Registratiewachtwoord ophalen om de microsoft-app-id en wachtwoordwaarden voor Microsoft-apps op te halen.

Notitie

U kunt deze botcode nu publiceren naar uw Azure-abonnement (selecteer met de rechtermuisknop het project en kies Publiceren), maar dit is niet nodig voor dit artikel. U moet een publicatieconfiguratie instellen die gebruikmaakt van de toepassing en het hostingabonnement dat u hebt gebruikt bij het configureren van de bot in Azure Portal.

De bot testen met behulp van de emulator

Als u dit nog niet hebt gedaan, installeert u de Bot Framework Emulator. Zie ook Fouten opsporen met de emulator.

Als u wilt dat de voorbeeldaanmelding van de bot werkt, moet u de emulator configureren zoals wordt weergegeven in De emulator configureren voor verificatie.

Testen

Nadat u het verificatiemechanisme hebt geconfigureerd, kunt u het daadwerkelijke testvoorbeeld van de bot uitvoeren.

Notitie

Mogelijk wordt u gevraagd om een magic-code in te voeren, omdat de manier waarop het botvoorbeeld wordt geïmplementeerd. Deze magische code maakt deel uit van rfc #7636 en is er om een extra beveiligingselement toe te voegen. Door de magic-code te verwijderen, is er een verhoogd beveiligingsrisico. Dit kan worden verzacht met Direct Line waarvoor verbeterde verificatie is ingeschakeld. Zie Verbeterde verificatie van Bot Framework voor meer informatie.

  1. Voer het botvoorbeeld lokaal uit op uw computer.
  2. Start de emulator.
  3. U moet de app-id en het wachtwoord van uw bot opgeven wanneer u verbinding maakt met de bot.
    • U krijgt de app-id en het wachtwoord van de Azure-app-registratie. Dit zijn dezelfde waarden die u hebt toegewezen aan de bot-app in het appsettings.json of .env bestand. In de emulator wijst u deze waarden toe in het configuratiebestand of de eerste keer dat u verbinding maakt met de bot.
    • Als u het wachtwoord in uw botcode moet ontsnappen aan xml-escape, moet u dit hier ook doen.
  4. Typ help een lijst met beschikbare opdrachten voor de bot en test de verificatiefuncties.
  5. Nadat u zich hebt aangemeld, hoeft u uw referenties pas opnieuw op te geven nadat u zich hebt afgemeld.
  6. Als u zich wilt afmelden en uw verificatie wilt annuleren, typt logoutu .

Notitie

Voor botverificatie is het gebruik van de Bot Connector-service vereist. De service heeft toegang tot gegevens uit uw Azure Bot-resource.

Voorbeeld van verificatie

In het voorbeeld van botverificatie is het dialoogvenster ontworpen om het gebruikerstoken op te halen nadat de gebruiker is aangemeld.

Voorbeeldgesprek met de verificatievoorbeeldbot.

Voorbeeld van verificatie voor Microsoft Graph

In het voorbeeld van botverificatie voor Microsoft Graph is het dialoogvenster ontworpen om een beperkte set opdrachten te accepteren nadat de gebruiker is aangemeld.

Voorbeeldgesprek met de voorbeeldbot van Microsoft Graph-verificatie.

Aanvullende informatie

Wanneer een gebruiker de bot vraagt iets te doen waarvoor de bot is vereist dat de gebruiker zich heeft aangemeld, kan de bot een OAuthPrompt token voor een bepaalde verbinding initiëren. Hiermee OAuthPrompt maakt u een stroom voor het ophalen van tokens die bestaat uit:

  1. Controleren of de Azure AI Bot Service al een token heeft voor de huidige gebruiker en verbinding. Als er een token is, wordt het token geretourneerd.
  2. Als Azure AI Bot Service geen token in de cache heeft, wordt er een OAuthCard gemaakt met een aanmeldingsknop die de gebruiker kan selecteren.
  3. Nadat de gebruiker op de OAuthCard aanmeldingsknop heeft geselecteerd, stuurt Azure AI Bot Service de bot rechtstreeks het token van de gebruiker of presenteert de gebruiker met een verificatiecode van 6 cijfers om in het chatvenster in te voeren.
  4. Als de gebruiker een verificatiecode krijgt, wisselt de bot deze verificatiecode uit voor het token van de gebruiker.

In de volgende secties wordt beschreven hoe het voorbeeld enkele algemene verificatietaken implementeert.

Een OAuth-prompt gebruiken om de gebruiker aan te melden en een token op te halen

Architectuurdiagram voor het C#-voorbeeld.

Dialoogvensters\MainDialog.cs

Voeg een OAuth-prompt toe aan MainDialog in de constructor. Hier is de waarde voor de verbindingsnaam opgehaald uit het appsettings.json-bestand .

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)
    }));

Gebruik BeginDialogAsync in een dialoogvensterstap om de OAuth-prompt te starten, waarin de gebruiker wordt gevraagd zich aan te melden.

  • Als de gebruiker al is aangemeld, wordt er een tokenreactie-gebeurtenis gegenereerd zonder de gebruiker te vragen.
  • Anders wordt de gebruiker gevraagd zich aan te melden. De Azure AI Bot Service verzendt de reactie-gebeurtenis van het token nadat de gebruiker zich probeert aan te melden.
return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);

Controleer in de volgende dialoogvensterstap op de aanwezigheid van een token in het resultaat van de vorige stap. Als deze niet null is, heeft de gebruiker zich aangemeld.

// 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;

Wachten op een TokenResponseEvent

Wanneer u een OAuth-prompt start, wacht deze op een tokenantwoord-gebeurtenis, waaruit het token van de gebruiker wordt opgehaald.

Bots\AuthBot.cs

AuthBot is afgeleid van ActivityHandler en verwerkt expliciet activiteiten voor tokenreacties. Hier gaan we verder met het actieve dialoogvenster, waarmee de OAuth-prompt de gebeurtenis kan verwerken en het token kan ophalen.

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);
}

De gebruiker afmelden

Het is raadzaam om gebruikers expliciet af te melden, in plaats van te vertrouwen op de verbinding met een time-out.

Dialoogvensters\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;
}

Teams-verificatie toevoegen

OAuth wordt anders verwerkt in Teams dan in andere kanalen. Het voorbeeld van de Teams-verificatiebot (in C#, JavaScript, Java of Python) laat zien hoe u verificatie voor Teams op de juiste manier implementeert.

Meer lezen