Konfigurera din agent att använda OAuth

Konfigurera först OAuth för en agent på din Azure Bot-resurs och motsvarande appregistrering. Agentkörningen hämtar och uppdaterar sedan användartoken via funktionen AgentApplication för automatisk inloggning. Automatisk inloggning kan köras globalt (alla aktivitetstyper) eller selektivt så att endast vissa vägar eller aktivitetstyper begär en token.

Du kan registrera flera OAuth-hanterare i konfigurationen och tilldela dem till specifika vägar, eller deklarera en enda standardhanterare som används överallt. Om Azure-sidan har konfigurerats för det, kan varje hanterare eventuellt utföra On-Behalf-Of (OBO)-utbyten. För en snabb start, se autosigneringsexemplet, eller anpassa konfigurationen som visas här till en befintlig agent.

I följande avsnitt beskrivs hur du konfigurerar UserAuthorization, väljer mellan globala metoder och per väg-metoder samt hämtar token (standard och OBO) under en omgång. Regional vägledning ges också för distributioner som inte är amerikanska.

Språkstöd för OAuth

Agent-SDK stöder OAuth för alla språk. Detaljerna är likartade mellan olika språk. Kodexemplen i den här artikeln är specifika för .NET.

Du konfigurerar en .NET agent i appSettings.json eller via kod i Program.cs. Den här artikeln beskriver hur du konfigurerar med hjälp av appSettings.json.

Settings

Ett UserAuthorization objekt inuti AgentApplication styr hur agenten hämtar användartoken. Följande JSON och andra liknande exempel i artikeln visar den hierarkiska strukturen. Tabellerna som följer beskriver varje egenskap för UserAuthorization och för det kapslade Settings objektet.

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

UserAuthorization-egenskaper

I följande tabell visas de egenskaper på den översta nivån UserAuthorization som avgör hur hanterare väljs och hur token hämtas för varje inkommande aktivitet.

Om du vill begränsa vilka aktiviteter som automatisk inloggning gäller för anger du ett predikat som liknar: Options.AutoSignIn = (context, ct) => Task.FromResult(context.Activity.IsType(ActivityTypes.Message));.

Egenskaper för inställningar

I följande tabell beskrivs det kapslade Settings objektet som tillämpas på en enskild OAuth-hanterare, som styr presentationen av inloggningskort, återförsöksbeteende, tidsgränser och valfri OBO-utbyteskonfiguration.

Vilken typ ska du använda?

Använd följande tabell för att bestämma vilken metod som passar ditt scenario.

Använda token i koden (icke-OBO)

Det här avsnittet visar hur du hämtar och använder användartoken som returneras direkt av din Azure Bot OAuth-anslutning utan att utföra ett on-behalf-of-utbyte. Bestäm först om du föredrar global automatisk inloggning eller hanterare per rutt. Därefter anropar du GetTurnTokenAsync i aktivitetsbehandlaren så sent som möjligt, så att SDK:t kan uppdatera tokenen om den snart upphör att gälla. Följande exempel illustrerar båda mönstren.

Konfiguration av endast automatisk inloggning

Använd den här konfigurationen när global automatisk inloggning ska hämta en token för varje inkommande aktivitet utan att behöva ange hanterare per väg.

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

Din agentkod skulle se ut ungefär så här:

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

Endast konfiguration per väg

Använd en konfiguration per väg när du vill ha detaljerad kontroll: endast de vägar som du uttryckligen markerar hämta token. Konfiguration per väg minskar onödig tokenhämtning, tillåter olika vägar att rikta in sig på distinkta OAuth-anslutningar (och därmed olika resurser eller omfång) och gör att du kan blanda autentiserade och oautentiserade vägar i samma agent. I följande exempel inaktiveras global automatisk inloggning och en enda messageOauth hanterare är endast kopplad till meddelandevägen.

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

Din agentkod skulle se ut ungefär så här:

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

Använd GetTurnTokenAsync

Anropa GetTurnTokenAsync när du behöver användartoken under en tur. Du kan anropa den flera gånger. Anropa den omedelbart före användning så att uppdateringslogik (om det behövs) hanteras transparent.

Använda token i koden (OBO)

On-Behalf-Of (OBO) förlitar sig på att den första användarinloggningen returnerar en utbytbar token. Det kräver att OAuth-anslutningens omfång inkluderar ett som motsvarar ett omfång som exponeras av det underordnade API:et (till exempel om det exponerade omfånget är defaultScopeskan det konfigurerade omfånget vara api://botid-{{clientId}}/defaultScopes). Agent-SDK:t utför sedan ett MSAL-utbyte (Microsofts autentiseringsbibliotek) med hjälp av en konfigurerad anslutning som identifieras av OBOConnectionName och listan med OBOScopes. När både OBOConnectionName och OBOScopes finns i konfigurationen sker utbytet automatiskt och du hämtar den slutliga token via GetTurnTokenAsync. Om någon av dem saknas kan du utföra tokenutbytet explicit vid körning med ExchangeTurnTokenAsync, så att du dynamiskt kan fastställa anslutningen eller omfångslistan.

OBO i konfiguration

Använd det här mönstret när du känner till den underordnade resurs och de omfång som du behöver vid konfigurationen. När du anger både OBOConnectionName och OBOScopes utför SDK:et automatiskt OBO-utbytet (på uppdrag av) under inloggningen. Det innebär att efterföljande anrop till GetTurnTokenAsync returnerar OBO-tokenen direkt utan att någon extra körningskod behövs.

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

Din agentkod skulle se ut ungefär så här:

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-utbyte under körning

Använd ett körningsutbyte när den underordnade resursen, omfången eller till och med anslutningen du måste använda inte kan åtgärdas i konfigurationen, till exempel när omfång är beroende av klientorganisation, användarroll eller en funktionsflagga. I den här modellen konfigurerar du (valfritt) OBOConnectionName och anropar sedan ExchangeTurnTokenAsync med de omfattningar som du bestämmer vid varje tur, och får då ett utbytt token som du kan använda omedelbart.

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

Din agentkod skulle se ut ungefär så här:

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

Nationella OAuth-inställningar

För icke-AMERIKANSKA regioner uppdaterar du den tokentjänstslutpunkt som din agent använder.

Lägg till följande kod i appsettings.json:

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

För service-endpoint-urlanvänder du lämpligt värde från följande tabell för offentliga molnrobotar med datahemvist i den angivna regionen.