Copilot Studio поддерживает единый вход. Единый вход позволяет агентам на вашем веб-сайте входить в систему клиентов, если они уже вошли на страницу или в приложение, где развернут агент.
Например, агент размещается в корпоративной интрасети или в приложении, в которое пользователь уже вошел.
Существует пять основных шагов для настройки единого входа для Copilot Studio:
Включение ручной аутентификацию для агента с помощью Microsoft Entra ID
Создайте регистрацию приложения в Microsoft Entra ID для пользовательского холста.
Определите настраиваемую область для агента в Microsoft Entra ID.
Добавьте пользовательскую область в конфигурацию агента.
Настройте код на стороне клиента пользовательского холста, чтобы включить единый вход
Предварительные требования
Поддерживаемые каналы
В следующей таблице описаны каналы, которые в настоящее время поддерживают SSO. Вы можете предложить поддержку для дополнительных каналов на форуме идей Copilot Studio.
1 Если вы публикуете в канале Teams, необходимо следовать инструкциям по конфигурации Configure single sign-on с Microsoft Entra ID for agents в документации Microsoft Teams. Если вы не настроите параметры единого входа Teams в соответствии с инструкциями на упомянутой странице, проверка подлинности ваших пользователей всегда будет неуспешной при использовании канала Teams.
2 Поддерживается только канал чата в реальном времени. Дополнительная информация: Настройте передачи в Dynamics 365 Customer Service.
Внимание!
SSO в настоящее время не поддерживается, когда агент публикуется на портале Power Apps.
Создание регистраций приложений для пользовательского веб-сайта
Чтобы включить SSO, создайте две отдельные регистрации приложений:
-
Регистрация приложения для проверки подлинности, которая включает идентификацию пользователя по Microsoft Entra ID для агента
-
Регистрация приложения на основе холста, которая включает единый вход для вашей пользовательской веб-страницы
Из соображений безопасности не используйте одну и ту же регистрацию приложения как для вашего агента, так и для вашего собственного сайта.
Чтобы создать регистрацию приложения аутентификации, следуйте инструкциям в Настройте аутентификацию пользователя с помощью Microsoft Entra ID.
Создайте вторую регистрацию в приложении, которая будет служить регистрацией на Canvas.
Добавление URL-адреса обмена токенами
Чтобы обновить настройки аутентификации Microsoft Entra ID в Copilot Studio, добавьте URL обмена токенами, чтобы ваше приложение и Copilot Studio могли обмениваться информацией.
В Azure портале на странице регистрации вашего приложения для аутентификации перейдите в Expose an API.
В разделе Области выберите значок Копировать в буфер обмена.
В меню навигации Copilot Studio в разделе Параметры выберите Безопасность, а затем выберите плитку Аутентификация.
Для URL-адреса обмена токенами (требуется для SSO) вставьте область, которую вы скопировали ранее.
Выберите Сохранить.
В Azure портале, на странице регистрации приложения для аутентификации, перейдите по Обзор.
Скопируйте значение ID приложения (клиента ) в разделе Essentials.
На панели навигации выберите Manage>Expose an API.
В разделе «Авторизованные клиентские приложения» выберите « Добавить клиентское приложение», затем вставьте скопированный идентификатор клиента.
Выберите Сохранить.
После создания регистрации приложения на основе холста перейдите на страницу Аутентификация, затем выберите Добавить платформу.
В Конфигурации платформы выберите Добавить платформу, затем выберите SPA.
В разделе Redirect URI введите URL вашей веб-страницы. Например: http://contoso.com/index.html.
В разделе Потоки неявного предоставления и гибридные потоки включите оба маркера Маркеры доступа (используются для неявных потоков) и Маркеры идентификаторов (используемые для неявных и гибридных потоков).
Выберите Настроить.
Поиск URL-адреса конечной точки токена вашего агента
Откройте ваш агент в Copilot Studio и выберите Каналы.
Выберите Мобильное приложение.
В разделе Конечная точка токена выберите Копировать.
Настройка единого входа на веб-странице
Внимание!
Гостевые пользователи не могут получить доступ к ответам, сгенерированным ИИ, из источников данных SharePoint и Graph Connector в приложениях с поддержкой SSO.
Используйте код, предоставленный в Copilot Studio Samples GitHub repo чтобы создать веб-страницу для URL перенаправления. Скопируйте код из репозитория GitHub и измените его, используя следующие инструкции.
Перейдите на страницу Обзор на портале Azure и скопируйте Идентификатор приложения (клиента) и Идентификатор каталога (клиента) из регистрации приложения на основе холста.
Чтобы настроить Библиотеку проверки подлинности Майкрософт (MSAL):
- Назначьте
clientId своему ИД приложения (клиента).
- Назначьте
authority адресу https://login.microsoftonline.com/ и добавьте в конце ИД каталога (арендатора).
Например:
var clientApplication;
(function (){
var msalConfig = {
auth: {
clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
authority: 'https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
},
Задайте для переменной theURL URL-адрес конечной точки токена, который вы скопировали ранее. Например:
(async function main() {
var theURL = "https://<token endpoint URL>"
Измените значение userId так, чтобы оно включало в себя пользовательский префикс. Например:
var userId = clientApplication.account?.accountIdentifier != null ?
("My-custom-prefix" + clientApplication.account.accountIdentifier).substr(0, 64)
: (Math.random().toString() + Date.now().toString()).substr(0,64);
Сохранение изменений.
Убедитесь, что успешно настроили SSO.
При тестировании вашего агента, если SSO не настроен успешно, вам предлагают войти. Процесс входа даёт код валидации, который нужно скопировать в окно чата.
Если вы видите запрос на вход, убедитесь, что вы правильно выполнили шаги с 1 по 5 этой процедуры. Если SSO успешно настроен, вам не предлагают войти.
Заметка
Код в репозитории GitHub требует от пользователей выбрать кнопку входа. В продакшене возможно заменить функцию кнопок на более подходящее событие, например, переключение на страницу.
Связанный контент
Технический обзор
Следующая иллюстрация показывает, как пользователь входит в систему, не увидев подсказку входа (SSO) в Copilot Studio:
Пользователь агента вводит фразу, которая запускает тему входа. Тема входа предназначена для входа пользователя в систему и использования аутентифицированного токена (переменная User.AccessToken) пользователя.
Copilot Studio отправляет запрос на вход, позволяющий пользователю войти с помощью заданного провайдера идентификации.
Пользовательский холст агента перехватывает приглашение на вход и запрашивает токен от имени (OBO) от Microsoft Entra ID. Холст отправляет токен агенту.
После получения токена OBO агент меняет его на «токен доступа» и заполняет AuthToken переменную, используя значение токена доступа. Переменная IsLoggedIn также устанавливается в это время.
Создайте регистрацию приложения в Microsoft Entra ID для пользовательского холста
Чтобы включить систему единого входа, вам потребуются две отдельные регистрации приложений:
Внимание!
Вы не можете повторно использовать одну и ту же регистрацию приложения как для аутентификации пользователя вашего агента, так и для вашего пользовательского холста.
Создание регистрации приложения для холста агента
Войдите на портал Azure.
Перейдите к регистрациям приложений, либо выбрав значок, либо выполнив поиск в верхней панели поиска.
Выберите Создать регистрацию.
Введите имя регистрации. Используйте имя агента, чей canvas вы регистрируете, и добавьте «canvas», чтобы отделить его от регистрации приложения для аутентификации.
Например, если ваш агент называется "Справка по продажам Contoso" (Contoso sales help), вы можете назвать регистрацию приложения как "ContosoSalesCanvas" или что-то подобное.
В разделе Поддерживаемые типы учетных записей выберите Учетные записи в клиенте организации (любой каталог Microsoft Entra ID — с несколькими клиентами) и личные учетные записи Microsoft (например, Skype, Xbox).
Оставьте раздел URI перенаправления пока пустым, так как вы вводите эту информацию на следующих шагах. Выберите Зарегистрировать.
После завершения регистрации она открывается для странице Обзор. Перейдите к Манифест. Подтвердите, что accessTokenAcceptedVersion задано как 2. Если это не так, измените его на 2, а затем выберите Сохранить.
Добавление URL-адреса перенаправления
При открытой регистрации перейдите в Аутентификация, а затем выберите Добавить платформу.
В панели «Конфигурация платформ » выберите « Веб».
В разделе URI-адреса перенаправления добавьте полный URL-адрес на страницу, где размещен ваш холст чата. В разделе Неявное предоставление разрешения выберите флажки Токены идентификации и Токены доступа.
Выберите Настроить, чтобы подтвердить изменения.
Перейти к пункту Разрешения API. Выберите Предоставить согласие администратора для <имя вашего клиента>, затем Да.
Внимание!
Чтобы пользователям не требовалось давать согласие на каждое приложение, кто-то с ролью не менее администратора приложений или администратора облачных приложений может предоставлять согласие в рамках всего клиента для регистраций ваших приложений.
Определение пользовательской области для своего агента
Определите пользовательскую область, предоставив API для регистрации приложения на основе холста в рамках регистрации приложения аутентификации.
Области позволяют определять роли пользователя и администратора и права доступа.
Этот шаг создает отношение доверия между регистрацией приложения аутентификации для аутентификации и регистрацией приложения для вашего пользовательского холста.
Откройте регистрацию приложения, созданную вами при настройке аутентификации.
Перейдите к пункту Разрешения API и убедитесь, что для вашего агента добавлены правильные разрешения. Выберите Предоставить согласие администратора для <имя вашего клиента>, затем Да.
Внимание!
Чтобы пользователям не требовалось давать согласие на каждое приложение, кто-то с ролью не менее администратора приложений или администратора облачных приложений может предоставлять согласие в рамках всего клиента для регистраций ваших приложений.
Перейдите к пункту Предоставление API и выберите Добавить область.
Введите название телескопа вместе с информацией, которую пользователи видят на экране SSO. Выберите Добавить область.
Выберите Добавить клиентское приложение.
Введите Идентификатор приложения (клиента) со страницы Обзор для регистрации приложения на основе холста в поле Идентификатор клиента. Выберите галочку для указанного объёма, который вы создали.
Выберите Добавить приложение.
Используйте Token Exchange URL на странице конфигурации аутентификации Copilot Studio, чтобы exchange токен OBO для запрошённого токена доступа через фреймворк бота.
Copilot Studio вызывает Microsoft Entra ID для осуществления фактического обмена.
Выполните вход в Copilot Studio.
Убедитесь, что выбрали агента, для которого хотите включить аутентификацию, выбрав иконку агента в верхнем меню и выбрав правильного агента.
В меню навигации в разделе Параметры выберите Безопасность. Затем выберите карточку Аутентификация.
Введите полный URI с страницы Expose an API для регистрации приложения аутентификации агента в поле URL обмена токенами . URI-адрес канала в формате: api://1234-4567/scope.name.
Выберите Сохранить, затем опубликуйте содержимое агента.
Обновите пользовательскую страницу холста, где находится агент, чтобы перехватить запрос на карту входа и обменять токен OBO.
Настройте библиотеку Microsoft Authentication Library (MSAL), добавив следующий код в тег <script> в разделе <head>.
Обновите clientId, указав Идентификатор приложения (клиента) для регистрации приложения на основе холста. Замените <Directory ID> на Идентификатор каталога (клиента). Получите эти идентификаторы (ID) на странице обзора регистрации приложения Canvas.
<head>
<script>
var clientApplication;
(function () {
var msalConfig = {
auth: {
clientId: '<Client ID [CanvasClientId]>',
authority: 'https://login.microsoftonline.com/<Directory ID>'
},
cache: {
cacheLocation: 'localStorage',
storeAuthStateInCookie: false
}
};
if (!clientApplication) {
clientApplication = new Msal.UserAgentApplication(msalConfig);
}
} ());
</script>
</head>
Вставьте следующей тег <script> в раздел <body>. Этот скрипт вызывает метод для извлечения resourceUrl и обмена вашего текущего токена на токен, запрошенный в приглашении OAuth.
<script>
function getOAuthCardResourceUri(activity) {
if (activity &&
activity.attachments &&
activity.attachments[0] &&
activity.attachments[0].contentType === 'application/vnd.microsoft.card.oauth' &&
activity.attachments[0].content.tokenExchangeResource) {
// asking for token exchange with Microsoft Entra ID
return activity.attachments[0].content.tokenExchangeResource.uri;
}
}
function exchangeTokenAsync(resourceUri) {
let user = clientApplication.getAccount();
if (user) {
let requestObj = {
scopes: [resourceUri]
};
return clientApplication.acquireTokenSilent(requestObj)
.then(function (tokenResponse) {
return tokenResponse.accessToken;
})
.catch(function (error) {
console.log(error);
});
}
else {
return Promise.resolve(null);
}
}
</script>
Вставьте следующей тег <script> в раздел <body>. В методе main этот код добавляет условие к вашему store, с уникальным идентификатором вашего агента. Он также генерирует уникальный идентификатор как вашу переменную userId.
Обновите <BOT ID>, указав идентификатор вашего агента. Чтобы увидеть ID вашего агента в Copilot Studio, перейдите на страницу Channels для вашего агента и выберите Мобильное приложение.
<script>
(async function main() {
// Add your BOT ID below
var BOT_ID = "<BOT ID>";
var theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;
const {
token
} = await fetchJSON(theURL);
var directline = await fetchJSON(regionalChannelSettingsURL).then(res=> res.channelUrlsById.directline);
const directLine = window.WebChat.createDirectLine({
domain: `${directline}v3/directline`,
token
});
var userID = clientApplication.account?.accountIdentifier != null ?
("Your-customized-prefix-max-20-characters" + clientApplication.account.accountIdentifier).substr(0, 64) :
(Math.random().toString() + Date.now().toString()).substr(0, 64); // Make sure this will not exceed 64 characters
const store = WebChat.createStore({}, ({
dispatch
}) => next => action => {
const {
type
} = action;
if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
dispatch({
type: 'WEB_CHAT/SEND_EVENT',
payload: {
name: 'startConversation',
type: 'event',
value: {
text: "hello"
}
}
});
return next(action);
}
if (action.type === 'DIRECT_LINE/INCOMING_ACTIVITY') {
const activity = action.payload.activity;
let resourceUri;
if (activity.from && activity.from.role === 'bot' &&
(resourceUri = getOAuthCardResourceUri(activity))) {
exchangeTokenAsync(resourceUri).then(function(token) {
if (token) {
directLine.postActivity({
type: 'invoke',
name: 'signin/tokenExchange',
value: {
id: activity.attachments[0].content.tokenExchangeResource.id,
connectionName: activity.attachments[0].content.connectionName,
token,
},
"from": {
id: userID,
name: clientApplication.account.name,
role: "user"
}
}).subscribe(
id => {
if (id === 'retry') {
// The agent was not able to handle the invoke, so display the oauthCard
return next(action);
}
// else: tokenexchange successful and we do not display the oauthCard
},
error => {
// an error occurred to display the oauthCard
return next(action);
}
);
return;
} else
return next(action);
});
} else
return next(action);
} else
return next(action);
});
const styleOptions = {
// Add styleOptions to customize Web Chat canvas
hideUploadButton: true
};
window.WebChat.renderWebChat({
directLine: directLine,
store,
userID: userID,
styleOptions
},
document.getElementById('webchat')
);
})().catch(err => console.error("An error occurred: " + err));
</script>
Полный пример кода
Вы можете найти полный пример кода с MSAL и хранить условные скрипты, уже включённые в Copilot Studio Samples GitHub repo.