Konfigurowanie agenta .NET do używania protokołu OAuth

Protokół OAuth dla agenta .NET jest najpierw konfigurowany na zasobie usługi Azure Bot oraz odpowiedniej rejestracji aplikacji. Następnie środowisko uruchomieniowe agenta uzyskuje i odświeża tokeny użytkownika za pośrednictwem AgentApplication funkcji automatycznego logowania. Automatyczne logowanie może być uruchamiane globalnie (wszystkie typy działań) lub selektywnie, tak aby tylko niektóre trasy lub typy działań żądały tokenu.

W konfiguracji można zarejestrować wiele programów obsługi OAuth i przypisać je do określonych tras lub zadeklarować jedną domyślną procedurę obsługi używaną wszędzie. Każdy moduł obsługi może opcjonalnie wykonywać wymiany On-Behalf-Of (OBO), pod warunkiem, że po stronie Azure została skonfigurowana odpowiednia opcja. Aby uzyskać szybki start, zobacz przykład AutoSignIn lub dostosuj konfigurację pokazaną tutaj do istniejącego agenta.

W kolejnych sekcjach opisano, jak skonfigurować UserAuthorization, dokonać wyboru między podejściem globalnym a podejściem z podziałem na trasy oraz jak pobierać tokeny (standardowe i OBO) w czasie przetwarzania. Wskazówki regionalne są również udostępniane dla wdrożeń innych niż USA.

Agent platformy .NET jest skonfigurowany w ramach ustawień aplikacji lub za pośrednictwem kodu w pliku Program.cs. Ten dokument zawiera szczegółowe informacje dotyczące używania ustawień aplikacji.

Ustawienia

Obiekt UserAuthorization wewnątrz AgentApplication steruje sposobem uzyskiwania tokenów użytkownika. Poniższy kod JSON przedstawia strukturę hierarchiczną, a następnie tabele, które opisują każdą właściwość dla UserAuthorization i dla zagnieżdżonego Settings obiektu.

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

Właściwości autoryzacji użytkownika

W poniższej tabeli wymieniono właściwości najwyższego poziomu UserAuthorization , które określają sposób wybierania procedur obsługi i sposobu uzyskiwania tokenów dla każdego działania przychodzącego.

Aby ograniczyć, do których działań ma zastosowanie automatyczne logowanie, ustaw predykat podobny do: Options.AutoSignIn = (context, ct) => Task.FromResult(context.Activity.IsType(ActivityTypes.Message));.

Właściwości ustawień

W poniższej tabeli opisano zagnieżdżony obiekt Settings zastosowany do pojedynczej procedury obsługi OAuth, odpowiadającej za prezentację karty logowania, zachowanie ponawiania prób, limity czasu i opcjonalną konfigurację wymiany typu OBO.

Jakiego typu używać?

Skorzystaj z poniższej tabeli, aby zdecydować, które podejście pasuje do danego scenariusza.

Używanie tokenu w kodzie (inne niż OBO)

W tej sekcji pokazano, jak pobrać i użyć tokenu użytkownika bezpośrednio zwróconego przez połączenie OAuth usługi Azure Bot bez przeprowadzania wymiany w imieniu użytkownika. Najpierw zdecyduj, czy wolisz globalne automatyczne logowanie, czy obsługiwacze poszczególnych tras; następnie wewnątrz obsługiwacza działań wywołaj metodę UserAuthorization.GetTurnTokenAsync tak późno, jak to możliwe, aby SDK mogło odświeżyć token, jeśli zbliża się do wygaśnięcia. W poniższych przykładach przedstawiono oba wzorce.

Konfiguracja wyłącznie logowania automatycznego

Użyj tej konfiguracji, gdy globalne automatyczne logowanie powinno uzyskać token dla każdej przychodzącej aktywności bez konieczności określania procedur obsługi dla poszczególnych tras.

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

Kod agenta będzie wyglądać mniej więcej tak:

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

Konfiguracja tylko dla trasy

Użyj konfiguracji per trasa, jeśli chcesz uzyskać szczegółową kontrolę: tylko trasy, które jawnie oznaczysz, uzyskają tokeny. Konfiguracja poszczególnych tras zmniejsza niepotrzebne pobieranie tokenów, umożliwia różnym trasom kierowanie do różnych połączeń OAuth (a tym samym różnych zasobów lub zakresów) i umożliwia łączenie tras uwierzytelnionych i nieuwierzytelnionych w obrębie tego samego agenta. W poniższym przykładzie globalne automatyczne logowanie jest wyłączone, a pojedyncza messageOauth procedura obsługująca jest przypisany tylko do trasy komunikatu.

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

Kod agenta będzie wyglądać mniej więcej tak:

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

Użyj GetTurnTokenAsync

Wywołaj GetTurnTokenAsync za każdym razem, gdy potrzebujesz tokenu użytkownika podczas rundy. Można go wywołać wielokrotnie. Wywołaj ją bezpośrednio przed użyciem, aby logika odświeżania była, w razie potrzeby, transparentnie obsługiwana.

Używanie tokenu w kodzie (OBO)

On-Behalf-Of (OBO) opiera się na początkowym logowaniu użytkownika zwracającym token możliwy do wymiany. Wymaga to, aby zakresy połączenia OAuth zawierały zakres, który odpowiada zakresowi uwidocznionemu przez podrzędny interfejs API (na przykład jeśli uwidoczniony zakres to defaultScopes, skonfigurowany zakres może być api://botid-{{clientId}}/defaultScopes). Następnie zestaw SDK agentów wykonuje wymianę w bibliotece Microsoft Authentication Library (MSAL) przy użyciu skonfigurowanego połączenia zidentyfikowanego przez OBOConnectionName oraz listy OBOScopes. Gdy zarówno element OBOConnectionName , jak i OBOScopes są obecne w konfiguracji, wymiana odbywa się automatycznie i uzyskujesz końcowy token za pośrednictwem metody GetTurnTokenAsync. Jeśli któregokolwiek z tych elementów brakuje, możesz jawnie wykonać wymianę w czasie działania za pomocą ExchangeTurnTokenAsync polecenia, co umożliwia dynamiczne rozwiązywanie listy połączeń lub zakresów.

OBO w konfiguracji

Użyj tego wzorca, gdy znasz zasoby podrzędne i zakresy potrzebne w czasie konfiguracji. Po podaniu elementów OBOConnectionName i OBOScopes pakiet SDK automatycznie wykonuje wymianę w imieniu użytkownika podczas logowania. Oznacza to, że kolejne wywołania GetTurnTokenAsync zwracają token OBO bezpośrednio, bez potrzeby dodatkowego kodu środowiska uruchomieniowego.

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

Kod agenta będzie wyglądać mniej więcej tak:

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

Wymiana OBO w środowisku uruchomieniowym

Użyj wymiany środowiska uruchomieniowego, gdy zasób podrzędny, zakresy lub nawet połączenie, którego należy użyć, nie może być naprawiony w konfiguracji — na przykład gdy zakresy zależą od dzierżawy, roli użytkownika lub flagi funkcji. W tym modelu skonfigurujesz (opcjonalnie) OBOConnectionName, a następnie wywołujesz ExchangeTurnTokenAsync z zakresami, które określisz w momencie wywołania, otrzymując wymieniony token, który można natychmiast zastosować.

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

Kod agenta będzie wyglądać mniej więcej tak:

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

Regionalne ustawienia protokołu OAuth

W przypadku regionów innych niż USA należy zaktualizować adres punktu końcowego usługi tokenów używany przez agenta.

Dodaj następujące do appsettings.json:

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

Dla service-endpoint-url, użyj odpowiedniej wartości z poniższej tabeli dla botów chmury publicznej z rezydencją danych w określonym regionie.