Konfigurer din agent til at bruge OAuth

Først skal du konfigurere OAuth for en agent på din Azure Bot-ressource og tilsvarende appregistrering. Agentens kørsel henter og opdaterer derefter brugertokens via funktionen AgentApplication til automatisk logon. Automatisk log ind kan fungere globalt (alle typer af aktiviteter) eller selektivt, så det kun er bestemte ruter eller typer af aktiviteter, der anmoder om et token.

Du kan registrere flere OAuth-handlere i konfigurationen og tildele dem til bestemte ruter eller deklarere en enkelt standardhandler, der bruges overalt. Hver handler kan eventuelt udføre OBO-udvekslinger (On-Behalf-Of), når Azure-siden er konfigureret til det. Du kan få en hurtig start ved at se AutoSignIn-eksemplet eller tilpasse den konfiguration, der vises her, til en eksisterende agent.

I følgende afsnit beskrives det, hvordan du konfigurerer UserAuthorization, beslutter mellem globale tilgange og tilgange pr. rute og henter tokens (standard og OBO) under en tur. Der gives også regional vejledning til udrulninger, der ikke er i USA.

Sprogunderstøtter OAuth

Agents SDK understøtter OAuth for alle sprog. Detaljer er ens mellem forskellige sprog. Kodeeksemplerne i denne artikel er specifikke for .NET.

Du konfigurerer en .NET agent i appSettings.json eller via kode i Program.cs. I denne artikel beskrives det, hvordan du konfigurerer ved hjælp af appSettings.json.

Indstillinger

Et UserAuthorization objekt i AgentApplication styrer, hvordan agenten henter brugertokens. Den følgende JSON og andre lignende eksempler i artiklen viser den hierarkiske struktur. De efterfølgende tabeller beskriver hver egenskab for UserAuthorization og for det indlejrede Settings objekt.

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

Egenskaber for Brugergodkendelse

I følgende tabel vises de egenskaber på øverste niveau UserAuthorization , der bestemmer, hvordan handlere vælges, og hvordan tokens hentes for hver indgående aktivitet.

Hvis du vil begrænse, hvilke aktiviteter automatisk logon gælder for, skal du angive et prædikat, der ligner: Options.AutoSignIn = (context, ct) => Task.FromResult(context.Activity.IsType(ActivityTypes.Message));.

Egenskaber for indstillinger

I følgende tabel beskrives det indlejrede Settings objekt, der er anvendt på en individuel OAuth-handler, der styrer logonkortpræsentation, funktionsmåde for forsøg, timeout og valgfri konfiguration af OBO-udveksling.

Hvilken type skal du bruge?

Brug følgende tabel til at beslutte, hvilken fremgangsmåde der passer til dit scenarie.

Brug tokenet i kode (ikke OBO)

I dette afsnit kan du se, hvordan du henter og bruger det brugertoken, der returneres direkte af din Azure Bot OAuth-forbindelse uden at udføre en udveksling på vegne af. Beslut først, om du foretrækker globale automatiske logon- eller rutehandlere. I din aktivitetshandler skal du derefter kalde GetTurnTokenAsync så sent som muligt, så SDK'et kan opdatere tokenet, hvis det er tæt på udløb. Følgende eksempler illustrerer begge mønstre.

Konfiguration kun automatisk logon

Brug denne konfiguration, når global automatisk logon skal hente et token for hver indgående aktivitet uden at skulle angive handlere pr. rute.

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

Din agentkode ser nogenlunde sådan ud:

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 kun pr. rute

Brug en konfiguration pr. rute, når du vil have detaljeret kontrol: Kun de ruter, du eksplicit markerer hent tokens. Konfiguration pr. rute reducerer unødvendig hentning af token, gør det muligt for forskellige ruter at målrette særskilte OAuth-forbindelser (og derfor forskellige ressourcer eller områder) og giver dig mulighed for at blande godkendte og ikke-godkendte ruter i den samme agent. I følgende eksempel er globalt automatisk logon deaktiveret, og en enkelt messageOauth handler er kun knyttet til meddelelsesruten.

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

Din agentkode ser nogenlunde sådan ud:

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

Brug GetTurnTokenAsync

Kald GetTurnTokenAsync , når du har brug for brugertokenet under en tur. Du kan aktivere den flere gange. Kald den umiddelbart før brug, så opdateringslogik (hvis det er nødvendigt) håndteres gennemsigtigt.

Brug tokenet i kode (OBO)

On-Behalf-Of (OBO) er afhængig af den indledende brugerlogon, der returnerer et ombytteligt token. Det kræver, at OAuth-forbindelsens områder omfatter et, der svarer til et område, der vises af downstream-API'en (hvis det eksponerede område f.eks. er defaultScopes, kan det konfigurerede område være api://botid-{{clientId}}/defaultScopes). Agents SDK udfører derefter en MSAL-udveksling (Microsoft Authentication Library) ved hjælp af en konfigureret forbindelse, der er identificeret af OBOConnectionName , og listen over OBOScopes. Når både OBOConnectionName og OBOScopes er til stede i konfigurationen, sker udvekslingen automatisk, og du henter det endelige token via GetTurnTokenAsync. Hvis der mangler en af dem, kan du udføre udvekslingen eksplicit på kørselstidspunktet med ExchangeTurnTokenAsync, så du kan løse forbindelsen eller områdelisten dynamisk.

OBO i konfiguration

Brug dette mønster, når du kender den downstreamressource og de områder, du har brug for på konfigurationstidspunktet. Når du angiver både OBOConnectionName og OBOScopes, udfører SDK'et automatisk udvekslingen på vegne af under login-processen. Det betyder, at efterfølgende kald til GetTurnTokenAsync returnerer OBO-tokenet direkte uden ekstra kørselskode.

  "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 agentkode ser nogenlunde sådan ud:

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 på kørselstidspunktet

Brug en kørselsudveksling, når den downstream-ressource, de områder eller den forbindelse, du skal bruge, ikke kan løses i konfigurationen – f.eks. når områder afhænger af lejer, brugerrolle eller et funktionsflag. I denne model konfigurerer du (valgfrit) OBOConnectionNameog kalder derefter ExchangeTurnTokenAsync med de områder, du beslutter på skift, og modtager et udvekslet token, som du straks kan anvende.

  "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 agentkode ser nogenlunde sådan ud:

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

Internationale OAuth-indstillinger

For områder, der ikke er i USA, skal du opdatere det tokentjenesteslutpunkt, som din agent bruger.

Føj følgende kode til appsettings.json:

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

For service-endpoint-urlskal du bruge den relevante værdi fra følgende tabel til public-cloud bots med dataopbevaring i det angivne område.