Расширение приложения вкладки с помощью разрешений и областей Microsoft Graph

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

Области графа, такие как User.Read или Mail.Read, указывают, к чему ваше приложение может получить доступ из учетной записи пользователя Teams. Необходимо указать области в запросе на авторизацию. В этой статье описаны действия по настройке разрешений и областей Microsoft Graph для приложения вкладки Teams.

Настройка разрешений API в Идентификаторе Microsoft Entra

Вы можете настроить дополнительные области Graph в идентификаторе Microsoft Entra для приложения. Это делегированные разрешения, используемые приложениями, которым требуется доступ для входа. Пользователь или администратор приложения, выполнившего вход, должен сначала предоставить согласие на них. После этого приложение вкладки может предоставить согласие от имени вошедшего пользователя при вызове Microsoft Graph.

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

Чтобы настроить разрешения API:

1. Откройте приложение, зарегистрированное на портале Azure.

2. Выберите Управление>разрешениями API в области слева.

   

   Появится страница Разрешения API.

3. Выберите + Добавить разрешение , чтобы добавить разрешения API Microsoft Graph.

   

   Появится страница Запрос разрешений API.

4. Выберите Microsoft Graph.

   

   Отобразятся параметры разрешений Graph.

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

   

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

   

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

   В браузере появится сообщение о том, что разрешения обновлены.

   

   Добавленные разрешения отображаются на странице Разрешения API.

   

   Теперь вы настроили приложение с разрешениями Microsoft Graph.

Настройка проверки подлинности для разных платформ

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

Примечание.

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

Вы можете настроить проверку подлинности для нескольких платформ, если URL-адрес уникален.

Чтобы настроить проверку подлинности для платформы:

1. Откройте приложение, зарегистрированное на портале Azure.

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

   

   Появится страница Конфигурации платформ.

3. Выберите + Добавить платформу.

   

   Появится страница Настройка платформ.

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

   

   Можно настроить несколько платформ определенного типа. Убедитесь, что URI перенаправления уникален для каждой настраиваемой платформы.

   Появится страница "Настройка веб-платформы".

   Примечание.

   Конфигурации различаются в зависимости от выбранной платформы.

5. Введите сведения о конфигурации платформы.

   

   1. Введите URI перенаправления. URI должен быть уникальным.
   2. Введите URL-адрес выхода из внешнего канала.
   3. Выберите маркеры, которые вы хотите отправить идентификатору Microsoft Entra для приложения.

6. Нажмите Настроить.

   Платформа настраивается и отображается на странице Конфигурации платформ.

Получение маркера доступа для MS Graph

Необходимо получить маркер доступа для Microsoft Graph. Это можно сделать с помощью потока Microsoft Entra on-behalf-of (OBO).

Текущая реализация единого входа ограничена разрешениями уровня пользователя, которые недоступны для выполнения вызовов Graph. Чтобы получить разрешения и области, необходимые для вызова Graph, приложения единого входа должны реализовать пользовательскую веб-службу для обмена маркера, полученного из библиотеки JavaScript Teams, на маркер, включающий необходимые области. Для получения маркера со стороны клиента можно использовать библиотеку проверки подлинности Майкрософт (MSAL).

После настройки разрешений Graph в Microsoft Entra ID необходимо получить идентификатор маркера из клиента Teams, а затем обменять его с маркером на стороне сервера.

Получение идентификатора маркера из клиента Teams

Ниже приведен пример получения идентификатора маркера из клиента Teams.

microsoftTeams.authentication.getAuthToken().then((result) => {
    //result contains the id token
            console.log(result);
        })

Обмен идентификатором маркера с маркером на стороне сервера

Ниже приведен пример потока OBO для получения маркера доступа из клиента Teams с помощью MSAL:

C#

IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(<"Client id">)
                                                .WithClientSecret(<"Client secret">)
                                                .WithAuthority($"https://login.microsoftonline.com/<"Tenant id">")
                                                .Build();
            try
            {
                var idToken = <"Client side token">;
                UserAssertion assert = new UserAssertion(idToken);
                List<string> scopes = new List<string>();
                scopes.Add("https://graph.microsoft.com/User.Read");
                // Acquires an access token for this application (usually a Web API) from the authority configured in the application.
                var responseToken = await app.AcquireTokenOnBehalfOf(scopes, assert).ExecuteAsync();
                return responseToken.AccessToken.ToString();
            }
            catch (Exception ex)
            {
                return ex.Message;
            }
        }

Node.js

Класс ConfidentiaClientApplication Справочник по пакету SDK | Пример кода

// Exchange client Id side token with server token
  app.post('/getProfileOnBehalfOf', function(req, res) {
        var tid = < "Tenant id" >
    var token = < "Client side token" >
    var scopes = ["https://graph.microsoft.com/User.Read"];

        // Creating MSAL client
        const msalClient = new msal.ConfidentialClientApplication({
            auth: {
                clientId: < "Client ID" >,
                clientSecret: < "Client Secret" >
      }
        });

        var oboPromise = new Promise((resolve, reject) => {
            msalClient.acquireTokenOnBehalfOf({
                authority: `https://login.microsoftonline.com/${tid}`,
                oboAssertion: token,
                scopes: scopes,
                skipCache: true
            }).then(result => {
                console.log("Token is: " + result.accessToken);
            }).catch(error => {
                reject({ "error": error.errorCode });
            });
        });

Если необходим доступ к данным Microsoft Graph, настройте серверный код следующим образом:

1. Проверка маркера доступа. Дополнительные сведения см. в разделе Проверка маркера доступа;
2. Инициирование потока OBO OAuth 2.0 с вызовом платформы удостоверений Майкрософт, которая включает маркер доступа, некоторые метаданные о пользователе и учетные данные приложения вкладки (идентификатор приложения и секрет клиента). Платформа удостоверений Майкрософт возвращает новый маркер доступа, который можно использовать для доступа к Microsoft Graph.
3. Получение данных из Microsoft Graph с помощью нового маркера.
4. Используйте сериализацию кэша маркеров в MSAL.NET, чтобы кэшировать новый маркер доступа для нескольких, если это необходимо.

Важно!

• Для обеспечения безопасности всегда используйте код на стороне сервера для выполнения вызовов Microsoft Graph или других вызовов, требующих передачи маркера доступа. Это помогает защитить маркер от перехвата или утечки. НЕ возвращайте маркер OBO клиенту, так как он позволит клиенту выполнять прямые вызовы к Microsoft Graph.
• Для двух отдельных приложений, зарегистрированных в Идентификаторе Microsoft Entra, для каждого приложения требуются отдельные маркеры. Используйте поток OBO , чтобы обеспечить обмен данными между приложениями.
• Не используйте notifySuccess результат для возврата сведений о маркере на родительскую страницу. Используйте localStorage для сохранения маркера и передачи ключа элемента через notifySuccess.

Получение согласия

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

От администратора клиента

Простой способ предоставления согласия от имени организации — получить согласие администратора.

От пользователя

При запросе дополнительного согласия пользователя с помощью возможности проверки подлинности клиентской библиотеки JavaScript (TeamsJS) в Microsoft Teams учитывайте следующие моменты:

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

1. Маркер, полученный с помощью , getAuthToken() должен быть обменяться на стороне сервера с помощью потока OBO Microsoft Entra, чтобы получить доступ к другим API Graph. Убедитесь, что для этого обмена используется конечная точка Microsoft Entra версии 2.

2. При первой попытке выполнить обмен маркерами для пользователя, microsoft Entra отказывается обмениваться маркерами, это может быть связано с тем, что пользователь не согласился предоставить вашему приложению разрешение на доступ к данным пользователя. В таких случаях обмен завершается ошибкой invalid_grant или interaction_required . Примеры invalid_grant ошибок включают в себя, когда требуется согласие или auth_code, утверждение или маркер обновления истек, отозван, неправильно сформирован или отсутствует. Примеры interaction_required включают, когда требуется многофакторная проверка подлинности или регистрация корпоративных устройств.

3. Если обмен завершается сбоем invalid_grant из-за ошибок или interaction_required , необходимо заказать у пользователя согласие. Так как взаимодействие с пользователем может происходить только от клиента, сервер должен вернуть клиентскому приложению указание на то, что требуется согласие. Затем можно использовать пользовательский интерфейс, чтобы попросить пользователя приложения предоставить другое согласие. Пользовательский интерфейс должен содержать кнопку, которая активирует диалоговое окно согласия Microsoft Entra.

4. Чтобы запросить у пользователя согласие на доступ к данным приложения, необходимо включить prompt=consent свойство в query-string-parameter в идентификатор Microsoft Entra.

   • Использование ?prompt=consent&scope={scopes} вместо ?scope={scopes}
   • Убедитесь, что {scopes} свойство содержит все области, которые запрашивается у пользователя. Например, Mail.Read или User.Read.

   Сведения об обработке добавочного согласия для приложения tab см. в разделе Добавочное и динамическое согласие пользователя.

5. После того как пользователь приложения предоставит дополнительные разрешения, повторите попытку потока OBO, чтобы получить доступ к дополнительным API Graph. Дополнительные сведения см. в статье Пример кода проверки подлинности единого входа в Teams Personal Tab .

Условие гонки при выполнении вызова OBO после недопустимого исключения предоставления

Если пользователь не предоставил согласие приложения Microsoft Entra для этих областей, вызов OBO завершается ошибкой invalid_grant или interaction_required ошибкой. Эта ошибка сообщает о том, что необходимо заставить у пользователя запрос на его согласие.

Когда пользователь предоставил свое согласие и вы пытаетесь немедленно позвонить по OBO, иногда между идентификатором Microsoft Entra ID, распространяющим это согласие, и запросом OBO возникает раса. Это может привести к сбою вызова OBO с теми же invalid_grant ошибками или interaction_required .

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

Механизм ожидания и повтора должен отслеживать, дал ли пользователь согласие на необходимые области. Если вызов API, включающий запрос OBO, завершается сбоем с приведенными выше ошибками, но пользователь уже дал согласие, избегайте отображения запроса согласия пользователю. Вместо этого подождите некоторое время, прежде чем повторить вызов API. Обычно идентификатор Microsoft Entra отправляет согласие в течение трех-пяти секунд. В одном из наших примеров приложений мы повторяем до трех раз с двойным временем ожидания между каждой попыткой, начиная с одной секунды ожидания.

Если после трех-пяти попыток поток OBO по-прежнему завершается сбоем, пользователь может не согласиться на все необходимые области, и вам может потребоваться снова предложить ему согласие.

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

Пример кода

Название примера	Описание	C#	Node.js
Единый вход в Microsoft Entra tabs	Пример приложения Microsoft Teams для вкладок Microsoft Entra SSO, который использует поток OBO для вызова API Graph.	Просмотр	Просмотр

См. также

• Поток On-Behalf-Of OAuth 2.0
• Получение доступа к MS Graph
• Сериализация кэша маркеров в MSAL.NET
• Поставщик MSAL2 в Microsoft Teams