Добавление аутентификации конечных пользователей в помощника

Важно

Возможности и функции Power Virtual Agents теперь являются частью Microsoft Copilot Studio после значительных инвестиций в генеративный искусственный интеллект и расширенную интеграцию с Microsoft Copilot.

Некоторые статьи и снимки экрана могут ссылаться на Power Virtual Agents, пока мы обновляем документацию и учебные материалы.

Вы можете включить аутентификацию пользователя непосредственно в разговоре помощника. Аутентификация пользователя означает, что вы можете получить основные свойства пользователя, такие как имя и идентификатор, в переменные, а также предложить пользователю войти в систему с помощью узла аутентификации, получить токен пользователя для этого пользователя, а затем использовать этот токен для получения информации о пользователе из серверной системы.

Заметка

В помощниках, созданных в веб-приложении и в Microsoft Teams, предварительно настроена аутентификация для использования аутентификации Только для Teams и Power Apps.

Можно также использовать единый вход (SSO), чтобы вашим пользователям не приходилось входить в систему вручную. Дополнительные сведения см. в Настройка единого входа для Интернета.

Предварительные условия

• Использование переменных
• Настройка проверки подлинности конечных пользователей.

Веб-приложение

Добавьте аутентификацию пользователя в тему, чтобы ваши клиенты могли войти прямо в разговор. Вы можете затем персонализировать разговор с помощью пользовательских переменных и получить доступ к серверным системам от имени пользователя.

Настройка аутентификации вручную с помощью Microsoft Entra ID

Вам необходимо настроить аутентификацию пользователя с помощью Microsoft Entra ID, прежде чем вы сможете использовать аутентификацию в своих темах.

1. Выполните инструкции в разделе Настройка аутентификации пользователя с помощью Microsoft Entra ID.
2. Вернитесь к этой статье.

Добавьте проверку подлинности с системной темой Signin

Когда вы создаете помощника, Microsoft Copilot Studio автоматически добавляет системную тему под названием Вход. Чтобы использовать ее, вы должны установить аутентификацию вашего помощника вручную и потребовать от пользователей входа в систему. Когда клиент начинает разговор с помощником, срабатывает тема Вход и предлагает пользователю войти в систему. Вы можете настроить тему Вход в соответствии с потребностями вашего помощника.

1. В меню навигации в разделе Параметры выберите Безопасность.

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

3. Выберите Вручную (для пользовательского веб-сайта), затем выберите Требовать входа для пользователей.

   

   

Добавление проверки подлинности с пользовательской логикой

Тема Signin аутентифицирует пользователя в начале разговора. Чтобы позволить пользователю войти в систему позже, вы можете добавить узел Аутентификация к любой пользовательской теме.

Когда клиенты вводят свои имя и пароль, им может быть предложено ввести проверочный код. После того как они вошли в систему, им больше не будет предложено это снова, даже если они достигнут другого узла Проверка подлинности.

1. В меню навигации в разделе Параметры выберите Безопасность.

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

3. Выключите Требовать входа для пользователей.

4. В меню навигации выберите Темы, затем откройте тему, в которую вы хотите добавить проверку подлинности.

5. Выберите Добавить узел (+) и выберите Вызвать действие, а затем выберите Authenticate.

6. Протестируйте тему, используя пользователя, настроенного в вашем поставщике удостоверений.

Совет

Важно создать пути как для успешного входа, так и для неудачного. Вход может завершиться сбоем по многим причинам, в том числе из-за ошибок при входе в систему поставщика удостоверений.

Переменные аутентификации

Когда вы настроили аутентификацию пользователей для своего помощника, вы можете использовать переменные аутентификации в своих темах. В следующей таблице сравнивается доступность этих переменных в зависимости от выбранного варианта проверки подлинности.

Переменная аутентификации	Нет аутентификации	Только для Teams и Power Apps	Вручную
User.DisplayName	недоступно	в сети	в сети
User.FirstName	недоступно	в сети	в сети
User.LastName	недоступно	в сети	в сети
User.PrincipalName	недоступно	в сети	в сети
User.Email	недоступно	в сети	в сети
User.Id	недоступно	в сети	в сети
User.IsLoggedIn	недоступно	в сети	в сети
User.AccessToken	недоступно	недоступно	в сети
SignInReason	недоступно	в сети	в сети

User.DisplayName

Предупреждение

Эта переменная не обязательно содержит значение. Протестируйте с пользователем от вашего поставщика удостоверений, чтобы убедиться, что тема работает правильно.

Переменная User.DisplayName содержит отображаемое имя, которое хранится в поставщике удостоверений. Используйте эту переменную для приветствия или обращения к пользователю без необходимости явно давать имя помощнику, что делает разговор более персонализированным.

Microsoft Copilot Studio автоматически устанавливает значение User.DisplayName из утверждения name, предоставленного поставщиком удостоверений, при условии, что область действия profile была определена при настройке ручной аутентификации. Дополнительную информацию об области действия см. в разделе Настройка аутентификации пользователя с помощью Microsoft Entra ID.

User.Id

Предупреждение

Эта переменная не обязательно содержит значение. Протестируйте с пользователем от вашего поставщика удостоверений, чтобы убедиться, что тема работает правильно.

Переменная User.Id содержит идентификатор пользователя, хранящийся в поставщике удостоверений. Используйте это значение в потоках Power Automate для вызова API, которые принимают UserID в качестве значения.

Microsoft Copilot Studio автоматически устанавливает значение User.DisplayName из утверждения sub, предоставленного поставщиком удостоверений.

User.IsLoggedIn

User.IsLoggedIn — это переменная логического типа, в которой хранится статус входа пользователя. Значение true указывает, что пользователь вошел в систему. Вы можете использовать эту переменную для создания логики ветвления в своих темах, которая проверяет успешный, или для извлечения информации о пользователе, только если пользователь вошел в систему.

User.AccessToken

Предупреждение

Убедитесь, что вы передаете переменную User.AccessToken только для доверенных источников. Она содержит информацию об аутентификации пользователя, которая, если она скомпрометирована, может нанести вред пользователю.

Переменная User.AccessToken содержит токен пользователя, полученный после входа пользователя в систему. Вы можете передать эту переменную в потоки Power Automate, чтобы они могли подключаться к серверным API-интерфейсам и получать информацию о пользователе или выполнять действия от имени пользователя.

Не используйте User.AccessToken в узлах Сообщение или в потоках, которым вы не доверяете.

SignInReason

SignInReason— это переменная типа "выбор", которая указывает, когда пользователь должен войти в систему. Возможные значения:

• SignInRequired указывает, что пользователь должен войти в систему в начале разговора, используя системную тему Signin. Параметр Требовать входа для пользователей должен быть включен.

• Initializer указывает, что если пользователь еще не вошел в систему и достигает точки в беседе, в которой используются переменные проверки подлинности, пользователю будет предложено войти в систему.

Классическое

Переменные аутентификации

Если для вашего бота настроен вариант аутентификации Только для Teams и Power Apps или Вручную, в ваших темах будет доступен набор переменных аутентификации. См. документацию по настройке аутентификации для получения дополнительной информации о том, как настроить аутентификацию в вашем боте.

В следующей таблице сравнивается доступность переменных аутентификации по параметрам конфигурации аутентификации:

Переменная аутентификации	Нет аутентификации	Только для Teams и Power Apps	Вручную
UserDisplayName	❌	✔️	✔️
UserID	❌	✔️	✔️
IsLoggedIn	❌	❌	✔️
AuthToken	❌	❌	✔️

Переменная UserDisplayName

Переменная UserDisplayName содержит отображаемое имя пользователя, хранящееся в поставщике удостоверений. Вы можете использовать эту переменную для приветствия или обращения к конечному пользователю без необходимости явно сообщать об этом боту, что делает его более персонализированным.

Это значение поля получается из утверждения Microsoft Entra ID name. Для поставщиков OAuth это значение хранится в запросе name. Microsoft Copilot Studio автоматически извлекает это поле в переменную, поэтому убедитесь, что у вас есть profile как часть настройки области аутентификации.

Переменная UserID

Переменная UserID содержит идентификатор пользователя, хранящийся в поставщике удостоверений. Это значение может использоваться потоками Power Automate для вызова API, которые принимают UserID в качестве значения. Это значение поля получается из утверждения Microsoft Entra ID sub. Для поставщиков OAuth это значение хранится в запросе sub. Microsoft Copilot Studio автоматически извлекает это поле в переменную.

Предупреждение

Не гарантируется, что переменные UserDisplayName и UserID будут заполнены, они могут быть пустыми строками в зависимости от конфигурации пользователей в поставщике удостоверений. Протестируйте с пользователем от вашего поставщика удостоверений, чтобы убедиться, что ваши темы работают правильно, даже если эти переменные пусты.

Переменная IsLoggedIn

В переменной IsLoggedIn указывается, вошел ли пользователь в систему (либо в результате входа в систему, либо уже вошел в систему, также известный как путь успешного входа в систему) или не вошел в систему (что приведет к пути неудачного входа в систему).

IsLoggedIn — это переменная логического типа, содержащая статус входа пользователя. Вы можете использовать эту переменную для создания логики ветвления в своих темах, которая проверяет успешный вход (например, в шаблоне, уже предоставленном как часть добавления узла Проверить подлинность), или для рационального извлечения информации о пользователе, только если пользователь вошел в систему.

Переменная AuthToken

Переменная AuthToken содержит токен пользователя, полученный после входа пользователя в систему. Вы можете передать эту переменную в потоки Power Automate, чтобы они могли подключаться к серверным API-интерфейсам и получать информацию о пользователе или выполнять действия от имени пользователя.

Предупреждение

Убедитесь, что вы передаете переменную AuthToken только для доверенных источников. Она содержит информацию об аутентификации пользователя, которая, если она скомпрометирована, может нанести вред пользователю.

Не используйте AuthToken внутри узлов Сообщение или в потоках, которым вы не доверяете.

Проверка переменных аутентификации

По умолчанию панель Тестирование бота будет использовать учетную запись текущего вошедшего в систему пользователя для заполнения переменных UserDisplayName и UserID. Однако при тестировании тем, в которых используется проверка подлинности, вы можете захотеть использовать другие значения для этих переменных (или даже пустое значение).

Например, вы можете захотеть проверить, как используются специальные символы или что происходит, если переменная пуста.

Это относится только к панели Тестирование бота; вы не можете использовать команды, описанные в этом разделе, в опубликованном боте, развернутом на канале.

В следующей таблице перечислены команды, которые будут заполнять эти переменные. Введите команду на панели Тестирование бота, как если бы вы обычно разговаривали с ботом. В случае успеха вы получите подтверждающее сообщение от бота. Если ваш бот не использует аутентификацию, вы получите сообщение об ошибке.

Если вы сбросите панель Тестирование бота (или вы вносите изменения в тему, которые вызывают автоматический сброс панели Тестирование бота), вам нужно будет отправить команды еще раз.

Переменная	Команда настраиваемого значения	Команда пустого (отсутствующего) значения
UserDisplayName	/debug set bot.UserDisplayName "Value"	/debug set bot.UserDisplayName ""
UserID	Недоступно	/debug set bot.UserID ""

Внимание

Вы не можете заполнить переменную UserID с настраиваемым значением (кроме пустого или отсутствующего значения) из соображений безопасности.

Аутентификация при использовании конфигурации «Только для Teams и Power Apps»

Если вы используете вариант аутентификации Только для Teams и Power Apps, вам не нужно явно добавлять аутентификацию в свои темы. В этой конфигурации любой пользователь в Microsoft Teams автоматически входит в систему с использованием учетных данных Teams, и ему не нужно явно входить в систему с помощью карточки аутентификации. Если для параметра аутентификации задано значение «Вручную», вам потребуется добавить узел аутентификации (даже для канала Teams).

Заметка

Если вы используете вариант аутентификации Только для Teams и Power Apps, у вас нет возможности явно добавить аутентификацию в свои темы.

Добавление аутентификации конечных пользователей в тему

Узел Аутентификация предложит пользователю войти в систему с картой входа. Если пользователь уже вошел в систему, ему не будет предложено снова войти, даже если он достигнет другого узла проверки подлинности.

Когда пользователь вводит свое имя пользователя и пароль в приглашении (размещенном у поставщика удостоверений), ему может быть предложено ввести проверочный код, в зависимости от канала. Некоторые каналы, такие как Microsoft Teams, не требуют от пользователя ввода кода проверки.

Когда у вашего бота настроен единый вход, пользователю не будет предлагаться войти в систему.

Чтобы добавить узел аутентификации в вашу тему:

1. Перейдите на страницу тем для бота, которого вы хотите редактировать.

2. Откройте Холст разработки для темы, к которой вы хотите добавить шаблон аутентификации.

   Заметка

   Если ваш бот подключен к Dynamics 365 Customer Service, узел аутентификации не может быть частью пути разговора, по которому бот следует при первоначальном приветствии пользователей, — иначе карточка входа будет показана дважды. Вместо этого вы должны добавить узел аутентификации к другой теме, который запускается ответом пользователя.

3. Выберите Добавить узел (+), чтобы добавить узел сообщения. Введите то, что бот должен сказать, чтобы указать, что взаимодействие входа собирается произойти.

   

4. Под узлом сообщения выберите Добавить узел (+), выберите Вызвать действие, затем выберите Аутентификация.

   

   Заметка

   Узел Аутентифицировать доступен только в окне выбора действий в конце дерева диалога (как листовой узел). Его нельзя добавить в середину диалога. После добавления под ним могут быть добавлены другие узлы.

5. После выбора ряд новых узлов будут добавлены автоматически. Эти узлы включают родительский узел Аутентификация, за которым следуют узлы как для успешного, так и для неудачного пути.

   

Использование AuthToken без узла проверки подлинности

Переменные IsLoggedIn и AuthToken доступны, даже если вы не используете шаблон, предоставленный пунктом меню Вызов действия. Если вы передадите переменную AuthToken без предварительного прохождения пользователем через узел Проверить подлинность, пользователю будет предложено войти на этом этапе.

Передача этой переменной AuthToken может быть полезна, если вы всегда ожидаете, что пользователь вошел в систему, или если ваш пользователь перенаправляется из другой темы. Мы предлагаем вам использовать шаблон, предоставленный записью Вызов действия, для обработки случаев, когда пользователь не вошел в систему.

Заметка

Если пользователь выходит из системы в середине разговора, ему будет предложено войти снова, если тема приходит на узел, который использует переменную AuthToken.

Путь успеха

Путь успеха приравнивается к тому, где IsLoggedIn = True и учитывает случай, когда пользователь успешно вошел в систему (или вход в систему был уже выполнен).

Если у вас есть логика, которая использует переменную AuthToken (например, для подключения к серверной системе, использующей поток для получения информации о пользователе), она должна идти по этому пути.

Путь неудачи

Путь неудачи соответствует любому условию, кроме IsLoggedIn = True. В большинстве случаев путь сбоя возникает из-за того, что пользователь не смог войти в систему, использовал неверный пароль или отменил вход.

Добавьте любую логику, которая может потребоваться для обработки этого случая. В качестве примера мы предоставили варианты для повторения или передачи агенту-человеку. Настройте действия пути сбоя для вашего конкретного сценария и использования.

Тестирование вашей темы

Обязательно проверьте свою тему с использованием реального пользователя, настроенного в вашем поставщике идентификации. Убедитесь, что используются как путь успешного входа в систему, так и путь неудачи, чтобы не было неожиданностей, если ваш пользователь не может войти в систему или произошла ошибка взаимодействия входа провайдера идентификации.

См. также

Можно также использовать единый вход (SSO), чтобы вашим пользователям не приходилось входить в систему вручную. Дополнительные сведения см. в Настройка единого входа для Интернета.