Использование службы Azure Bot для проверки подлинности в TeamsUsing Azure Bot Service for Authentication in Teams

Важно!

Статьи, приведенные в этом разделе, основаны на пакете SDK "V3 Bot Framework".The articles in this section are based on the v3 Bot Framework SDK. Если вы ищете текущую документацию (версия 4,6 или более поздняя версия пакета SDK), ознакомьтесь с разделом " беседы Боты ".If you're looking for current documentation (version 4.6 or later of the SDK) see the Conversational Bots section.

Без Оаускард службы Azure Bot это усложняет реализацию проверки подлинности в Bot.Without the Azure Bot Service’s OAuthCard it is complicated to implement authentication in a bot. Это полная стопка стека, включающая создание веб-интерфейсов, интеграцию с внешними поставщиками OAuth, управление маркерами и обработку правильных вызовов API "сервер-сервер" для безопасного процесса проверки подлинности.It is a full-stack challenge that involving building a web experience, integrating with external OAuth providers, token management, and handling the right server-to-server API calls to complete authentication flow securely. Это может привести к клунки, для которых требуется ввод "магическых номеров".This can result in clunky experiences requiring the entry of “magic numbers”.

С Оаускард службы Azure Bot упрощается вход пользователей и доступ к поставщикам внешних данных.With Azure Bot Service’s OAuthCard, it is easier for your Teams bot to sign in your users and access external data providers. Если вы уже реализовали проверку подлинности и хотите переключиться на что-то проще, или если вы хотите добавить проверку подлинности в службу Bot в первый раз, Оаускард может сделать это проще.Whether you’ve already implemented auth and you want to switch over to something simpler, or if you are looking to add authentication to your bot service for the first time, the OAuthCard can make it easier.

В других разделах, посвященных проверке подлинности, описывается проверка подлинности без использования оаускард, поэтому если вы хотите более глубоко изучить проверку подлинности в Teams или в ситуации, когда вы не можете использовать оаускард, вы по-прежнему можете ссылаться на эти темы.Other topics in Authentication describe authentication without using the OAuthCard, so if you want to understand authentication in Teams more deeply, or have a situation where you can not use the OAuthCard, you can still refer to those topics.

Поддержка ОаускардSupport for the OAuthCard

В настоящее время существуют некоторые ограничения, которые можно использовать в Оаускард.There are currently some restrictions to where you can use the OAuthCard. Эти решения перечислены ниже.These include:

Как служба Azure Bot помогает выполнять проверку подлинности?How does the Azure Bot Service help me do authentication?

Полная документация по Оаускард доступна в разделе: Добавление проверки подлинности в Bot через службу робота Azure.Full documentation using the OAuthCard is available in the topic: Add authentication to your bot via Azure Bot Service. Обратите внимание, что этот раздел входит в набор документации по Azure Bot Framework и не относится к Teams.Note that this topic is in the Azure Bot Framework documentation set, and is not specific to Teams.

В следующих разделах рассказывается, как использовать Оаускард в Teams.The following sections tell how to use the OAuthCard in Teams.

Основные преимущества разработчиков TeamsMain benefits for Teams developers

Оаускард помогает с проверкой подлинности следующими способами:The OAuthCard helps with authentication in the following ways:

  • Обеспечивает сквозной веб-процесс проверки подлинности: вам больше не нужно создавать и размещать веб-страницы для направления внешнего входа или для перенаправления.Provides an out-of-box web-based authentication flow: you no longer have to write and host a web page to direct to external login experiences or provide a redirect.
  • Неэффективно для конечных пользователей: полный вход в Teams.Is seamless for end users: complete the full sign in experience right within Teams.
  • Включает удобные средства управления маркерами: вам больше не нужно реализовывать систему хранения маркеров — вместо этого, служба Bot позаботится о кэшировании маркеров и предоставляет безопасный механизм для извлечения этих маркеров.Includes easy token management: you no longer have to implement a token storage system – instead, the Bot Service takes care of token caching and provides a secure mechanism for fetching those tokens.
  • Поддерживается полным комплектом SDK: простота интеграции и использования в службе Bot.Is supported by complete SDKs: easy to integrate and consume from your bot service.
  • Имеет встроенную поддержку многих популярных поставщиков OAuth, таких как Azure AD/MSA, Facebook и Google.Has out-of-box support for many popular OAuth providers, such as Azure AD/MSA, Facebook, and Google.

Когда следует реализовывать собственное решение?When should I implement my own solution?

Так как маркеры доступа являются конфиденциальными сведениями, их не следует хранить во внешней службе.Because access tokens are sensitive information, you may not wish to have them stored in an external service. В этом случае вы можете по-прежнему реализовать собственную систему управления маркерами и вход в систему в Teams, как описано в разделах, посвященных проверке подлинности Teams.In this case, you may choose to still implement your own token management system and login experience within Teams, as described in the rest of the Teams Authentication topics.

Начало работы с Оаускард в TeamsGetting started with OAuthCard in Teams

Примечание

В этом руководстве используется пакет SDK для Bot Framework версии 3.This guide is using the Bot Framework v3 SDK. Здесьвы можете найти реализацию v4.You can find the v4 implementation here. Вам все равно потребуется создать манифест и включить token.botframework.com в validDomains раздел, так как в противном случае кнопка входа не будет открывать окно проверки подлинности.You will still need to create a manifest and include token.botframework.com in the validDomains section, because otherwise the Sign in button will not open the authentication window. Используйте app Studio для создания манифеста.Use the App Studio to generate your manifest.

Сначала необходимо настроить службу Azure Bot, чтобы настроить внешние поставщики проверки подлинности.You’ll first need to configure your Azure bot service to set up external authentication providers. Сведения о настройке поставщиков удостоверений для подробной процедуры.Read Configuring identity providers for detailed steps.

Чтобы включить проверку подлинности с помощью службы Azure Bot, необходимо внести следующие дополнения в код:To enable authentication using the Azure Bot Service, you need to make these additions to your code:

  1. Включите token.botframework.com в validDomains раздел манифеста приложения, так как teams внедряет страницу входа в службу Bot.Include token.botframework.com in the validDomains section of your app manifest because Teams will embed the Bot Service’s login page.
  2. Получение маркера из службы Bot, когда необходимо получить доступ к ресурсам, прошедшим проверку подлинности.Fetch the token from the Bot Service whenever your bot needs to access authenticated resources. Если маркер недоступен, отправьте сообщение с Оаускард пользователю, который запрашивает вход в внешнюю службу.If no token is available, send a message with an OAuthCard to the user requesting them to log into the external service.
  3. Обработка действия по завершению входа.Handle the login completion activity. Это гарантирует, что запрос и маркер проверки подлинности связываются с пользователем, в настоящее время взаимодействующим с роботом Bot.This ensures that the authentication request and the token are associated with the user currently interacting with your bot.
  4. Извлеките маркер, когда он должен выполнять действия, прошедшие проверку подлинности, например, вызов внешних интерфейсов API REST.Retrieve the token whenever your bot needs to perform authenticated actions, such as calling external REST APIs.

В коде диалогового окна необходимо добавить этот фрагмент кода (C#), который проверяет наличие существующего маркера доступа:In your dialog code, you’ll need to add this snippet (C#), which checks for an existing access token:

// First ask Bot Service if it already has a token for this user
var token = await context.GetUserTokenAsync(ConnectionName).ConfigureAwait(false);
if (token != null)
{
    // use the token to do exciting things!
}
else
{
    // If Bot Service does not have a token, send an OAuth card to sign in 
    await SendOAuthCardAsync(context, (Activity)context.Activity);
}

Если маркер доступа не существует, код отправит ему сообщение с Оаускард:If an access token doesn’t exist, your code will then send a message with an OAuthCard to the user:

private async Task SendOAuthCardAsync(IDialogContext context, Activity activity)
{
    await context.PostAsync($"To do this, you'll first need to sign in.");

    var reply = await context.Activity.CreateOAuthReplyAsync(_connectionName, _signInMessage, _buttonLabel).ConfigureAwait(false);
    await context.PostAsync(reply);

    context.Wait(WaitForToken);
}

Чтобы обработать действие "завершение входа", необходимо обработать следующий вызов:To handle the login complete activity, you’ll need to process this Invoke:

if (activity.Name == "signin/verifyState")
{
  // We do this so that we can pass handling to the right logic in the dialog. You can
  // set this to be whatever string you want.
  activity.Text = "loginComplete";
  await Conversation.SendAsync(activity, () => new Dialogs.RootDialog());

  return Request.CreateResponse(HttpStatusCode.OK);
}

В коде диалогового окна вы можете получить маркер из службы проверки подлинности Bot:In your dialog code, you can then retrieve the token from the Bot authentication service:

if (text.Contains("loginComplete"))
  {
    // Handle login completion event.
    JObject ctx = activity.Value as JObject;

    if (ctx != null)
    {
      string code = ctx["state"].ToString();

      var oauthClient = activity.GetOAuthClient();
      var token = await oauthClient.OAuthApi.GetUserTokenAsync(activity.From.Id, ConnectionName, magicCode: code).ConfigureAwait(false);
      if (token != null)
      {
        // Make whatever API calls here you want
        await context.PostAsync($"Success! You are now signed in.");
      }
    }
  // Need to respond to the Invoke.
  return;
}

Использование Оаускард с расширениями обмена сообщениямиUsing OAuthCard with messaging extensions

Вы также можете использовать службу Azure Bot для подключения сторонних поставщиков к своему расширению обмена сообщениями.You can also use Azure Bot Service to connect third-party providers to your messaging extension. Это то же, что и для Bot, за исключением того, что вместо возврата Оаускард служба возвращает запрос на вход.The flow is the same as with a bot, except instead of returning an OAuthCard, your service will return a login prompt.

В следующем фрагменте кода (C#) показано, как создавать ответ на вход:The following snippet (C#) illustrates how to craft the login response:

var token = await client.OAuthApi.GetUserTokenAsync(activity.From.Id, ConnectionName).ConfigureAwait(false);

if (token == null)
{
  // Send the login response with the auth link.
  string link = await client.OAuthApi.GetSignInLinkAsync(activity, ConnectionName);

  response = new ComposeExtensionResponse()
  {
    ComposeExtension = new ComposeExtensionResult()
  };
  response.ComposeExtension.Type = "auth";
  response.ComposeExtension.SuggestedActions = new ComposeExtensionSuggestedAction()
  {
    Actions = new List<CardAction>()
      {
        new CardAction(ActionTypes.OpenUrl, title: "Sign into this app", value: link)
      }
    };
  return response;
}

Обратите внимание, что в приведенном выше примере необходимо сделать вызов GetSignInLinkAsync напрямую для client.OAuthApi свойства.Note that in the example above you need to make the call to GetSignInLinkAsync directly against the client.OAuthApi property.

Когда пользователь успешно завершает последовательность входа, служба получает другой запрос на вызов, содержащий исходный запрос пользователя, а также строку с параметром State, содержащую "код Magic".When the user successfully completes the login sequence, your service will receive another Invoke request containing the original user query, along with a state parameter string containing the “magic code”. Теперь вы можете получить маркер, используя эту строку, а также идентификатор пользователя и имя подключения.You can now fetch the token using this string, along with the user ID and connection name.

var query = activity.GetComposeExtensionQueryData();
JObject data = activity.Value as JObject;

var client = activity.GetOAuthClient();

// Check if the request comes with login state
if (data != null && data["state"] != null)
{
  var token = await client.OAuthApi.GetUserTokenAsync(activity.From.Id, ConnectionName, data["state"].ToString());

  // Do stuff with the token here.

}