Добавьте аутентификацию пользователя в тему, чтобы ваши клиенты могли войти прямо в разговор. Вы можете затем персонализировать разговор с помощью пользовательских переменных и получить доступ к серверным системам от имени пользователя.
Вам необходимо настроить аутентификацию пользователя с помощью Microsoft Entra ID, прежде чем вы сможете использовать аутентификацию в своих темах.
Выполните инструкции в разделе Настройка аутентификации пользователя с помощью Microsoft Entra ID.
Добавление проверки подлинности с системной темой "Вход"
Когда вы создаете агент, Copilot Studio автоматически добавляет системную тему под названием Вход. Чтобы использовать ее, вы должны установить аутентификацию вашего агента вручную и потребовать от пользователей входа в систему. Когда клиент начинает разговор с агентом, срабатывает тема Вход и предлагает пользователю войти в систему. Вы можете настроить тему Вход в соответствии с потребностями вашего агента.
Внимание!
Рекомендуется использовать тему Вход в систему только для предоставления метода проверки подлинности, предоставляемого Copilot Studio. Ее не следует изменять для вызова каких-либо других действий или потоков или других методов аутентификации.
Откройте агент в Copilot Studio, выберите Параметры в верхней части страницы, затем выберите Безопасность.
Выберите Аутентификация.
Выберите Аутентификация вручную, а затем выберите Требовать входа для пользователей.
Настройте все поля аутентификации вручную по мере необходимости.
Выберите Сохранить.
Добавление проверки подлинности с пользовательской логикой
Тема Вход проверяет подлинность пользователя в начале разговора. Чтобы позволить пользователю войти в систему позже, вы можете добавить узел Аутентификация к любой пользовательской теме.
Когда клиенты вводят свое имя пользователя и пароль, им может быть предложено ввести код проверки. После входа в систему запрос больше не отображается, даже если они достигают другого узла Проверка подлинности.
Выберите Параметры вверху страницы, затем выберите Безопасность.
Выберите плитку Проверка подлинности.
Заметка
Вы должны выбрать Аутентификация вручную, чтобы добавить аутентификацию пользователя в пользовательскую тему.
Снимите флажок Требовать входа для пользователей.
Настройте все поля аутентификации вручную по мере необходимости.
Выберите Сохранить.
Выберите Темы в верхней части страницы.
Выберите Добавить узел ( 
) >Расширенные>Аутентификация.
Протестируйте тему, используя пользователя, настроенного в вашем поставщике удостоверений.
Совет
Важно создать пути как для успешного входа, так и для неудачного. Вход может завершиться сбоем по многим причинам, в том числе из-за ошибок при входе в систему поставщика удостоверений.
Переменные аутентификации
При настройке аутентификации пользователей для агента можно использовать переменные аутентификации в темах. В следующей таблице сравнивается доступность этих переменных в зависимости от выбранного варианта проверки подлинности.
Дополнительные сведения о переменных см. в разделе Обзор переменных.
| Переменная аутентификации |
Без аутентификации |
Проверка подлинности через Майкрософт |
Проверка подлинности вручную |
| User.DisplayName |
Недоступно |
На месте |
На месте |
| User.FirstName |
Недоступно |
На месте |
На месте |
| User.LastName |
Недоступно |
На месте |
На месте |
| User.PrincipalName |
Недоступно |
На месте |
На месте |
| User.Email |
Недоступно |
На месте |
На месте |
| User.Id |
Недоступно |
На месте |
На месте |
| User.IsLoggedIn |
Недоступно |
На месте |
На месте |
| User.AccessToken |
Недоступно |
Недоступно |
На месте |
| SignInReason |
Недоступно |
На месте |
На месте |
User.DisplayName
Предупреждение
Эта переменная не обязательно содержит значение. Протестируйте с пользователем от вашего поставщика удостоверений, чтобы убедиться, что тема работает правильно.
Переменная User.DisplayName содержит отображаемое имя, хранящееся в поставщике удостоверений. Используйте эту переменную для приветствия или обращения к пользователю без необходимости явно давать имя агенту, что делает разговор более персонализированным.
Copilot Studio автоматически устанавливает значение User.DisplayName из утверждения name, предоставленного поставщиком удостоверений, при условии, что область действия profile была определена при настройке ручной аутентификации. Дополнительную информацию об области действия см. в разделе Настройка аутентификации пользователя с помощью Microsoft Entra ID.
User.Id
Предупреждение
Эта переменная не обязательно содержит значение. Протестируйте с пользователем от вашего поставщика удостоверений, чтобы убедиться, что тема работает правильно.
Переменная User.Id содержит идентификатор пользователя, хранящийся в поставщике удостоверений. Используйте это значение в потоках Power Automate для вызова API, которые принимают UserID в качестве значения.
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 указывает, что когда пользователь не вошел в систему и достигает точки диалога, в которой используются переменные проверки подлинности, ему предлагается войти в систему.
Переменные аутентификации
Если ваш агент настроен на вариант Проверка подлинности в Microsoft или Вручную, в ваших темах будет доступен набор переменных аутентификации. Дополнительные сведения о том, как настроить проверку подлинности в агенте, см. в разделе Настройка проверки подлинности пользователей в Copilot Studio.
В следующей таблице сравнивается доступность переменных аутентификации по параметрам конфигурации аутентификации:
| Переменная аутентификации |
Без аутентификации |
Проверка подлинности через Майкрософт |
Вручную |
User.DisplayName |
❌ |
✔️ |
✔️ |
User.Id |
❌ |
✔️ |
✔️ |
User.IsLoggedIn |
❌ |
❌ |
✔️ |
User.AccessToken |
❌ |
❌ |
✔️ |
Переменная UserDisplayName
Переменная User.DisplayName содержит отображаемое имя пользователя, хранящееся в поставщике удостоверений. Вы можете использовать эту переменную для приветствия или обращения к клиенту без необходимости явно сообщать об этом агенту, что делает его более персонализированным.
Это значение поля получается из утверждения Microsoft Entra ID name. Для поставщиков OAuth это значение хранится в утверждении name. Copilot Studio автоматически извлекает это поле в переменную, поэтому убедитесь, что у вас есть profile как часть настройки области аутентификации.
Переменная UserID
Переменная User.Id содержит идентификатор пользователя, хранящийся в поставщике удостоверений. Потоки Power Automate могут использовать это значение для вызова API-интерфейсов, которые принимают UserID в качестве значения.
Это значение поля получается из утверждения Microsoft Entra ID sub. Для поставщиков OAuth это значение хранится в утверждении sub. Copilot Studio автоматически извлекает это поле в переменную.
Предупреждение
Не гарантируется, что переменные User.DisplayName и User.Id будут заполнены, они могут быть пустыми строками в зависимости от конфигурации пользователей в поставщике удостоверений. Протестируйте с пользователем от вашего поставщика удостоверений, чтобы убедиться, что ваши темы работают правильно, даже если эти переменные пусты.
Переменная IsLoggedIn
В переменной User.IsLoggedIn указывается, вошел ли пользователь в систему (либо в результате входа в систему, либо уже вошел в систему, также известный как путь успешного входа в систему) или не вошел в систему (что приведет к пути неудачного входа в систему).
User.IsLoggedIn — это логическая переменная, содержащая статус входа пользователя. Вы можете использовать эту переменную для создания логики ветвления в своих темах, которая проверяет успешный вход (например, в шаблоне, уже предоставленном как часть добавления узла Проверить подлинность), или для рационального извлечения информации о пользователе, только если пользователь вошел в систему.
Переменная User.AccessToken
Переменная User.AccessToken содержит токен пользователя, полученный после входа пользователя в систему. Вы можете передать эту переменную в потоки Power Automate, чтобы они могли подключаться к серверным API-интерфейсам и получать информацию о пользователе или выполнять действия от имени пользователя.
Предупреждение
Убедитесь, что вы передаете переменную User.AccessToken только для доверенных источников. Она содержит информацию об аутентификации пользователя, которая, если она скомпрометирована, может нанести вред пользователю.
Не используйте User.AccessToken внутри узлов Сообщение или в потоках, которым вы не доверяете.
Проверка переменных аутентификации
По умолчанию панель Тестирование бота использует учетную запись текущего вошедшего в систему пользователя для заполнения переменных User.DisplayName и User.Id. Однако при тестировании тем, в которых используется проверка подлинности, вы можете захотеть использовать другие значения для этих переменных (или даже пустое значение).
Например, вы можете захотеть проверить, как используются специальные символы или что происходит, если переменная пуста.
В следующей таблице перечислены команды, которые должны заполнять эти переменные. Эти команды относится только к панели Тестирование бота; вы не можете использовать их в опубликованном агенте, развернутом на канале.
Введите нужную команду на панели Тестирование бота, как если бы вы обычно разговаривали с агентом. В случае успеха вы получите подтверждающее сообщение от агента. Если ваш агент не использует аутентификацию, вы получите сообщение об ошибке.
Если вы сбросите панель Тестирование бота (или вы вносите изменения в тему, которые вызывают автоматический сброс панели Тестирование бота), вам нужно будет отправить команды еще раз.
| Переменная |
Команда настраиваемого значения |
Команда пустого (отсутствующего) значения |
User.DisplayName |
/debug set bot.UserDisplayName "Value" |
/debug set bot.UserDisplayName "" |
User.Id |
Недоступно |
/debug set bot.UserID "" |
Важно
Из соображений безопасности вы не можете заполнить переменную User.Id с настраиваемым значением (кроме пустого или отсутствующего значения).
Проверка подлинности при использовании "Проверка подлинности с помощью Microsoft"
Если ваш параметр аутентификации задан равным Проверка подлинности с помощью Microsoft, вам не нужно явно добавлять аутентификацию в свои темы. В этой конфигурации любой пользователь в Microsoft Teams автоматически входит в систему с использованием учетных данных Teams, и ему не нужно явно входить в систему с помощью карточки аутентификации. Если для параметра аутентификации задано значение Вручную, вы должны добавить узел Аутентификация (даже для канала Teams).
Заметка
Если для параметра аутентификации задано значение Проверка помощи с помощью Microsoft, вам не нужен вариант явного добавления аутентификации в свои темы.
Добавление аутентификации конечных пользователей в тему
Узел Проверка подлинности предлагает пользователю войти в систему с помощью карточки входа. После входа пользователю в систему этот запрос больше не отображается, даже если пользователь достигает другого узла Проверка подлинности.
Когда пользователь вводит свое имя пользователя и пароль в приглашении (размещенном у поставщика удостоверений), ему может быть предложено ввести проверочный код, в зависимости от канала. Некоторые каналы, такие как Microsoft Teams, не требуют от пользователя кода проверки.
Если у вашего агента настроен единый вход, пользователю не будет предлагаться войти в систему.
Чтобы добавить узел Проверка подлинности в вашу тему:
Перейдите на страницу Темы для агента, который вы хотите редактировать.
Откройте тему, к которой вы хотите добавить шаблон проверки подлинности.
Заметка
Если ваш агент подключен к Dynamics 365 Customer Service, узел аутентификации не может быть частью пути диалога, по которому агент следует при первоначальном приветствии пользователей; в противном случае карточка входа будет показана дважды. Вместо этого вы должны добавить узел Проверка подлинности к другой теме, который запускается ответом пользователя.
Выберите Добавить узел (+), чтобы добавить узел сообщения. Введите то, что агент должен сказать, чтобы указать, что взаимодействие входа собирается произойти.
Под узлом сообщения выберите Добавить узел (+), выберите Вызвать действие, затем выберите Аутентификация.
Заметка
Узел Аутентифицировать доступен только в окне выбора действий в конце дерева диалога (как листовой узел). Его нельзя добавить в середину диалога. После добавления под ним могут быть добавлены другие узлы.
Новый узлы появляются автоматически: родительский узел Аутентификация, за которым следуют узлы как для успешного, так и для неудачного пути.
Использование User.AccessToken без узла проверки подлинности
Переменные User.IsLoggedIn и User.AccessToken доступны, даже если вы не используете шаблон, предоставленный пунктом меню Вызов действия. Если вы передадите переменную User.AccessToken без предварительного прохождения пользователем через узел Проверить подлинность, пользователю будет предложено войти на этом этапе.
Передача этой переменной User.AccessToken может быть полезна, если вы всегда ожидаете, что пользователь вошел в систему, или если ваш пользователь перенаправляется из другой темы. Мы предлагаем вам использовать шаблон, предоставленный записью Вызов действия, для обработки случаев, когда пользователь не вошел в систему.
Заметка
Если пользователь выходит из системы в середине разговора, ему будет предложено войти снова, если тема приходит на узел, который использует переменную User.AccessToken.
Путь успеха
Путь успеха приравнивается к тому, где User.IsLoggedIn = True и учитывает случай, когда пользователь успешно вошел в систему (или вход в систему был уже выполнен).
Если у вас есть логика, которая использует переменную User.AccessToken (например, для подключения к серверной системе, использующей поток для получения информации о пользователе), она должна идти по этому пути.
Путь неудачи
Путь неудачи соответствует любому условию, кроме IsLoggedIn = True. В большинстве случаев путь сбоя возникает из-за того, что пользователь не смог войти в систему, использовал неверный пароль или отменил вход.
Добавьте любую логику, которая может потребоваться для обработки этого случая. В качестве примера мы предоставили варианты для повторения или передачи агенту-человеку. Настройте действия пути сбоя для вашего конкретного сценария и использования.
Тестирование вашей темы
Обязательно проверьте свою тему с использованием реального пользователя, настроенного в вашем поставщике идентификации. Убедитесь, что используются как путь успешного входа в систему, так и путь неудачи, чтобы не было неожиданностей, если ваш пользователь не может войти в систему или произошла ошибка взаимодействия входа провайдера идентификации.