OAuth2 / OIDC — подключение сервиса к Omniscol

Что делает Omniscol как сервер OAuth2

Внешний сервис — ИИ-агент, коннектор, панель показателей — становится клиентом, зарегистрированным в вашем аккаунте; пользователь школы одобряет его доступ на экране согласия; после этого сервис получает токен доступа с коротким сроком действия, область действия которого ограничена предоставленными скоупами и правами пользователя.

Этот механизм отличается от SSO для пользователей, описанного на странице OIDC / SSO: там Omniscol, наоборот, выступает клиентом вашего поставщика удостоверений и подключает ваших пользователей. Здесь Omniscol находится на стороне сервера: к нему подключаются сервисы.

Этот сервер используют две интеграции Omniscol:

• MCP — стандартная аутентификация ИИ-агента проходит через этот сервер OAuth2 (см. MCP — подключение ИИ-агента);
• OneRoster — поставщик данных OneRoster аутентифицируется токеном OAuth2 «машина — машина», который выдаёт тот же сервер (см. OneRoster).

Любой другой сервис, совместимый с OAuth2 / OIDC, может подключаться к нему так же.

Обнаружение и конечные точки протокола

Omniscol публикует метаданные обнаружения по стандартным адресам .well-known в корне домена вашего аккаунта (например, https://vasha-shkola.omniscol.com). Совместимый клиент находит там все конечные точки самостоятельно, без ручной настройки:

• /.well-known/oauth-authorization-server — метаданные сервера авторизации (RFC 8414);
• /.well-known/openid-configuration — метаданные OpenID Connect (содержимое то же, что в предыдущем пункте);
• /.well-known/jwks.json — открытые ключи для проверки (JWKS), по которым проверяется подпись id_token;
• /.well-known/oauth-protected-resource — метаданные защищённого ресурса (RFC 9728).

Эти метаданные перечисляют конечные точки протокола:

• /oauth/authorize — запрос авторизации (экран входа, затем экран согласия);
• /oauth/token — обмен кода на токен и обновление токена;
• /oauth/register — динамическая регистрация клиентов (RFC 7591);
• /oidc/userinfo — сведения о вошедшем пользователе (OIDC);
• /oauth/revoke — отзыв токена (RFC 7009).

Эти конечные точки протокола общедоступны: они не ограничены аккаунтами Премиум, и открывать их вручную не нужно. К Премиум относится только экран управления клиентами, описанный ниже.

Потоки авторизации

Omniscol поддерживает три потока OAuth2:

• Код авторизации с PKCE — поток по умолчанию для сервиса, который действует от имени пользователя. Сервис перенаправляет пользователя на /oauth/authorize; после входа и согласия Omniscol возвращает код авторизации (действителен 5 минут), который сервис обменивает на /oauth/token. Используется метод PKCE S256, а единственный допустимый response_type — code.
• Обновление (refresh_token) — чтобы продлить делегированный доступ без повторного согласия.
• Client credentials — поток «машина — машина», без пользователя; его используют, в частности, потребители OneRoster. Клиент аутентифицируется напрямую и получает токен доступа.

При обмене сервер выдаёт токен доступа (Bearer, действует 1 час) и, для пользовательских потоков, токен обновления (действует 30 дней). Если запрошен скоуп openid, дополнительно выдаётся подписанный id_token OIDC; его подпись проверяется через /.well-known/jwks.json. Поток client_credentials выдаёт только токен доступа, без токена обновления и без id_token.

Затем токен доступа передаётся в HTTP-заголовке Authorization: Bearer <токен>. При каждом вызове Omniscol проверяет его подпись, убеждается, что клиент по-прежнему имеет статус «активный», что пользователь по-прежнему существует и обладает нужной ролью, и что скоупы токена покрывают вызываемую конечную точку; в противном случае вызов отклоняется.

Скоупы и согласие

Скоупы, которыми вы управляете на клиенте:

• read:basic — чтение расписаний, сводных панелей и экранов просмотра (модули Главная страница, Расписание, Сводная панель, Управление расписанием);
• read:user — чтение списка пользователей;
• write:data — запись в те же модули просмотра;
• admin — административный доступ (модули Администрирование, Управление отсутствиями, Управление расписанием).

Сервер знает также скоупы OIDC (openid, email, profile) и скоупы OneRoster только для чтения (префикс imsglobal.org). Эти скоупы привилегированные: клиент не может назначить их себе сам через динамическую регистрацию; их должен выдать администратор в карточке клиента.

Фактически предоставляемый скоуп — это пересечение того, что запрашивает клиент, и того, что для него зарегистрировано: клиент никогда не получает больше, чем указано в его карточке. В пользовательском потоке экран согласия (/oauth/consent) показывает название и логотип запрашивающего сервиса, а также понятный список запрошенных скоупов, с кнопками Принять и Отклонить. Если пользователь одобряет запрос, выдаётся код авторизации и пользователь возвращается в сервис; если отклоняет, он возвращается в сервис с ошибкой access_denied.

Динамическая регистрация клиентов

Конечная точка /oauth/register реализует динамическую регистрацию (Dynamic Client Registration, RFC 7591): совместимый сервис может зарегистрироваться клиентом сам, без предварительного ручного вмешательства. Благодаря этому агент MCP настраивается по одному лишь URL сервера.

Динамическая регистрация не может назначить привилегированный скоуп (скоупы OneRoster): они молча отбрасываются, а если не остаётся ни одного допустимого скоупа, по умолчанию выдаётся read:basic. Привилегированные скоупы остаются доступными только при выдаче администратором.

Экран управления клиентами OAuth2

В аккаунтах Премиум вы управляете клиентами из раздела Администрирование → Импорт/Экспорт, секция OAuth2, с помощью кнопки OAuth2. Для доступа сначала требуется пароль администратора — дополнительное подтверждение перед открытием экрана.

Экран перечисляет зарегистрированные клиенты и для каждого показывает его состояние (активный / неактивный), название, скоупы, контакты и URI (сайт, логотип, URI перенаправления). Вы можете:

• Зарегистрировать клиент — укажите название, необязательный software_id, скоупы, контакты, сайт, логотип и URI перенаправления. При создании Omniscol показывает client_id и client_secret только один раз.
• Изменить клиент — изменять можно только безопасные поля: название, скоупы, контакты, сайт и логотип. URI перенаправления, software_id и секрет здесь не меняются.
• Включить или отключить клиент — у отключённого клиента токены отклоняются начиная со следующего вызова.
• Удалить клиент — удаление необратимо.

Секрет клиента

client_secret показывается только один раз, при регистрации. Omniscol хранит у себя лишь хеш секрета и никогда не хранит секрет в открытом виде: его нельзя ни показать повторно, ни получить позже. Сразу скопируйте его в менеджер секретов.

client_id, напротив, детерминирован: он вычисляется из названия аккаунта, названия клиента и хеша его технических метаданных. Поэтому две полностью одинаковые регистрации дают один и тот же идентификатор.

Обновление секрета (ротация)

Ротация секрета возможна: она выпускает новый секрет, сохраняет только хеш нового секрета и возвращает этот секрет лишь один раз. Она выполняется через конечную точку управления динамической регистрацией (/oauth/register/<client_id>/rotation) и требует предъявить токен регистрации, выданный клиенту при его динамической регистрации. Поэтому из описанного выше экрана управления ротация не запускается: этот токен экран не использует.

OAuth2 или токен API: что выбрать

Omniscol предлагает два механизма машинного доступа с разными моделями доверия:

• OAuth2 (эта страница) — зарегистрированная третья сторона после согласия пользователя получает токен с коротким сроком действия (1 ч), ограниченный предоставленными скоупами, который можно обновлять и отзывать (отключив клиент). Поток client_credentials дополнительно покрывает взаимодействие «машина — машина» без пользователя. Это подходящий способ для идентифицированного стороннего сервиса, для MCP и OneRoster.
• Токен API (см. API Omniscol) — автономный токен, подписанный сервером, который содержит список разрешённых конечных точек и который вы сами передаёте внешней системе: без зарегистрированной третьей стороны, без экрана согласия, без обновления. Это делегирование администратором собственных прав системе, которую он контролирует.

Итак, токен API подходит, когда вы сами передаёте доступ системе, которую контролируете; OAuth2 подходит, когда идентифицированный сторонний сервис должен получить делегированный, ограниченный скоупами и отзываемый доступ, либо когда этого требует протокол (MCP, OneRoster).