Настройка единого входа с помощью Microsoft Entra ID

Внимание

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

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

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

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

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

Например, помощник размещается в корпоративной интрасети или в приложении, в которое пользователь уже вошел.

Существует четыре основных шага для настройки единого входа для Copilot Studio:

1. Создайте регистрацию приложения в Microsoft Entra ID для пользовательского холста.

2. Определите настраиваемую область действия для вашего помощника.

3. Настройка проверки подлинности в Copilot Studio для включения SSO.

4. Настройте HTML-код настраиваемого холста, чтобы включить SSO.

Важно

Единый вход в настоящее время не поддерживается, если помощник:

• Опубликован на веб-сайте SharePoint.
• Опубликован на портале Power Apps.

Поддерживаемые каналы

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

Канал	Поддерживается
Каналы службы Azure Bot	Неподдерживаемые
Пользовательский веб-сайт	Поддерживается
Демонстрационный веб-сайт	Неподдерживаемые
Facebook	Неподдерживаемые
Microsoft Teams1	Поддерживается
Мобильное приложение	Неподдерживаемые
Многоканальное взаимодействие для Customer Service2	Поддерживается

¹ Если у вас включен также канал Teams, вам необходимо следовать инструкциям по настройке из документации Настройка единого входа для канала Teams. Если вы не настроите параметры единого входа Teams в соответствии с инструкциями на упомянутой странице, проверка подлинности ваших пользователей всегда будет неуспешной при использовании канала Teams.

² Поддерживается только канал чата в реальном времени. Дополнительная информация: Настройте передачи в Dynamics 365 Customer Service.

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

Создание регистраций приложений для пользовательского веб-сайта

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

• Регистрация приложения для аутентификации, которая позволяет Microsoft Entra ID аутентифицировать пользователя для вашего помощника
• Регистрация приложения на основе холста, которая включает единый вход для вашей пользовательской веб-страницы

Мы не рекомендуем повторно использовать одну и ту же регистрацию приложения для помощника и пользовательского веб-сайта по соображениям безопасности.

1. Выполните инструкции в разделе Настройка проверки подлинности пользователей с помощью Microsoft Entra ID, чтобы создать регистрацию аутентификации приложения.
2. Следуйте тем же инструкциям еще раз, чтобы создать вторую регистрацию приложения, которая будет служить регистрацией вашего приложения на основе холста.
3. Вернитесь к этой статье.

Настройка регистрации приложения на основе холста

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

2. В Конфигурации платформы выберите Добавить платформу, затем выберите Интернет.

3. В разделе URI перенаправления введите URL-адрес своей веб-страницы, например, http://contoso.com/index.html.

   

4. В разделе Потоки неявного предоставления и гибридные потоки включите оба маркера Маркеры доступа (используются для неявных потоков) и Маркеры идентификаторов (используемые для неявных и гибридных потоков).

5. Выберите Настроить.

Найдите URL-адрес конечной точки токена вашего помощника

1. в Copilot Studio перейдите в Параметры, затем выберите Каналы.

2. Выберите Мобильное приложение.

3. В разделе Конечная точка токена выберите Копировать.

   

Настройка единого входа на веб-странице

Используйте код, который можно найти в репозитории GitHub Copilot Studio, для создания веб-страницы для URL-адреса перенаправления. Скопируйте код из репозитория GitHub и внесите в него изменения, следуя инструкциям ниже.

1. Перейдите на страницу Обзор на портале Azure и скопируйте Идентификатор приложения (клиента) и Идентификатор каталога (клиента) из регистрации приложения на основе холста.

   

2. Чтобы настроить Библиотеку проверки подлинности Майкрософт (MSAL):

   • Назначьте clientId своему ИД приложения (клиента).
   • Назначьте authority адресу https://login.microsoftonline.com/ и добавьте в конце ИД каталога (арендатора).

   Например:

   var clientApplication;
       (function (){
       var msalConfig = {
           auth: {
               clientId: '692e92c7-xxxx-4060-76d3-b381798f4d9c',
               authority: 'https://login.microsoftonline.com/7ef988bf-xxxx-51af-01ab-2d7fd011db47'     
           },
   

3. Задайте для переменной theURL URL-адрес конечной точки токена, который вы скопировали ранее. Например:

   (async function main() {
   
       var theURL = "https://1c0.0.environment.api.powerplatform.com/powervirtualagents/bots/5a099fd/directline/token?api-version=2022-03-01-preview"
   

4. Измените значение 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);
   

5. Сохранение изменений.

Тестирование помощника с использованием веб-страницы

1. Откройте свою веб-страницу в браузере.

2. Выберите Войти.

   

   Заметка

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

   Открывается новая вкладка браузера.

3. Перейдите на новую вкладку и скопируйте проверочный код.

4. Вернитесь на вкладку со своим помощником и вставьте код проверки в разговор с помощником.

Связанные статьи

• Регистрация приложения Azure

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

Технический обзор

На следующем рисунке показано, как пользователь вошел в систему, не увидев приглашения для входа в систему (SSO) в Copilot Studio:

1. Пользователь помощника вводит фразу, которая запускает тему входа. Тема входа предназначена для входа пользователя в систему и использования аутентифицированного токена (переменная AuthToken) пользователя.

2. Copilot Studio отправляет запрос на вход в систему, чтобы пользователь мог войти в систему с помощью своего настроенного поставщика удостоверений.

3. Пользовательский холст помощника перехватывает приглашение на вход и запрашивает токен от имени (OBO) от Microsoft Entra ID. Холст отправляет токен помощнику.

4. При получении токена OBO помощник обменивает токен OBO на «маркер доступа» и заполняет переменную AuthToken, используя значение маркера доступа. Переменная IsLoggedIn также устанавливается в это время.

Создайте регистрацию приложения в Microsoft Entra ID для пользовательского холста

Чтобы включить систему единого входа, вам потребуются две отдельные регистрации приложений:

• Один для вашего помощника, чтобы включить аутентификацию пользователя с помощью Microsoft Entra ID.
• Один для вашего пользовательского холста, чтобы включить SSO.

Важно

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

Создание регистрации приложения для холста помощника

1. Войдите на портал Azure.

2. Перейдите к регистрациям приложений, либо выбрав значок, либо выполнив поиск в верхней панели поиска.

   

3. Выберите Создать регистрацию.

   

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

   Например, если ваш помощник называется "Справка по продажам Contoso" (Contoso sales help), вы можете назвать регистрацию приложения как "ContosoSalesCanvas" или что-то подобное.

5. Выберите тип учетной записи в Поддерживаемые типы учетных записей. Мы рекомендуем вам выбрать Учетные записи в любом каталоге организации (любой каталог Microsoft Entra ID — несколько клиентов) и личные учетные записи Майкрософт (например, Skype, Xbox).

6. Оставьте раздел URI перенаправления пока пустым, так как вы вводите эту информацию на следующих шагах. Выберите Зарегистрировать.

   

7. После завершения регистрации она открывается для странице Обзор. Перейдите к Манифест. Подтвердите, что accessTokenAcceptedVersion задано как 2. Если это не так, измените его на 2, а затем выберите Сохранить.

Добавление URL-адреса перенаправления

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

   

2. В колонке Настройка платформ выберите Интернет.

   

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

4. Выберите Настроить, чтобы подтвердить изменения.

   

5. Перейти к пункту Разрешения API. Выберите Предоставить согласие администратора для <имя вашего клиента>, затем Да.

   Внимание

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

   

Определите настраиваемую область действия для вашего помощника

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

Этот шаг создает отношение доверия между регистрацией приложения аутентификации для аутентификации и регистрацией приложения для вашего пользовательского холста.

1. Откройте регистрацию приложения, созданную вами при настройке аутентификации.

2. Перейдите к пункту Разрешения API и убедитесь, что для вашего помощника добавлены правильные разрешения. Выберите Предоставить согласие администратора для <имя вашего клиента>, затем Да.

   Внимание

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

3. Перейдите к пункту Предоставление API и выберите Добавить область.

   

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

   

5. Выберите Добавить клиентское приложение.

6. Введите Идентификатор приложения (клиента) со страницы Обзор для регистрации приложения на основе холста в поле Идентификатор клиента. Установите флажок для указанной области, которую вы создали.

7. Выберите Добавить приложение.

Настройка проверки подлинности в Copilot Studio для включения SSO

URL-адрес обмена токенами на странице конфигурации аутентификации Copilot Studio используется для обмена токена OBO на запрошенный маркер доступа через платформу ботов bot framework.

Copilot Studio вызывает Microsoft Entra ID для осуществления фактического обмена.

1. Выполните вход в Copilot Studio.

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

3. В меню навигации в разделе Параметры выберите Безопасность. Затем выберите карточку Аутентификация.

   

4. Введите полный URI области из колонки Предоставление API для регистрации приложения аутентификации помощника в поле URL-адрес обмена токенами. URI-адрес канала в формате: api://1234-4567/scope.name.

   

   

5. Выберите Сохранить, затем опубликуйте содержимое помощника.

Настройте HTML-код настраиваемого холста, чтобы включить SSO

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

1. Настройте библиотеку Microsoft Authentication Library (MSAL), добавив следующий код в тег <script> в разделе <head>.

2. Обновите clientId, указав Идентификатор приложения (клиента) для регистрации приложения на основе холста. Замените <Directory ID> на Идентификатор каталога (клиента). Вы получаете эти идентификаторы со страницы Обзор для регистрации приложения холста.

   

   <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>
   

3. Вставьте следующей тег <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>
   

4. Вставьте следующей тег <script> в раздел <body>. В методе main этот код добавляет условие к вашему store, с уникальным идентификатором вашего помощника. Он также генерирует уникальный идентификатор как вашу переменную userId.

5. Обновите <COPILOT ID>, указав идентификатор вашего помощника. Вы можете увидеть идентификатор своего помощника, перейдя на вкладку "Каналы" для бота, который вы используете, и выбрав Мобильное приложение на портале Copilot Studio.

   

   <script>
       (async function main() {
   
           // Add your COPILOT 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') {
                                           // copilot 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 и сохранить условные сценарии, которые уже включены в нашем репозитории GitHub.