Регистрация приложения Microsoft Graph

Конвейер собраний Teams читает расшифровки, записи и связанные артефакты из Microsoft Graph, используя только приложение (daemon) аутентификацию — без входа пользователя, без интерактивного согласия на каждое собрание. Для этого требуется регистрация приложения Azure AD с разрешениями приложения, одобренными администратором.

Это руководство описывает:

1. Создание регистрации приложения
2. Создание секрета клиента
3. Предоставление разрешений Graph API, необходимых конвейеру
4. Административное согласие на эти разрешения
5. (Опционально) Ограничение приложения конкретными пользователями с помощью политики доступа к приложениям

Для завершения вам понадобятся права администратора клиента (или администратор, который даст согласие от вашего имени). Сохраните собранные значения — они понадобятся в ~/.hermes/.env в конце.

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

• Клиент Microsoft 365 с лицензиями Teams Premium или Teams, которые создают расшифровки и записи собраний
• Доступ администратора к порталу Azure по адресу entra.microsoft.com
• Публично доступная HTTPS-конечная точка для уведомлений об изменениях Graph (настраивается позже, на этапе вебхук-слушателя)

Шаг 1: Создание регистрации приложения

1. Войдите в entra.microsoft.com как администратор клиента.
2. Перейдите в Identity → Applications → App registrations.
3. Нажмите New registration.
4. Заполните:
5. Name: Hermes Teams Meeting Pipeline (или любое имя, которое вы узнаете).
6. Supported account types: Accounts in this organizational directory only (Single tenant).
7. Redirect URI: оставьте пустым — для аутентификации только приложения он не нужен.
8. Нажмите Register.

Вы попадёте на страницу обзора приложения. Скопируйте два значения:

• Application (client) ID → MSGRAPH_CLIENT_ID
• Directory (tenant) ID → MSGRAPH_TENANT_ID

Шаг 2: Создание секрета клиента

1. В левой навигации откройте Certificates & secrets.
2. Нажмите New client secret.
3. Description: hermes-graph-secret. Expires: выберите значение, соответствующее вашей политике ротации (обычно 6–24 месяца).
4. Нажмите Add.
5. Немедленно скопируйте значение из столбца Value — оно отображается только один раз. Это значение — MSGRAPH_CLIENT_SECRET.

Столбец Secret ID — это не секрет. Вам нужен столбец Value.

Шаг 3: Предоставление разрешений Graph API

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

1. В левой навигации откройте API permissions.
2. Нажмите Add a permission → Microsoft Graph → Application permissions.
3. Добавьте разрешения из таблицы ниже, соответствующие тому, что должен делать конвейер.
4. После добавления нажмите Grant admin consent for <your tenant>. В столбце Status для каждого разрешения должна появиться зелёная галочка.

Необходимые для сводок на основе расшифровок

Необходимые для запасного варианта с записью (когда расшифровка недоступна)

Необходимые для доставки сводок (только режим Graph)

Если platforms.teams.extra.delivery_mode имеет значение graph, конвейер отправляет сводки в канал или чат Teams через Graph API. Пропустите эти разрешения, если вы используете режим доставки incoming_webhook.

Не рекомендуется

• OnlineMeetings.ReadWrite.All / Chat.ReadWrite без .All — шире, чем нужно конвейеру.
• Делегированные разрешения — конвейер использует поток только приложения (client-credentials); делегированные разрешения не будут работать без входа пользователя.

Шаг 4: (Рекомендуется) Ограничение приложения с помощью политики доступа к приложениям

По умолчанию разрешения приложения, такие как OnlineMeetings.Read.All, предоставляют приложению доступ ко всем собраниям в клиенте. Для партнёрских демо и тестовых клиентов это нормально; для продакшена почти наверняка нужно ограничить, собрания каких пользователей может читать приложение.

Microsoft предоставляет политики доступа к приложениям для Teams именно для этого. Политика настраивается только через PowerShell; в портале нет интерфейса для неё.

Из административной PowerShell с установленным модулем MicrosoftTeams и подключением (Connect-MicrosoftTeams):

# Создание политики, ограниченной приложением Hermes
New-CsApplicationAccessPolicy `
  -Identity "Hermes-Meeting-Pipeline-Policy" `
  -AppIds "<MSGRAPH_CLIENT_ID>" `
  -Description "Restrict Hermes meeting pipeline to allow-listed users"

# Назначение политики конкретным пользователям, чьи собрания может читать конвейер
Grant-CsApplicationAccessPolicy `
  -PolicyName "Hermes-Meeting-Pipeline-Policy" `
  -Identity "alice@example.com"

Grant-CsApplicationAccessPolicy `
  -PolicyName "Hermes-Meeting-Pipeline-Policy" `
  -Identity "bob@example.com"

Распространение может занять до 30 минут после назначения. Проверьте с помощью:

Test-CsApplicationAccessPolicy -Identity "alice@example.com" -AppId "<MSGRAPH_CLIENT_ID>"

Без соблюдения политики любой пользователь доступен для чтения — это техническое решение. Не пропускайте этот шаг в продакшен-клиенте.

Шаг 5: Запись учётных данных в файл окружения

Поместите три собранных значения в ~/.hermes/.env:

MSGRAPH_TENANT_ID=<directory-tenant-id>
MSGRAPH_CLIENT_ID=<application-client-id>
MSGRAPH_CLIENT_SECRET=<client-secret-value>

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

chmod 600 ~/.hermes/.env

Шаг 6: Проверка потока токенов

Гермес включает дымовой тест аутентификации Графика. Результат вашей установки Hermes:

python -c "
import asyncio
from tools.microsoft_graph_auth import MicrosoftGraphTokenProvider
provider = MicrosoftGraphTokenProvider.from_env()
token = asyncio.run(provider.get_access_token())
print('Token acquired, length:', len(token))
print(provider.inspect_token_health())
"

Успешный запуск выводит длинный текст токена и словарь здоровья, показывающий cached: True и значениеexpires_in_секунды около 3600. Поэтому выводится MicrosoftGraphTokenError с ошибочным кодом Azure. Наиболее распространённые:

Ротация секрета клиента

Секреты клиента Azure имеют жёсткий срок действия. До истечения срока:

1. Создайте второй секрет клиента на шаге 2, не удаляя первый.
2. Обновите MSGRAPH_CLIENT_SECRET в ~/.hermes/.env новым значением.
3. Перезапустите шлюз, чтобы был применен новый секрет: «Перезапуск шлюза Гермеса».
4. Проверьте с помощью дымового теста выше.
5. Удалите старый секрет с портала Azure.

Следующие шаги

После успешной проверки учётных данных происходит обращение к:

• Настройка вебхук-слушателя — развернуть платформу шлюза msgraph_webhook, которая получает уведомления об изменениях Graph.
• Конфигурация конвейера — при настройке конвейера собранных команд и CLI оператора.
• Внешняя доставка — подключите отправку обратно в канал или чат Teams.

Эти страницы построены вместе с PR, добавляя экологические нормы. Настройка учётных данных — это самостоятельный предварительный шаг, который можно выполнить заранее.