Поддержка единого входа (SSO) для БотыSingle sign-on (SSO) support for bots

Проверка подлинности с единым входом в Azure Active Directory (Azure AD) сводит к минимуму число попыток ввода учетных данных для входа пользователями, обновляя маркер проверки подлинности без уведомления.Single sign-on authentication in Azure Active Directory (Azure AD) minimizes the number of times users need to enter their login credentials by silently refreshing the authentication token. Если пользователи согласились использовать ваше приложение, им не нужно будет согласиться на другое устройство и автоматически выполнить вход в систему.If users agrees to use your app, they will not have to consent again on another device and will be signed in automatically. Этот процесс очень похож на поддержку единого входа для вкладки Teams.The flow is very similar to the Teams tab SSO support. Разница — это протокол, который используется для получения маркеров запросов Bot и получения ответов.The difference is the protocol for how a bot requests tokens and receives responses.

OAuth 2,0 — это открытый стандарт проверки подлинности и авторизации, используемый Azure Active Directory (Azure AD) и многими другими поставщиками удостоверений.OAuth 2.0 is an open standard for authentication and authorization used by Azure Active Directory (Azure AD) and many other identity providers. Базовое понимание OAuth 2,0 является необходимым условием для работы с проверкой подлинности в Teams.A basic understanding of OAuth 2.0 is a prerequisite for working with authentication in Teams.

SSO SSO во время выполненияBot SSO at runtime

Схема SSO SSO во время выполнения

  1. Bot отправляет сообщение с Оаускард, которое содержит tokenExchangeResource свойство.The bot sends a message with an OAuthCard that contains the tokenExchangeResource property. Он указывает Teams на получение маркера проверки подлинности для приложения Bot.It tells Teams to obtain an authentication token for the bot application. Пользователь получает сообщения во всех активных конечных точках пользователя.The user receives messages at all the active endpoints of the user.

Примечание

  • Пользователь может одновременно иметь более одной активной конечной точки.A user can have more than one active endpoint at a time.
  • Маркер Bot получен от каждой активной конечной точки пользователя.The bot token is received from every active endpoint of the user.
  • В настоящее время для поддержки единого входа приложение должно быть установлено в личной области.Single sign-on support currently requires the app to be installed in personal scope.
  1. Если в первый раз текущий пользователь использует приложение Bot, будет выдаваться запрос на согласие (если требуется согласие) или обрабатывать проверку подлинности (например, двухфакторная проверка подлинности).If it is the first time the current user has used your bot application, there will be a request prompt to consent (if consent is required) or to handle step-up authentication (such as two-factor authentication).

  2. Microsoft Teams запрашивает маркер приложения Bot из конечной точки Azure AD для текущего пользователя.Microsoft Teams requests the bot application token from the Azure AD endpoint for the current user.

  3. Azure AD отправляет маркер приложения Bot в приложение Teams.Azure AD sends the bot application token to the Teams application.

  4. Microsoft Teams отправляет маркер участнику Bot как часть объекта value, возвращаемого действием Invoke, с именем Sign-in/Токенексчанже.Microsoft Teams sends the token to the bot as part of the value object returned by the invoke activity with the name sign-in/tokenExchange.

  5. Маркер будет проанализирован в приложении Bot для извлечения необходимой информации, например, адреса электронной почты пользователя.The token will be parsed in the bot application to extract the needed information, such as the user's email address.

Разработка ленты единого входа Microsoft TeamsDevelop a Single sign-on Microsoft Teams bot

Следующие действия: необходимы для разработки единого входа Microsoft Teams Bot:The following steps: are required to develop an SSO Microsoft Teams bot:

  1. Создание бесплатной учетной записи AzureCreate an Azure free account
  2. Обновление манифеста приложения TeamsUpdate your Teams app manifest
  3. Добавление кода для запроса и получения маркера BotAdd the code to request and receive the bot token

Создание учетной записи AzureCreate an Azure account

Этот шаг аналогичен последующему входу в табуляцию:This step is similar to the tab SSO flow:

  1. Получение идентификатора приложения Azure AD для настольных, Интернет-и мобильных клиентов Teams.Get your Azure AD Application ID for Teams desktop, web, or mobile client.
  2. Укажите разрешения, необходимые вашему приложению для конечной точки Azure AD, и (при необходимости) Microsoft Graph.Specify the permissions that your application needs for the Azure AD endpoint and, optionally, Microsoft Graph.
  3. Предоставление разрешений для настольных приложений, веб-приложений и мобильных приложений Teams.Grant permissions for Teams desktop, web, and mobile applications.
  4. Добавьте клиентское приложение, нажав кнопку Добавить область и на открывшейся панели, введите access_as_user имя области.Add a client app by selecting the Add a scope button and in the panel that opens, enter access_as_user as the Scope name.

Примечание

Область "access_as_user", используемая для добавления клиентского приложения, — "Администраторы и пользователи".The "access_as_user" scope used to add a client app is for "Administrators and users".

Важно!

  • Если вы создаете автономную программу Bot, задайте здесь идентификатор URI идентификатора приложения api://botid-{YourBotId} , йоурботид ссылается на идентификатор приложения Azure AD.If you are building a standalone bot, set the Application ID URI to api://botid-{YourBotId} Here, YourBotId refers to your Azure AD application ID.
  • Если вы создаете приложение с помощью ленты и вкладки, задайте для идентификатора URI идентификатор приложения api://fully-qualified-domain-name.com/botid-{YourBotId} .If you are building an app with a bot and a tab, set the Application ID URI to api://fully-qualified-domain-name.com/botid-{YourBotId}.

Обновление манифеста приложенияUpdate your app manifest

Добавьте новые свойства в манифест Microsoft teams:Add new properties to your Microsoft Teams manifest:

WebApplicationInfo — родительский элемент следующих элементов:WebApplicationInfo - The parent of the following elements:

  • ID — идентификатор клиента приложения.id - The client ID of the application. Это идентификатор приложения, полученный в ходе регистрации приложения с помощью Azure AD.This is the application ID that you obtained as part of registering the application with Azure AD.
  • Resource — домен и поддомен приложения.resource - The domain and subdomain of your application. Это тот же URI (включая api:// протокол), который вы зарегистрировали при создании scope на шаге 6.This is the same URI (including the api:// protocol) that you registered when creating your scope in step 6 above. Не следует включать access_as_user путь в ресурс.You shouldn't include the access_as_user path in your resource. Доменная часть этого URI должна быть соотнесена с доменом, включая все поддомены, используемые в URL-адресах манифеста приложения Teams.The domain part of this URI should match the domain, including any subdomains, used in the URLs of your Teams application manifest.
"webApplicationInfo": {
  "id": "00000000-0000-0000-0000-000000000000",
  "resource": "api://subdomain.example.com/00000000-0000-0000-0000-000000000000"
}

Запрос маркера BotRequest a bot token

Запрос на получение маркера является обычным запросом POST Message (с использованием существующей схемы сообщения).The request to get the token is a normal POST message request (using the existing message schema). Он включен в вложения объекта Оаускард.It is included in the attachments of an OAuthCard. Схема для класса Оаускард определена в схеме Microsoft Bot 4,0 , и она очень похожа на карточку входа.The schema for the OAuthCard class is defined in Microsoft Bot Schema 4.0 and it is very similar to a sign-in card. Если TokenExchangeResource свойство заполнено на карточке, Teams будет обрабатывать этот запрос как необъявляемый токен.Teams will treat this request as a silent token acquisition if the TokenExchangeResource property is populated on the card. Для канала Teams мы соблюдаем только Id свойство, которое уникально идентифицирует запрос маркера.For the Teams channel we honor only the Id property, which uniquely identifies a token request.

Примечание

OAuthPrompt MultiProviderAuthDialog Для проверки подлинности с использованием единого входа (Bot) или платформы.The Bot Framework OAuthPrompt or the MultiProviderAuthDialog is supported for single sign-on (SSO) authentication.

Если вы впервые используете приложение, а пользователь не дойдет согласие пользователя, в диалоговом окне будет отображаться диалоговое окно, в котором будет выполняться согласие, аналогичный приведенному ниже.If this is the first time the user is using your application and the user consent is required, the user will be shown a dialog to continue with the consent experience similar to the one below. Когда пользователь выбирает Continue (продолжить), выполняются два различных действия в зависимости от того, определен ли Bot или нет, и кнопку входа на оаускард.When the user selects Continue, two different things occur depending on whether the bot is defined or not and a sign-in button on the OAuthCard.

Диалоговое окно "согласие"

Если элемент Bot определяет кнопку входа, то поток входа для Боты будет срабатывать аналогично потоку входа с помощью кнопки карточки в потоке сообщений.If the bot defines a sign-in button, the sign-in flow for bots will be triggered similarly to the sign-in flow from a card button in a message stream. Разработчик должен принять решение о том, какие разрешения необходимо запросить у пользователя.It is up to the developer to decide which permissions to ask for the user to consent. Этот подход рекомендуется в тех случаях, когда вам нужен маркер с разрешениями openId , например, если вы хотите обмениваться маркером для ресурсов Graph.This approach is recommended if you need a token with permissions beyond openId, for example, if you want to exchange the token for graph resources.

Если на карточке ленты не предоставляется кнопка входа, она инициирует согласие пользователя на минимальный набор разрешений.If the bot is not providing a sign-in button on the card, it triggers user consent for a minimal set of permissions. Этот маркер полезен для обычной проверки подлинности и считывания адреса электронной почты пользователя.This token is useful for basic authentication and getting the user email address.

Запрос маркера C# без кнопки входа:C# token request without a sign-in button:

var attachment = new Attachment
            {
                Content = new OAuthCard
                {
                    TokenExchangeResource = new TokenExchangeResource
                    {
                        Id = requestId
                    }
                },
                ContentType = OAuthCard.ContentType,
            };
            var activity = MessageFactory.Attachment(attachment);

            // NOTE: This activity needs to be sent in the 1:1 conversation between the bot and the user. 
            // If the bot supports group and channel scope, this code should be updated to send the request to the 1:1 chat. 

   await turnContext.SendActivityAsync(activity, cancellationToken);

Получение маркераReceiving the token

Ответ с маркером отправляется через действие Invoke с той же схемой, что и другие вызовы, которые Боты получать сегодня.The response with the token is sent through an invoke activity with the same schema as others invoke activities the bots receive today. Единственное отличие заключается в том, что имя Invoke, Sign-in/токенексчанже и поле value , которое будет содержать идентификатор (строку) начального запроса для получения маркера, и поле маркер (строковое значение, включая маркер).The only difference is the invoke name, sign-in/tokenExchange and the value field which will contain the Id (a string) of the initial request to get the token and the token field (a string value including the token). Обратите внимание, что вы можете получить несколько ответов для данного запроса, если у пользователя есть несколько активных конечных точек.Please note that you might receive multiple responses for a given request if the user has multiple active endpoints. Вы можете подублировать ответы с маркером.It is up to you to deduplicate the responses with the token.

Код C#, реагирующий на обработку действия Invoke:C# code to respond to handle the invoke activity:

protected override async Task<InvokeResponse> OnInvokeActivityAsync
  (ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
        {
            try
            {
                if (turnContext.Activity.Name == SignInConstants.TokenExchangeOperationName && turnContext.Activity.ChannelId == Channels.Msteams)
                {
                    await OnTokenResponseEventAsync(turnContext, cancellationToken);
                    return new InvokeResponse() { Status = 200 };
                }
                else
                {
                    return await base.OnInvokeActivityAsync(turnContext, cancellationToken);
                }
            }
            catch (InvokeResponseException e)
            {
                return e.CreateInvokeResponse();
            }
        }

turnContext.activity.valueТип относится к типу токенексчанжеинвокерекуест и содержит маркер, который можно использовать для работы с роботом.The turnContext.activity.value is of type TokenExchangeInvokeRequest and contains the token that can be further used by your bot. Безопасное хранение маркеров по соображениям производительности и их обновление.Store the tokens securely for performance reasons and refresh them.

Обновление портала Azure с подключением OAuthUpdate the Azure portal with the OAuth connection

  1. На портале Azure вернитесь к регистрации каналов ленты.In the Azure Portal, navigate back to the Bot Channels Registration.

  2. Перейдите к колонке Параметры и выберите пункт Добавить параметр в разделе Параметры подключения OAuth.Switch to the Settings blade and choose Add Setting under the OAuth Connection Settings section.

Представление SSOBotHandle2

  1. Заполните форму параметров подключения .Complete the Connection Setting form:
  • Введите имя для нового параметра подключения.Enter a name for your new Connection Setting. Это имя, которое будет указываться в ссылках внутри параметров кода службы Bot в действии 5.This will be the name that gets referenced inside the settings of your bot service code in step 5.
  • В раскрывающемся списке Поставщик услуг выберите Azure Active Directory v2.In the Service Provider dropdown, select Azure Active Directory V2.
  • Введите учетные данные клиента для приложения AAD.Enter the client credentials for the AAD application.

Примечание

В приложении AAD может потребоваться неявное предоставление .Implicit grant may be required in the AAD application.

  • Для URL-адреса обмена маркерами используйте значение Scope, определенное на предыдущем шаге приложения AAD.For the Token Exchange URL, use the scope value defined in the previous step of your AAD application. Присутствие URL-адреса Exchange маркера указывает пакету SDK, что это приложение AAD настроено для единого входа.The presence of the Token Exchange URL is indicating to the SDK that this AAD application is configured for SSO.
  • Укажите "Common" в качестве идентификатора клиента.Specify "common" as the Tenant ID.
  • Добавьте все области, настроенные при указании разрешений на доступ к подчиненным API для приложения AAD.Add all the scopes configured when specifying permissions to downstream APIs for your AAD application. Если указан идентификатор клиента и секрет клиента, хранилище маркеров будет обмениваться маркером для маркера графа с определенными разрешениями.With the client id and client secret provided, token store will exchange the token for a graph token with defined permissions for you.
  • Нажмите кнопку Сохранить.Select Save.

Представление параметра Вуссоботконнектион

Обновление примера проверки подлинностиUpdate the auth sample

Начните с примера проверки подлинности Teams.Start with the teams auth sample.

  1. Обновите Теамсбот, чтобы включить следующие функции.Update the TeamsBot to include the following. Чтобы обработать дедупинг входящего запроса, см.To handle the deduping of the incoming request, see below:
 protected override async Task OnSignInInvokeAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
        {
            await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
        }
    protected override async Task OnTokenResponseEventAsync(ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
        {
            await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
        }
  1. Обновите, appsettings.json чтобы включить botId , пароль и имя подключения, указанные выше.Update the appsettings.json to include the botId, password, and the connection name defined above.
  2. Обновите манифест и убедитесь, что token.botframework.com он находится в разделе Допустимые домены.Update the manifest and ensure that token.botframework.com is in the valid domains section.
  3. Поzip-файл манифеста с изображениями профиля и установите его в Teams.Zip the manifest with the profile images and install it in Teams.

Дополнительные примеры кодаAdditional code samples