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

Конвейер встреч Teams читает стенограммы встреч, записи и связанные артефакты из Microsoft Graph, используя только аутентификацию приложения (демон) — без входа пользователя, без интерактивного согласия на каждую встречу. Для этого требуется регистрация приложения 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 <ваш тенант>. Столбец Status должен измениться на зелёную галочку для каждого разрешения.

Требуется для сводок на основе стенограмм

Требуется для резервного использования записи (когда стенограмма недоступна)

Требуется для доставки сводок (только режим Graph)

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

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

• OnlineMeetings.ReadWrite.All / Chat.ReadWrite без .All — шире, чем нужно конвейеру.

• Делегированные разрешения — конвейер использует поток только для приложения (учётные данные клиента); делегированные разрешения не будут работать без входа пользователя.

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

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

Microsoft предоставляет для этого политики доступа к приложениям (Application Access Policies) для Teams. Эта возможность доступна только через PowerShell; в портале нет UI для неё.

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

# Create a policy scoped to the Hermes app
New-CsApplicationAccessPolicy `
  -Identity "Hermes-Meeting-Pipeline-Policy" `
  -AppIds "<MSGRAPH_CLIENT_ID>" `
  -Description "Restrict Hermes meeting pipeline to allow-listed users"

# Grant the policy to specific users whose meetings the pipeline may read
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 включает быстрый тест аутентификации Graph. Из вашей установки 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_seconds около 3600. При ошибках возникает MicrosoftGraphTokenError с кодом ошибки Azure. Наиболее частые ошибки:

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

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

1. Создайте второй секрет клиента на шаге 2, не удаляя первый.

2. Обновите MSGRAPH_CLIENT_SECRET в ~/.hermes/.env новым значением.

3. Перезапустите gateway, чтобы новый секрет вступил в силу: hermes gateway restart.

4. Проверьте работу с помощью теста выше.

5. Удалите старый секрет на портале Azure.

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

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

• Настройка слушателя вебхуков — запуск платформы gateway msgraph_webhook, которая получает уведомления об изменениях Graph.

• Конфигурация конвейера — настройка среды выполнения конвейера встреч Teams и CLI оператора.

• Исходящая доставка — интеграция сводок обратно в канал или чат Teams.

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