Создание вкладки единого входа Microsoft Teams с помощью набора средств Microsoft Graph

Статья
03/26/2023

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

Создание вкладки единого входа включает следующие действия.

Добавьте набор средств Microsoft Graph.
Создайте всплывающее окно проверки подлинности.
Создание идентификатора клиента/приложения
Создание серверной части
Инициализация поставщика TEAMS MSAL2.
Добавление компонентов.
Протестируйте приложение.

Добавление Microsoft Graph Toolkit

Вы можете использовать Microsoft Graph Toolkit в приложении, ссылаясь на загрузчик напрямую (через unpkg) или установив пакеты npm. Чтобы использовать набор средств, вам также потребуется пакет SDK для Microsoft Teams.

unpkg
npm

Чтобы использовать набор средств и пакет SDK Teams через загрузчики, добавьте ссылку в скрипте в код:

<!-- Microsoft Teams sdk must be referenced before the toolkit -->
<script src="https://unpkg.com/@microsoft/teams-js@2/dist/MicrosoftTeams.min.js" crossorigin="anonymous"></script>
<script src="https://unpkg.com/@microsoft/mgt@2/dist/bundle/mgt-loader.js"></script>

Использование Toolkit с помощью модулей ES6 обеспечивает полное управление процессом объединения и позволяет объединить только код, необходимый для приложения. Чтобы использовать модули ES6, добавьте в проект пакеты npm для набора средств и пакета SDK Microsoft Teams:

npm install @microsoft/teams-js @microsoft/mgt-element @microsoft/mgt-teams-msal2-provider @microsoft/mgt-components

Если приложение не предоставлено предварительное согласие администратора, пользователям может потребоваться согласие на разрешения. Чтобы включить эту функцию, необходимо указать страницу, которую приложение Teams откроет во всплывающем окне, чтобы следовать потоку проверки подлинности. Путь к странице может быть любым, если он находится в том же домене, что и ваше приложение (например, https://yourdomain.com/tabauth). Единственным требованием для этой страницы является вызов TeamsMsal2Provider.handleAuth() метода, но вы можете добавить любое содержимое или ход загрузки.

Ниже приведен пример базовой страницы, которая обрабатывает поток проверки подлинности во всплывающем окне.

unpkg
npm

<!DOCTYPE html>
<html>
  <head>
    <script src="https://unpkg.com/@microsoft/teams-js@2/dist/MicrosoftTeams.min.js" crossorigin="anonymous"></script>
    <script src="https://unpkg.com/@microsoft/mgt@2/dist/bundle/mgt-loader.js"></script>
  </head>

  <body>
    <script>
      mgt.TeamsMsal2Provider.handleAuth();
    </script>
  </body>
</html>

import { TeamsMsal2Provider } from '@microsoft/mgt-teams-msal2-provider';

TeamsMsal2Provider.handleAuth();

Создание идентификатора клиента/приложения

Вкладка должна работать как зарегистрированное приложение Azure AD, чтобы получить маркер доступа от Azure AD. Зарегистрируйте приложение в клиенте и предоставьте Microsoft Teams разрешение на получение маркеров доступа от его имени:

Откройте браузер и перейдите в Центр администрирования Azure Active Directory. Войдите с помощью личная учетная запись (учетная запись Майкрософт) или рабочую или учебную учетную запись.
В левой области выберите Azure Active Directory, а затем выберите Регистрация приложений в разделе Управление.
Выберите Новая регистрация. На странице Регистрация приложения задайте необходимые значения следующим образом:
- Задайте для свойства ИмяNode.js Teams SSO (или имя по своему выбору).
- В поле Поддерживаемые типы учетных записей выберите Учетные записи в любом каталоге организаций и личные учетные записи Майкрософт.
- В разделе URI перенаправления задайте для первого раскрывающегося списка Single Page Application значение и задайте значение URL-адреса страницы проверки подлинности, созданного на предыдущем шаге, например https://myapp.ngrok.io/tabauth.
На странице обзора приложения скопируйте значение идентификатора приложения (клиента) для последующего использования. Это значение потребуется при создании нового поставщика и в серверной части.
В разделе Управление перейдите в раздел Секреты сертификатов&. Нажмите кнопку Новый секрет клиента. Введите значение в поле Описание, выберите один из параметров Срок действия и нажмите Добавить.
Прежде чем покинуть страницу, скопируйте значение секрета клиента. Это потребуется для серверной службы.

Важно!

Система никогда не покажет секрет клиента повторно, поэтому убедитесь, что вы скопировали его.
В разделе Управление перейдите к разделу Разрешения API. Выберите Добавить разрешение>Делегированные разрешенияMicrosoft Graph>, а затем добавьте следующие разрешения: email, offline_access, openid, profile, User.Read. Выберите Добавить разрешения.
(НЕОБЯЗАТЕЛЬНО) Если вы хотите предварительно предоставить согласие на любые другие области, можно добавить дополнительные разрешения. Если вы используете другие компоненты или планируете использовать другие API Microsoft Graph, могут потребоваться дополнительные разрешения. Дополнительные сведения о необходимых разрешениях см. в документации по каждому компоненту.
- Чтобы получить предварительное согласие от имени администратора, выберите Предоставить согласие администратора, а затем нажмите кнопку Да.
В разделе Управление перейдите к разделу Предоставление API. В верхней части страницы рядом с Application ID URIэлементом выберите Задать. При этом создается API в виде: api://{AppID}. Обновите его, чтобы добавить поддомен; например, api://myapp.ngrok.io/{appID}.
На той же странице выберите Добавить область. Заполните поля следующим образом и выберите Добавить область:
- Имя области: access_as_user
- Кто может предоставить согласие?: администраторы и пользователи
- Администратор отображаемое имя согласия:Teams can access the user’s profile
- Администратор описание согласия:Allows Teams to call the app’s web APIs as the current user
- Отображаемое имя согласия пользователя: Teams can access the user profile and make requests on the user's behalf
- Описание согласия пользователя: Enable Teams to call this app’s APIs with the same rights as the user.
- Состояние: включено
URL-адрес API должен выглядеть следующим образом: api://myapp.ngrok.io/{appID}/access_as_user.
Затем добавьте два клиентских приложения. Это касается классических и мобильных клиентов Teams и веб-клиента. В разделе Авторизованные клиентские приложения выберите Добавить клиентское приложение. Введите идентификатор клиента и выберите созданный область. Затем выберите Добавить приложение. Сделайте это для следующих идентификаторов:
- 5e3ce6c0-2b1f-4285-8d4b-75ee78787346
- 1fec8e78-bce4-4aaf-ab1b-5451cc387264

Создание серверной части

Серверной частью может быть любая серверная часть, которая позволяет обменивать маркер проверки подлинности Microsoft Teams с маркером, который можно использовать для вызова Microsoft Graph через поток on-behalf-of.

См. пример узла единого входа Teams.

Ниже приведена эталонная реализация сервера node express.

import dotenv from 'dotenv';
import express from 'express';
import path from 'path';
import * as msal from '@azure/msal-node';
import { NextFunction, Request, Response } from 'express';
import jwt, { JwtHeader, SigningKeyCallback } from 'jsonwebtoken';
import jwksClient from 'jwks-rsa';
import jwt_decode from 'jwt-decode';

// Load .env file
dotenv.config();

/**
 * Validates a JWT
 * @param {Request} req - The incoming request
 * @param {Response} res - The outgoing response
 * @returns {Promise<string | null>} - Returns the token if valid, returns null if invalid
 */
function validateJwt(req: Request, res: Response, next: NextFunction): void {
  const authHeader = req.headers.authorization!;
  const ssoToken = authHeader.split(' ')[1];
  if (ssoToken) {
    const validationOptions = {
      audience: process.env.CLIENT_ID,
    };
    jwt.verify(ssoToken, getSigningKey, validationOptions, (err, payload) => {
      if (err) {
        return res.sendStatus(403);
      }
      next();
    });
  } else {
    res.sendStatus(401);
  }
}

/**
 * Parses the JWT header and retrieves the appropriate public key
 * @param {JwtHeader} header - The JWT header
 * @param {SigningKeyCallback} callback - Callback function
 */
function getSigningKey(header: JwtHeader, callback: SigningKeyCallback): void {
  const client = jwksClient({
    jwksUri: 'https://login.microsoftonline.com/common/discovery/keys'
  });
  client.getSigningKey(header.kid!, (err, key) => {
    if (err) {
      callback(err, undefined);
    } else {
      callback(null, key.getPublicKey());
    }
  });
}

/**
 * Gets an access token for the user using the on-behalf-of flow
 * @param authHeader - The Authorization header value containing a JWT bearer token
 * @returns {Promise<string | null>} - Returns the access token if successful, null if not
 */
async function getAccessTokenOnBehalfOf(req: Request, res: Response): Promise<void> {
  // The token has already been validated, just grab it
  const authHeader = req.headers.authorization!;
  const ssoToken = authHeader.split(' ')[1];

  // Create an MSAL client
  const msalClient = new msal.ConfidentialClientApplication({
    auth: {
      clientId: req.body.clientid,
      clientSecret: process.env.APP_SECRET
    }
  });

  try {
    const result = await msalClient.acquireTokenOnBehalfOf({
      authority: `https://login.microsoftonline.com/${jwt_decode<any>(ssoToken).tid}`,
      oboAssertion: ssoToken,
      scopes: req.body.scopes,
      skipCache: true
    });
    res.json({ access_token: result?.accessToken });
  } catch (error) {
    if (error.errorCode === 'invalid_grant' || error.errorCode === 'interaction_required') {
      // This is expected if it's the user's first time running the app ( user must consent ) or the admin requires MFA
      res.status(403).json({ error: 'consent_required' }); // This error triggers the consent flow in the client.
    } else {
      // Unknown error
      res.status(500).json({ error: error.message });
    }
  }
}

////////////////////////
// create and run server
////////////////////////

const app = express();
const PORT = process.env.port || process.env.PORT || 8000;

// Support JSON payloads
app.use(express.json());
app.use(express.static(path.join(__dirname, 'client')));

// An example for using POST and with token validation using middleware
app.post('/api/token', validateJwt, async (req, res) => {
  await getAccessTokenOnBehalfOf(req, res);
});

app.listen(PORT, () => {
  console.log(`⚡️[server]: Server is running at http://localhost:${PORT}`);
});

Инициализация поставщика MSAL2 Teams

Поставщики microsoft Graph Toolkit обеспечивают проверку подлинности и доступ к Microsoft Graph. Дополнительные сведения см. в статье Использование поставщиков. Поставщик Teams MSAL2 обрабатывает всю логику и взаимодействия, которые необходимо реализовать с помощью пакета SDK Для Teams для проверки подлинности пользователя.

В режиме единого входа убедитесь, что он указывает sso-url / ssoUrl на серверный API и указывает на него.

HTML
JavaScript

Добавьте в mgt-teams-msal2-provider HTML-код.

<mgt-teams-msal2-provider
  client-id="<YOUR_CLIENT_ID>"
  auth-popup-url="/tabauth"
  scopes="User.Read,Mail.ReadBasic"
  sso-url="http://localhost:8000/api/token"
  http-method="POST"
  ></mgt-teams-msal2-provider>

Замените <YOUR_CLIENT_ID> идентификатором клиента для приложения, замените auth-popup-url полным или относительным путем к странице проверки подлинности, а замените sso-url полным или относительным путем к серверной службе.

Чтобы инициализировать поставщик в коде JavaScript, импортируйте TeamsMsal2Provider и задайте .globalProvider

import {Providers} from '@microsoft/mgt-element';
import {TeamsMsal2Provider, HttpMethod} from '@microsoft/mgt-teams-msal2-provider';
import * as MicrosoftTeams from "@microsoft/teams-js";

TeamsMsal2Provider.microsoftTeamsLib = MicrosoftTeams;

Providers.globalProvider = new TeamsMsal2Provider({
  clientId: `<YOUR_CLIENT_ID>`,
  authPopupUrl: '/tabauth',
  scopes: ['User.Read','Mail.ReadBasic'],
  ssoUrl: 'http://localhost:8000/api/token',
  httpMethod: HttpMethod.POST
});

Замените <YOUR_CLIENT_ID> идентификатором клиента для приложения, замените authPopupUrl полным или относительным путем к странице проверки подлинности, а замените ssoUrl полным или относительным путем к серверной службе.

Добавление компонентов

Теперь вы можете добавить любой из компонентов Microsoft Graph Toolkit.

Компоненты в HTML можно добавлять, как обычно. Например, чтобы добавить Person компонент, добавьте следующий код в HTML- код.

<mgt-person person-query="me"></mgt-person>

Если вы используете React, мы рекомендуем использовать компоненты React из библиотекиmgt-react. Дополнительные сведения см. в статье Использование Microsoft Graph Toolkit с React.

Тестирование примера

Полную реализацию см. в примере узла единого входа Teams.

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

Важно!

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

Дальнейшие действия

Воспользуйтесь компонентами в интерактивной среде.
Задайте вопрос на microsoft Q&A.
Сообщайте об ошибках и оставляйте запросы на создание функций в GitHub.

Создание вкладки единого входа Microsoft Teams с помощью набора средств Microsoft Graph

Добавление Microsoft Graph Toolkit

Создание идентификатора клиента/приложения

Создание серверной части

Инициализация поставщика MSAL2 Teams

Добавление компонентов

Тестирование примера

Дальнейшие действия

Дополнительные ресурсы

Дополнительные ресурсы

Создание вкладки единого входа Microsoft Teams с помощью набора средств Microsoft Graph

Добавление Microsoft Graph Toolkit

Создание всплывающей страницы проверки подлинности

Создание идентификатора клиента/приложения

Создание серверной части

Инициализация поставщика MSAL2 Teams

Добавление компонентов

Тестирование примера

Дальнейшие действия

Дополнительные ресурсы

Дополнительные ресурсы