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

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

В этом руководстве рассматриваются следующие шаги:

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

Для завершения вам потребуются права администратора клиента (или администратор, который предоставит согласие от вашего имени). Сохраните собранные значения — они понадобятся в файле ~/.vibeos/.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. Заполните поля:
   • Name: VibeOS Teams Meeting Pipeline (или любое другое узнаваемое имя).
   • Supported account types: Accounts in this organizational directory only (Single tenant).
   • Redirect URI: оставьте пустым — для аутентификации только приложения он не требуется.
5. Нажмите Register.

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

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

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

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

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

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

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

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

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

Разрешение	Что оно дает приложению
OnlineMeetings.Read.All	Чтение метаданных собраний Teams (тема, участники, URL для присоединения).
OnlineMeetingTranscript.Read.All	Чтение расшифровок собраний, созданных Teams.

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

Разрешение	Что оно дает приложению
OnlineMeetingRecording.Read.All	Загрузка записей собраний Teams для обработки STT в автономном режиме.
CallRecords.Read.All	Поиск собраний по записям вызовов, когда известен только URL для присоединения.

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

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

Разрешение	Что оно дает приложению
ChannelMessage.Send	Отправка сообщений в каналы Teams от имени приложения.
Chat.ReadWrite.All	Отправка сообщений в личные и групповые чаты (только если вы указали chat_id в качестве цели доставки).

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

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

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

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

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

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

# Создание политики, ограничивающей область действия приложения VibeOS
New-CsApplicationAccessPolicy `
  -Identity "VibeOS-Meeting-Pipeline-Policy" `
  -AppIds "<MSGRAPH_CLIENT_ID>" `
  -Description "Ограничить конвейер собраний VibeOS списком разрешенных пользователей"

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

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

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

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

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

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

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

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

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

chmod 600 ~/.vibeos/.env

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

VibeOS включает дымовой тест аутентификации Graph. Из вашей установки VibeOS:

python -c "
import asyncio
from tools.microsoft_graph_auth import MicrosoftGraphTokenProvider
provider = MicrosoftGraphTokenProvider.from_env()
token = asyncio.run(provider.get_access_token())
print('Токен получен, длина:', len(token))
print(provider.inspect_token_health())
"

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

Ошибка Azure	Значение	Исправление
AADSTS7000215: Invalid client secret	Значение секрета не совпадает или истекло.	Создайте новый секрет на шаге 2; обновите .env.
AADSTS700016: Application not found	Неправильный MSGRAPH_CLIENT_ID или неправильный клиент.	Перепроверьте, что значения из шага 1 относятся к одному и тому же приложению.
AADSTS90002: Tenant not found	Опечатка в MSGRAPH_TENANT_ID.	Скопируйте Directory (tenant) ID со страницы обзора приложения еще раз.
insufficient_claims во время вызова (не во время получения токена)	Токен получен, но Graph возвращает 401/403.	Вы пропустили административное согласие на шаге 3 или добавили разрешения, но не дали согласие заново. Вернитесь к API permissions и снова нажмите Grant admin consent.

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

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

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

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

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

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

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