Konfigurieren Des Agents für die Verwendung von OAuth

Richten Sie zunächst OAuth für einen Agent in Ihrer Azure Bot-Ressource und die entsprechende App-Registrierung ein. Die Agentlaufzeit bezieht und aktualisiert dann Benutzertoken über die Funktion AgentApplication zur automatischen Anmeldung. Die automatische Anmeldung kann global (alle Aktivitätstypen) oder selektiv ausgeführt werden, sodass nur bestimmte Routen oder Aktivitätstypen ein Token anfordern.

Sie können mehrere OAuth-Handler in der Konfiguration registrieren und sie bestimmten Routen zuweisen oder einen einzelnen Standardhandler deklarieren, der überall verwendet wird. Jeder Handler kann optional einen On-Behalf-Of (OBO)-Austausch durchführen, wenn die Azure-Seite dafür konfiguriert ist. Einen schnellen Einstieg finden Sie im AutoSignIn-Beispiel, oder stellen Sie die hier gezeigte Konfiguration in einen vorhandenen Agent um.

In den folgenden Abschnitten wird beschrieben, wie Sie UserAuthorization konfigurieren, zwischen einem globalen und einem routenspezifischen Ansatz wählen und Token (Standard und OBO) während der Verarbeitung abrufen. Regionale Anleitungen werden auch für Nicht-US-Bereitstellungen bereitgestellt.

Sprachunterstützung für OAuth

Das Agents SDK unterstützt OAuth für alle Sprachen. Details sind in verschiedenen Sprachen ähnlich. Die Codebeispiele in diesem Artikel sind spezifisch für .NET.

Sie konfigurieren einen .NET Agent in appSettings.json oder über Code in Program.cs. In diesem Artikel wird beschrieben, wie Sie die Konfiguration mit appSettings.json durchführen.

Settings

Ein UserAuthorization Objekt innerhalb AgentApplication steuert, wie der Agent Benutzertoken erwirbt. Der folgende JSON-Code und andere wie im Artikel zeigen die hierarchische Struktur. In den folgenden Tabellen werden die einzelnen Eigenschaften für UserAuthorization und für das geschachtelte Settings Objekt beschrieben.

  "AgentApplication": {
    "UserAuthorization": {
      "DefaultHandlerName": "{{handler-name}}",
      "AutoSignIn": true | false,
      "Handlers": {
        "{{handler-name}}": {
          "Settings": {
            "AzureBotOAuthConnectionName": "{{azure-bot-connection-name}}",
            "OBOConnectionName": "{{connection-name}}",
            "OBOScopes": [
              "{{obo-scope}}"
            ],
            "Title": "{{signin-card-title}}",
            "Text": "{{signin-card-button-text}}",
            "InvalidSignInRetryMax": {{int}},
            "InvalidSignInRetryMessage": {{invalid-attempt-message}},
            "Timeout": {{timeout-ms}}
          }
        }
      }
    }
  }

Eigenschaften der Benutzerberechtigungen

In der folgenden Tabelle sind die Eigenschaften der obersten Ebene UserAuthorization aufgeführt, die bestimmen, wie Handler ausgewählt werden und wie Token für jede eingehende Aktivität abgerufen werden.

Wenn Sie einschränken möchten, auf welche Aktivitäten die automatische Anmeldung angewendet wird, legen Sie ein Prädikat wie das folgende fest: Options.AutoSignIn = (context, ct) => Task.FromResult(context.Activity.IsType(ActivityTypes.Message));.

Eigenschaften der Einstellungen

In der folgenden Tabelle wird das geschachtelte Settings Objekt beschrieben, das auf einen einzelnen OAuth-Handler angewendet wird und die Darstellung von Anmeldekarten, das Wiederholungsverhalten, Zeitüberschreitungen und die optionale OBO-Austauschkonfiguration steuert.

Welchen Typ sollten Sie verwenden?

Verwenden Sie die folgende Tabelle, um zu entscheiden, welcher Ansatz zu Ihrem Szenario passt.

Verwenden des Tokens im Code (nicht-OBO)

In diesem Abschnitt wird gezeigt, wie Sie das Benutzertoken abrufen und verwenden, das direkt von Ihrer Azure Bot OAuth-Verbindung zurückgegeben wird, ohne einen On-Behalf-Of-Austausch durchzuführen. Entscheiden Sie zuerst, ob Sie globale automatische Anmeldung oder Handler pro Route bevorzugen. Rufen Sie dann in Ihrem Aktivitätshandler "GetTurnTokenAsync " so spät wie möglich auf, damit das SDK das Token aktualisieren kann, wenn es bald abläuft. Die folgenden Beispiele veranschaulichen beide Muster.

Konfiguration nur für die automatische Anmeldung

Verwenden Sie diese Konfiguration, wenn die globale automatische Anmeldung ein Token für jede eingehende Aktivität abrufen soll, ohne dass für jeden Routenhandler angegeben werden muss.

  "AgentApplication": {
    "UserAuthorization": {
      "DefaultHandlerName": "auto",
      "Handlers": {
        "auto": {
          "Settings": {
            "AzureBotOAuthConnectionName": "teams_sso",
          }
        }
      }
    }
  },

Ihr Agentcode würde ungefähr wie folgt aussehen:

public class MyAgent : AgentApplication
{
    public MyAgent(AgentApplicationOptions options) : base(options)
    {
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
    }

    public async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        var token = await UserAuthorization.GetTurnTokenAsync(turnContext);

        // use the token 
    }
}

Konfiguration pro Route

Verwenden Sie eine Konfiguration pro Route, wenn Sie eine differenzierte Steuerung wünschen: Nur die Routen, die Sie explizit markieren, erwerben Token. Durch die Konfiguration pro Route werden unnötige Tokenabrufe reduziert, unterschiedliche Routen für unterschiedliche OAuth-Verbindungen (und daher unterschiedliche Ressourcen oder Geltungsbereiche) ermöglicht, und es können authentifizierte und nicht authentifizierte Routen innerhalb desselben Agents kombiniert werden. Im folgenden Beispiel ist die globale automatische Anmeldung deaktiviert, und ein einzelner messageOauth Handler wird nur an die Nachrichtenroute angefügt.

  "AgentApplication": {
    "UserAuthorization": {
      "AutoSignIn": false,
      "Handlers": {
        "messageOauth": {
          "Settings": {
            "AzureBotOAuthConnectionName": "teams_sso",
          }
        }
      }
    }
  },

Ihr Agentcode würde ungefähr wie folgt aussehen:

public class MyAgent : AgentApplication
{
    public MyAgent(AgentApplicationOptions options) : base(options)
    {
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last, autoSignInHandlers: ["messageOauth"]);
    }

    public async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        var token = await UserAuthorization.GetTurnTokenAsync(turnContext, "messageOauth");

        // use the token
    }
}

Verwenden Sie GetTurnTokenAsync

Rufen Sie GetTurnTokenAsync auf, wenn Sie das Benutzertoken während einer Drehung benötigen. Sie können sie mehrmals aufrufen. Rufen Sie sie unmittelbar vor der Verwendung auf, damit die Aktualisierungslogik (falls erforderlich) transparent behandelt wird.

Verwenden des Tokens im Code (OBO)

On-Behalf-Of (OBO) basiert auf der anfänglichen Benutzeranmeldung, die ein austauschbares Token zurückgibt. Dies erfordert, dass die OAuth-Verbindungsbereiche einen bereich enthalten, der einem Bereich entspricht, der von der downstream-API verfügbar gemacht wird (z. B. wenn der verfügbar gemachte Bereich ist defaultScopes, der konfigurierte Bereich kann sein api://botid-{{clientId}}/defaultScopes). Das Agents SDK führt dann einen Austausch über die Microsoft Authentication Library (MSAL) (MSAL) durch, indem eine konfigurierte Verbindung verwendet wird, die durch OBOConnectionName und die Liste von OBOScopes identifiziert wird. Wenn beide OBOConnectionName und OBOScopes in der Konfiguration vorhanden sind, erfolgt der Austausch automatisch, und Sie erhalten das endgültige Token über GetTurnTokenAsync. Wenn eines von beiden fehlt, können Sie den Austausch zur Laufzeit explizit mit ExchangeTurnTokenAsync durchführen, sodass Sie die Verbindung oder die Bereichsliste dynamisch bestimmen können.

OBO in Konfiguration

Verwenden Sie dieses Muster, wenn Sie die nachgelagerte Ressource und bereiche kennen, die Sie zur Konfigurationszeit benötigen. Wenn Sie sowohl OBOConnectionName als auch OBOScopes bereitstellen, führt das SDK während des Anmeldevorgangs automatisch den On-Behalf-Of-Austausch durch. Dies bedeutet, dass nachfolgende Aufrufe von GetTurnTokenAsync das OBO-Token direkt ohne zusätzlichen Laufzeitcode zurückgeben.

  "AgentApplication": {
    "UserAuthorization": {
      "DefaultHandlerName": "auto",
      "Handlers": {
        "auto": {
          "Settings": {
            "AzureBotOAuthConnectionName": "teams_sso",
            "OBOConnectionName": "ServiceConnection",
            "OBOScopes": [
              "https://myservicescope.com/.default"
            ]
          }
        }
      }
    }
  },
  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "FederatedCredentials",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{TenantId}}",
        "ClientId": "{{ClientId}}",
        "FederatedClientId": "{{ManagedIdentityClientId}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

Ihr Agentcode würde ungefähr wie folgt aussehen:

public class MyAgent : AgentApplication
{
    public MyAgent(AgentApplicationOptions options) : base(options)
    {
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
    }

    public async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        var token = await UserAuthorization.GetTurnTokenAsync(turnContext);

        // use the token
    }
}

OBO Exchange zur Laufzeit

Verwenden Sie einen Laufzeitaustausch, wenn die nachgeschaltete Ressource, bereiche oder sogar die Verbindung, die Sie verwenden müssen, nicht in der Konfiguration behoben werden kann, z. B. wenn Bereiche von Mandanten, Benutzerrolle oder Featurekennzeichnung abhängen. In diesem Modell konfigurieren Sie optional das OBOConnectionName, rufen dann ExchangeTurnTokenAsync mit den Scopes auf, die Sie zur Laufzeit festlegen, und erhalten ein ausgetauschtes Token, das Sie sofort verwenden können.

  "AgentApplication": {
    "UserAuthorization": {
      "DefaultHandlerName": "auto",
      "Handlers": {
        "auto": {
          "Settings": {
            "AzureBotOAuthConnectionName": "teams_sso",
            "OBOConnectionName": "ServiceConnection"
          }
        }
      }
    }
  },
  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "FederatedCredentials",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{TenantId}}",
        "ClientId": "{{ClientId}}",
        "FederatedClientId": "{{ManagedIdentityClientId}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

Ihr Agentcode würde ungefähr wie folgt aussehen:

public class MyAgent : AgentApplication
{
    public MyAgent(AgentApplicationOptions options) : base(options)
    {
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
    }

    public async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        var scopes = GetScopes();

        var exchangedToken = await UserAuthorization.ExchangeTurnTokenAsync(turnContext, exchangeScopes: scopes);

        // use the token
    }
}

Regionale OAuth-Einstellungen

Aktualisieren Sie für Nicht-US-Regionen den tokendienstendpunkt, den Ihr Agent verwendet.

Fügen Sie den folgenden Code zu appsettings.json hinzu:

"RestChannelServiceClientFactory": {
   "TokenServiceEndpoint": "{{service-endpoint-uri}}"
}

Verwenden Sie für service-endpoint-urlden geeigneten Wert aus der folgenden Tabelle für Public-Cloud-Bots mit Data Residency in der angegebenen Region.