Hinzufügen von Authentifizierung zu einem Bot

Verfügbar für C#-, JavaScript- und Python-Bots.

Verfügbar für C#-, JavaScript- und Python-Bots.

Verfügbar für Bots in allen Programmiersprachen: C#, JavaScript, Java und Python.

1. Öffnen Sie die Ressourcenseite für Ihren Bot im Azure-Portal.

2. Wählen Sie Einstellungen aus.

3. Klicken Sie ganz unten Auf der Seite unter OAuth-Verbindungseinstellungen auf Einstellung hinzufügen.

4. Füllen Sie das Formular wie folgt aus:

   1. Name: Geben Sie einen Namen für Ihre Verbindung ein. Diesen verwenden Sie im Code Ihres Bots.

   2. Dienstanbieter. Wählen Sie Microsoft Entra ID aus, um Microsoft Entra ID-spezifische Felder anzuzeigen.

   3. Client-ID. Geben Sie die Anwendungs-(Client-ID) ein, die Sie für Ihren Microsoft-Entra-ID-Identitätsanbieter aufgezeichnet haben.

   4. Geheimer Clientschlüssel. Geben Sie das Geheimnis ein, das Sie für Ihren Microsoft-Entra-ID-Identitätsanbieter aufgezeichnet haben.

      Tipp

      Wenn Sie Zertifikate verwenden möchten, können Sie den Anbieter AAD v2 mit Zertifikaten auswählen. Sie müssen Bot Service Token Store (appid: 5b404cf4-a79d-4cfe-b866-24bf8e1a4921) die Berechtigung zum Abrufen des Zertifikats erteilen.

   5. URL für den Tokenaustausch. Lassen Sie sie leer, da sie nur für SSO in Microsoft Entra ID verwendet wird.

   6. Mandanten-ID. Geben Sie die Verzeichnis-(Mandant)-ID ein, die Sie zuvor für Ihre Microsoft-Entra-ID-App oder gemeinsam notiert haben, je nachdem, welche unterstützten Kontotypen bei der Erstellung der Azure DD-App ausgewählt wurden. Folgen Sie diesen Kriterien, um zu entscheiden, welcher Wert zugewiesen werden soll:

      • Wenn Sie beim Erstellen der Microsoft-Entra-ID-App Nur Konten in diesem Organisationsverzeichnis (nur Microsoft – einzelner Mandant) ausgewählt haben, geben Sie die Mandanten-ID ein, die Sie zuvor für die Microsoft-Entra-ID-App notiert haben.
      • Wenn Sie aber „Konten in einem beliebigen Organisationsverzeichnis (beliebiges Microsoft-Entra-ID-Verzeichnis – mehrinstanzenfähig)“ und „Konten in allen Organisationsverzeichnissen und persönliche Microsoft-Konten (z. B. Skype, Xbox, Outlook.com)“ oder Konten in einem beliebigen Organisationsverzeichnis (Microsoft-Entra-ID-Verzeichnis – mehrinstanzfähig) ausgewählt haben, müssen Sie common anstelle einer Mandanten-ID eingeben. Andernfalls überprüft die Microsoft-Entra-ID-App über den Mandanten, dessen ID ausgewählt wurde, und schließt persönliche Microsoft-Konten aus.

      Dieser Mandant wird den Benutzern zugeordnet, die authentifiziert werden können. Weitere Informationen finden Sie unter Mandanten in Microsoft Entra ID.

   7. Geben Sie unter Bereiche die Namen der Berechtigungen ein, die Sie bei der Anwendungsregistrierung ausgewählt haben. Zu Testzwecken können Sie einfach eingeben: openid profile.

      Hinweis

      Bei Microsoft Entra ID wird im Feld Bereiche eine Liste von durch Leerzeichen getrennten Werten mit Beachtung der Groß-/Kleinschreibung verwendet.

5. Wählen Sie Speichern.

1. Navigieren Sie im Azure-Portal zur Ressourcenseite Ihres Bots.

2. Wählen Sie Einstellungen aus.

3. Klicken Sie ganz unten Auf der Seite unter OAuth-Verbindungseinstellungen auf Einstellung hinzufügen.

4. Füllen Sie das Formular wie folgt aus:

   1. Geben Sie unter Name einen Namen für die Verbindung ein. Dieser Name wird in Ihrem Bot-Code verwendet.

   2. Wählen Sie für Serviceanbieter Microsoft Entra ID aus. Sobald Sie dies ausgewählt haben, werden die Microsoft-Entra-ID-spezifischen Felder angezeigt.

   3. Geben Sie unter Client-ID die Anwendungs-ID (Client) ein, die Sie für Ihre Azure AD V1-Anwendung notiert haben.

   4. Geben Sie unter Geheimer Clientschlüssel das Geheimnis ein, das Sie erstellt haben, um dem Bot Zugriff auf die Microsoft-Entra-ID-App zu gewähren.

   5. Geben Sie authorization_code unter Gewährungstyp ein.

   6. Geben Sie https://login.microsoftonline.com unter Anmelde-URL ein.

   7. Geben Sie als Mandanten-ID die Verzeichnis-ID (Mandant) ein, die Sie zuvor für Ihre Microsoft-Entra-ID-App notiert haben, oder common (gemeinsam), je nachdem, welche unterstützten Kontotypen bei der Erstellung der ADD-App ausgewählt wurden. Folgen Sie diesen Kriterien, um zu entscheiden, welcher Wert zugewiesen werden soll:

      • Wenn Sie beim Erstellen der Microsoft-Entra-ID-App Nur Konten in diesem Organisationsverzeichnis (nur Microsoft – einzelner Mandant) ausgewählt haben, geben Sie die Mandanten-ID ein, die Sie zuvor für die Microsoft-Entra-ID-App notiert haben.
      • Wenn Sie aber „Konten in einem beliebigen Organisationsverzeichnis (beliebiges Microsoft-Entra-ID-Verzeichnis – mehrinstanzenfähig)“ und „Konten in allen Organisationsverzeichnissen und persönliche Microsoft-Konten (z. B. Skype, Xbox, Outlook.com)“ oder Konten in einem beliebigen Organisationsverzeichnis (Microsoft-Entra-ID-Verzeichnis – mehrinstanzfähig) ausgewählt haben, müssen Sie common anstelle einer Mandanten-ID eingeben. Andernfalls überprüft die Microsoft-Entra-ID-App über den Mandanten, dessen ID ausgewählt wurde, und schließt persönliche MS-Konten aus.

      Dieser Mandant wird den Benutzern zugeordnet, die authentifiziert werden können. Weitere Informationen finden Sie unter Mandanten in Microsoft Entra ID.

   8. Für Ressourcen-URL geben Sie https://graph.microsoft.com/ ein.

   9. Lassen Sie das Feld Bereiche leer.

5. Klicken Sie auf Speichern.

1. Klonen Sie aus dem GitHub-Repository das Beispiel, mit dem Sie arbeiten möchten: Bot-Authentifizierung oder Bot-Authentifizierung für Microsoft Graph.

2. Aktualisieren Sie appsettings.json:

   • Legen Sie ConnectionName auf den Namen der OAuth-Verbindungseinstellung fest, die Sie Ihrem Bot hinzugefügt haben.

   • Legen Sie MicrosoftAppId und MicrosoftAppPassword auf die App-ID bzw. das App-Geheimnis Ihres Bots fest.

     Abhängig von den Zeichen in Ihrem Botgeheimnis müssen Sie das Kennwort unter Umständen mit XML-Escapezeichen versehen. Beispielsweise müssen alle kaufmännische Und-Zeichen (&) als & codiert werden.

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

   Um OAuth in Bot mit Datenresidenz in Public Cloud zu verwenden, müssen Sie die folgenden Konfigurationen in Ihren App-Einstellungen hinzufügen

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

   Dabei ist <Regional-OAuth-URL> eine der folgenden URIs:

   URI	Beschreibung
   https://europe.api.botframework.com	Für Public-Cloud-Bots mit Datenresidenz in Europa.
   https://unitedstates.api.botframework.com	Für Public-Cloud-Bots mit Datenresidenz in den USA.
   https://india.api.botframework.com	Für Public-Cloud-Bots mit Data Residency in Indien.

3. Aktualisieren von Startup.cs:

   Um OAuth in nicht öffentlichen Azure-Clouds wie der Government-Cloud zu verwenden, müssen Sie den folgenden Code in der Datei Startup.cs hinzufügen.

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

   Dabei ist <uri-to-use> eine der folgenden URIs:

   URI	Beschreibung
   https://api.botframework.azure.us	Für Government-Cloud-Bots ohne Datenresidenz in den USA.
   https://api.botframework.com	Für Public-Cloud-Bots ohne Datenresidenz. Dies ist der Standard-URI und erfordert keine Änderung an Startup.cs.

1. Klonen Sie aus dem GitHub-Repository, mit dem Sie arbeiten möchten: Bot-Authentifizierung oder Bot-Authentifizierung für Microsoft Graph.

2. Aktualisieren Sie die ENV-Datei:

   • Legen Sie connectionName auf den Namen der OAuth-Verbindungseinstellung fest, die Sie Ihrem Bot hinzugefügt haben.

   • Legen Sie die Werte MicrosoftAppId und MicrosoftAppPassword auf die App-ID bzw. das App-Geheimnis Ihres Bots fest.

     Abhängig von den Zeichen in Ihrem Botgeheimnis müssen Sie das Kennwort unter Umständen mit XML-Escapezeichen versehen. Beispielsweise müssen alle kaufmännische Und-Zeichen (&) als & codiert werden.

   MicrosoftAppType=
   MicrosoftAppId=
   MicrosoftAppPassword=
   MicrosoftAppTenantId=
   connectionName=
   

1. Klonen Sie aus dem GitHub-Repository das Beispiel, mit dem Sie arbeiten möchten: Bot-Authentifizierung oder Bot-Authentifizierung für Microsoft Graph.

2. Aktualisieren von application.properties:

   • Legen Sie ConnectionName auf den Namen der OAuth-Verbindungseinstellung fest, die Sie Ihrem Bot hinzugefügt haben.
   • Legen Sie MicrosoftAppId und MicrosoftAppPassword auf die App-ID bzw. das App-Geheimnis Ihres Bots fest.

   MicrosoftAppId=
   MicrosoftAppPassword=
   server.port=3978
   ConnectionName=
   

1. Klonen Sie aus dem GitHub-Repository das Beispiel, mit dem Sie arbeiten möchten: Bot-Authentifizierung oder Bot-Authentifizierung für Microsoft Graph.

2. Aktualisieren Sie config.py:

   • Legen Sie ConnectionName auf den Namen der OAuth-Verbindungseinstellung fest, die Sie Ihrem Bot hinzugefügt haben.

   • Legen Sie MicrosoftAppId und MicrosoftAppPassword auf die App-ID bzw. das App-Geheimnis Ihres Bots fest.

     Abhängig von den Zeichen in Ihrem Botgeheimnis müssen Sie das Kennwort unter Umständen mit XML-Escapezeichen versehen. Beispielsweise müssen alle kaufmännische Und-Zeichen (&) als & codiert werden.

   #!/usr/bin/env python3
   # Copyright (c) Microsoft Corporation. All rights reserved.
   # Licensed under the MIT License.
   
   import os
   
   """ Bot Configuration """
   
   
   class DefaultConfig:
       """ Bot Configuration """
   
       PORT = 3978
       APP_ID = os.environ.get("MicrosoftAppId", "")
       APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
       APP_TYPE = os.environ.get("MicrosoftAppType", "MultiTenant")
       APP_TENANTID = os.environ.get("MicrosoftAppTenantId", "")
       CONNECTION_NAME = os.environ.get("ConnectionName", "")
   

Dialogs\MainDialog.cs

Fügen Sie dem MainDialog-Element im Konstruktor eine OAuth-Eingabeaufforderung hinzu. Hier wurde der Wert für den Verbindungsnamen aus der Datei appsettings.json abgerufen.

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

Verwenden Sie innerhalb eines Dialogschritts BeginDialogAsync, um die OAuth-Eingabeaufforderung zu starten, mit der der Benutzer zum Anmelden aufgefordert wird.

• Wenn der Benutzer bereits angemeldet ist, wird ein Tokenantwortereignis generiert, ohne dass der Benutzer eine Aufforderung erhält.
• Andernfalls wird der Benutzer zum Anmelden aufgefordert. Azure KI Bot Service sendet das Tokenantwortereignis, nachdem der Benutzer versucht hat, sich anzumelden.

return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);

Überprüfen Sie im folgenden Dialogschritt, ob im Ergebnis des vorherigen Schritts ein Token enthalten ist. Wenn es nicht NULL lautet, war die Anmeldung des Benutzers erfolgreich.

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

dialogs/mainDialog.js

Fügen Sie dem MainDialog-Element im Konstruktor eine OAuth-Eingabeaufforderung hinzu. Hier wurde der Wert für den Verbindungsnamen aus der ENV-Datei abgerufen.

this.addDialog(new WaterfallDialog(MAIN_WATERFALL_DIALOG, [
    this.promptStep.bind(this),
    this.loginStep.bind(this),
    this.displayTokenPhase1.bind(this),
    this.displayTokenPhase2.bind(this)
]));

Verwenden Sie innerhalb eines Dialogschritts beginDialog, um die OAuth-Eingabeaufforderung zu starten, mit der der Benutzer zum Anmelden aufgefordert wird.

• Wenn der Benutzer bereits angemeldet ist, wird ein Tokenantwortereignis generiert, ohne dass der Benutzer eine Aufforderung erhält.
• Andernfalls wird der Benutzer zum Anmelden aufgefordert. Azure KI Bot Service sendet das Tokenantwortereignis, nachdem der Benutzer versucht hat, sich anzumelden.

const tokenResponse = stepContext.result;

Überprüfen Sie im folgenden Dialogschritt, ob im Ergebnis des vorherigen Schritts ein Token enthalten ist. Wenn es nicht NULL lautet, war die Anmeldung des Benutzers erfolgreich.

await stepContext.context.sendActivity('Login was not successful please try again.');
return await stepContext.endDialog();

MainDialog.java

Fügen Sie dem MainDialog-Element im Konstruktor eine OAuth-Eingabeaufforderung hinzu. Hier wurde der Wert für den Verbindungsnamen aus der Datei application.properties abgerufen.

OAuthPromptSettings settings = new OAuthPromptSettings();
settings.setText("Please Sign In");
settings.setTitle("Sign In");
settings.setConnectionName(configuration.getProperty("ConnectionName"));
settings.setTimeout(300000); // User has 5 minutes to login (1000 * 60 * 5)

addDialog(new OAuthPrompt("OAuthPrompt", settings));

Verwenden Sie innerhalb eines Dialogschritts beginDialog, um die OAuth-Eingabeaufforderung zu starten, mit der der Benutzer zum Anmelden aufgefordert wird.

• Wenn der Benutzer bereits angemeldet ist, wird ein Tokenantwortereignis generiert, ohne dass der Benutzer eine Aufforderung erhält.
• Andernfalls wird der Benutzer zum Anmelden aufgefordert. Azure KI Bot Service sendet das Tokenantwortereignis, nachdem der Benutzer versucht hat, sich anzumelden.

return stepContext.beginDialog("OAuthPrompt");

Überprüfen Sie im folgenden Dialogschritt, ob im Ergebnis des vorherigen Schritts ein Token enthalten ist. Wenn es nicht NULL lautet, war die Anmeldung des Benutzers erfolgreich.

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

dialogs/main_dialog.py

Fügen Sie dem MainDialog-Element im Konstruktor eine OAuth-Eingabeaufforderung hinzu. Hier wurde der Wert für den Verbindungsnamen aus der Datei config.py abgerufen.

self.add_dialog(
    WaterfallDialog(
        "WFDialog",
        [
            self.prompt_step,
            self.login_step,
            self.display_token_phase1,
            self.display_token_phase2,
        ],
    )
)

Verwenden Sie innerhalb eines Dialogschritts begin_dialog, um die OAuth-Eingabeaufforderung zu starten, mit der der Benutzer zum Anmelden aufgefordert wird.

• Wenn der Benutzer bereits angemeldet ist, wird ein Tokenantwortereignis generiert, ohne dass der Benutzer eine Aufforderung erhält.
• Andernfalls wird der Benutzer zum Anmelden aufgefordert. Azure KI Bot Service sendet das Tokenantwortereignis, nachdem der Benutzer versucht hat, sich anzumelden.

return await step_context.begin_dialog(OAuthPrompt.__name__)

Überprüfen Sie im folgenden Dialogschritt, ob im Ergebnis des vorherigen Schritts ein Token enthalten ist. Wenn es nicht NULL lautet, war die Anmeldung des Benutzers erfolgreich.

if step_context.result:
    await step_context.context.send_activity("You are now logged in.")
    return await step_context.prompt(
        ConfirmPrompt.__name__,
        PromptOptions(
            prompt=MessageFactory.text("Would you like to view your token?")
        ),
    )

await step_context.context.send_activity(
    "Login was not successful please try again."
)

Bots\AuthBot.cs

AuthBot wird von ActivityHandler abgeleitet und führt eine explizite Verarbeitung von Tokenantwortereignis-Aktivitäten durch. Hier setzen wir den aktiven Dialog fort, sodass die OAuth-Eingabeaufforderung das Ereignis verarbeiten und das Token abrufen kann.

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

bots/authBot.js

AuthBot wird von ActivityHandler abgeleitet und führt eine explizite Verarbeitung von Tokenantwortereignis-Aktivitäten durch. Hier setzen wir den aktiven Dialog fort, sodass die OAuth-Eingabeaufforderung das Ereignis verarbeiten und das Token abrufen kann.

await this.dialog.run(context, this.dialogState);

await next();

AuthBot.java

AuthBot wird von Dialog abgeleitet und führt eine explizite Verarbeitung von Tokenantwortereignis-Aktivitäten durch. Hier setzen wir den aktiven Dialog fort, sodass die OAuth-Eingabeaufforderung das Ereignis verarbeiten und das Token abrufen kann.

@Override
protected CompletableFuture<Void> onTokenResponseEvent(TurnContext turnContext) {
    LoggerFactory.getLogger(AuthBot.class).info("Running dialog with Token Response Event Activity.");

    // Run the Dialog with the new Token Response Event Activity.
    return Dialog.run(dialog, turnContext, conversationState.createProperty("DialogState"));
}

bots/auth_bot.py

AuthBot führt eine explizite Verarbeitung von Tokenantwortereignis-Aktivitäten durch. Hier setzen wir den aktiven Dialog fort, sodass die OAuth-Eingabeaufforderung das Ereignis verarbeiten und das Token abrufen kann.

async def on_token_response_event(self, turn_context: TurnContext):
    # Run the Dialog with the new Token Response Event Activity.
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

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

dialogs/logoutDialog.js

async interrupt(innerDc) {
    if (innerDc.context.activity.type === ActivityTypes.Message) {
        const text = innerDc.context.activity.text.toLowerCase();
        if (text === 'logout') {
            const userTokenClient = innerDc.context.turnState.get(innerDc.context.adapter.UserTokenClientKey);

            const { activity } = innerDc.context;
            await userTokenClient.signOutUser(activity.from.id, this.connectionName, activity.channelId);

            await innerDc.context.sendActivity('You have been signed out.');
            return await innerDc.cancelAllDialogs();
        }
    }

LogoutDialog.java

private CompletableFuture<DialogTurnResult> interrupt(DialogContext innerDc) {
    if (innerDc.getContext().getActivity().getType().equals(ActivityTypes.MESSAGE)) {
        String text = innerDc.getContext().getActivity().getText().toLowerCase();

        if (text.equals("logout")) {
            // The bot adapter encapsulates the authentication processes.
            BotFrameworkAdapter botAdapter = (BotFrameworkAdapter) innerDc.getContext().getAdapter();
            botAdapter.signOutUser(
                innerDc.getContext(),
                getConnectionName(),
                innerDc.getContext().getActivity().getFrom().getId())
                    .thenApply(result -> innerDc.getContext().sendActivity(MessageFactory.text("You have been signed out."))
                    .thenApply(sendResult -> null));
            return innerDc.cancelAllDialogs();
        }
    }

    return CompletableFuture.completedFuture(null);
}

dialogs/logout_dialog.py

        return result
    return await super().on_continue_dialog(inner_dc)

async def _interrupt(self, inner_dc: DialogContext):
    if inner_dc.context.activity.type == ActivityTypes.message:
        text = inner_dc.context.activity.text.lower()
        if text == "logout":
            user_token_client: UserTokenClient = inner_dc.context.turn_state.get(