Перейти к основному содержимому
Версия: 0.4 · текущая

Настройка поставщиков входа

Практическое руководствоПроверено 11 октября 2026 г.
Область применения:Excubius 0.4Роли: Установщик (администратор Linux), Суперадминистратор, Администратор сущности
ПланыFree · Core · Pro · EnterpriseРазвертываниеСамостоятельное размещение

Пользователи входят в Excubius с учетной записью своей организации из Microsoft Entra ID или Google. Excubius никогда не хранит пароль каталога: он получает от поставщика подписанный токен, проверяет его и хранит учетную запись как сочетание поставщика и идентификатора пользователя у этого поставщика, а не только как адрес электронной почты. В этом руководстве показано, как зарегистрировать Excubius у каждого поставщика и как определить, кто получает учетную запись.

Перед началом работы​

  • Узнайте публичный адрес сервера, https://<primary name>. С него начинаются все адреса перенаправления, приведенные ниже. Пользователи, открывшие Excubius по псевдониму, перенаправляются для входа на основное имя, поэтому достаточно одного адреса перенаправления для каждого поставщика. См. статью Настройка имен и TLS.
  • Используйте HTTPS. Microsoft Entra ID принимает http только для localhost.
  • Вам нужен доступ к файлу конфигурации сервера /opt/excubius/.env или к программе установки: sudo ./install.sh --reconfigure повторно запрашивает значения Entra ID.
  • Чтобы включить или отключить вход через Google, вам нужна роль Super admin (суперадминистратор). Чтобы определить, кто получает учетную запись в сущности, вам нужна роль Entity admin (администратор сущности) для этой сущности.

Как обрабатывается первый вход​

Роли назначаются только при создании учетной записи или принятии приглашения. Существующая учетная запись входит с теми ролями, которые у нее есть, поэтому роль, удаленная администратором, при следующем входе не возвращается.

Регистрация Excubius в Microsoft Entra ID​

План

Вход с помощью Microsoft Entra ID входит в планы Core, Pro и Enterprise.

Создайте одну регистрацию приложения на каждую установку для одного клиента (tenant). Мультитенантные регистрации (common или organizations) не поддерживаются.

  1. В Microsoft Entra admin center откройте App registrations и выберите New registration.
    • Name: имя, которое пользователи увидят в запросе согласия, например название, под которым они знают систему мониторинга.
    • Supported account types: Accounts in this organizational directory only (single tenant).
    • Redirect URI: платформа Web, https://<primary name>/api/v1/auth/entra/callback.
  2. На странице Overview скопируйте Directory (tenant) ID и Application (client) ID.
  3. В разделе Certificates & secrets › Client secrets выберите New client secret и скопируйте его Value, а не ID. Значение показывается только один раз. Запишите дату истечения срока действия: когда срок действия секрета истекает, вход перестает работать, поэтому заранее создайте следующий секрет и замените значение.
  4. В разделе Authentication оставьте отключенными Access tokens и ID tokens для неявного и гибридного потоков, а поле Front-channel logout URL оставьте пустым. Excubius использует поток кода авторизации с PKCE.
  5. В разделе API permissions оставьте делегированные разрешения Microsoft Graph openid, profile и email. Разрешение User.Read, добавляемое по умолчанию, не мешает. Предоставьте согласие администратора, если ваш клиент не разрешает пользователям давать согласие самостоятельно.
  6. В разделе Token configuration выберите Add optional claim, тип токена ID, утверждение email и примите запрос на добавление разрешения Graph email. Без этого Excubius использует preferred_username, что подходит, если имена участников-пользователей являются адресами электронной почты.
  7. При необходимости, чтобы назначать роли группам каталога, выберите Add groups claim в разделе Token configuration:
    • Выберите Groups assigned to the application, затем назначьте группы в разделе Enterprise applications › ваше приложение › Users and groups. Так токены остаются небольшими и содержат только сопоставленные вами группы. Вариант Security groups тоже подходит.
    • Для токена ID выберите Group ID. Excubius сопоставляет идентификаторы объектов групп; имена групп не сопоставляются.
    • Токен содержит не более 200 групп. Если групп больше, Entra ID не отправляет ни одной, и Excubius считает, что пользователь не входит ни в одну группу каталога.
  8. При необходимости в разделе Enterprise applications › ваше приложение › Properties задайте для Assignment required? значение Yes. Тогда войти смогут только пользователи и группы, назначенные приложению, еще до того, как Excubius применит собственные правила.

Теперь передайте значения в Excubius:

  1. Подключитесь к серверу, перейдите в учетную запись службы командой sudo -iu excubius и добавьте три значения в /opt/excubius/.env:

    ENTRA_TENANT_ID=8f6a1c2e-4b3d-4e5f-9a8b-7c6d5e4f3a2b
    ENTRA_CLIENT_ID=11111111-2222-3333-4444-555555555555
    ENTRA_CLIENT_SECRET=<the secret value>
  2. Перезапустите платформу:

    export XDG_RUNTIME_DIR=/run/user/$(id -u)
    systemctl --user restart excubius.service

Когда все три значения заданы, на странице входа появляется кнопка Sign in with Microsoft. Секрет клиента считывается только из файла конфигурации: он никогда не записывается в базу данных, не возвращается API и не попадает в журналы.

Регистрация Excubius в Google​

  1. В Google Cloud console откройте Google Auth Platform.
    • Audience: Internal, если у всех пользователей есть учетная запись Google Workspace вашей организации; в противном случае External. Опубликуйте приложение или на время тестирования добавьте тестовых пользователей.
    • Data access: области openid, .../auth/userinfo.email и .../auth/userinfo.profile.
  2. В разделе Clients выберите Create client, тип Web application, и добавьте разрешенный URI перенаправления https://<primary name>/api/v1/auth/google/callback. Источники JavaScript не нужны.
  3. Скопируйте Client ID и Client secret в /opt/excubius/.env как GOOGLE_CLIENT_ID и GOOGLE_CLIENT_SECRET, затем перезапустите платформу, как описано в шагах для Entra ID.
  4. Убедитесь, что функция access.google_login включена в разделе Settings › Instance. По умолчанию она включена.

На странице входа появляется кнопка Sign in with Google. Пока access.google_login отключена, вход через Google отклоняется, а не просто скрывается.

Google и разрешенные домены

Любой человек может создать личную учетную запись Google с любым адресом электронной почты, на который он получает почту. Поэтому вход через Google засчитывается для разрешенного домена, только если Google является доверенным источником для этого адреса: это учетная запись Google Workspace именно этого домена с подтвержденным адресом. Для личных учетных записей Google всегда требуется приглашение, и для приглашения Google должен сообщить, что адрес подтвержден.

Кто получает учетную запись​

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

РежимПервый вход без приглашенияНазначаемая роль
By invitation (по умолчанию)Отклоняется—
Allowed domainsПринимается, если домен адреса электронной почты есть в списке. Требуется точное совпадение; поддомены не учитываютсяDefault role (Наблюдатель, если вы не выберете другую; никогда не Суперадминистратор) в сущности, задающей регистрацию, которая наследуется ниже, как любая роль

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

  1. Откройте Settings › Users and roles и выберите сущность в средстве выбора, например ООО «Лукоморье».
  2. Выберите вкладку Registration. На странице указано, откуда взят текущий параметр: из этой сущности, из сущности выше или из установки.
  3. Выберите By invitation или Allowed domains.
  4. Для Allowed domains введите Domains через запятую или пробел (не более 50), например ciguapa.example, и выберите Default role.
  5. Выберите Save.

Чтобы сущность ниже снова наследовала параметр от родителя, выберите Inherit from above again.

  • Пользователь, домен которого разрешен в нескольких сущностях, получает роль по умолчанию каждой из них.
  • Для корневой сущности действует параметр установки ALLOWED_SIGNUP_DOMAINS, пока в ней не будет сохранена регистрация. Он означает режим Allowed domains с этими доменами и роль Наблюдатель в корневой сущности. Сохранение регистрации корневой сущности, даже в режиме By invitation, заменяет этот параметр.
  • Сущность в режиме By invitation сама перестает назначать роли по домену, но не может отнять роль, унаследованную от регистрации вышестоящей сущности.
  • Чтобы закрыть кому-либо доступ, деактивируйте этого пользователя. Удаление домена не влияет на существующие учетные записи. См. раздел Управление пользователями и ролями.

Приглашения и вход​

Приглашение — это ссылка https://<primary name>/invite/<token>, которую администратор сущности создает для одного адреса электронной почты, роли и сущности; см. раздел Приглашение пользователя. Когда пользователь открывает ссылку:

  • На странице отображаются сущность, роль, пригласивший пользователь и замаскированный адрес, а затем кнопки входа. Поставщику передается запрос на предварительный выбор приглашенного адреса.
  • Адрес учетной записи, с которой выполняется вход, должен совпадать с приглашенным; регистр букв не учитывается.
  • Создается учетная запись или связывается существующая учетная запись того же поставщика, и в приглашающей сущности назначается роль. Имеющаяся там более низкая роль повышается; более высокая сохраняется.
  • Если открыть ссылку позже еще раз, пользователь просто войдет в систему.

Если вход отклонен​

Браузер возвращается на страницу входа с понятным объяснением, а каждый отказ записывается в журнал аудита как login.failed с причиной.

КодЗначениеЧто делать
not_invitedПриглашения нет, и ни одна сущность не принимает регистрацию по домену; или ссылка приглашения неизвестнаПригласите пользователя или разрешите его домен
domain_not_allowedРегистрация по домену настроена, но не для этого домена, или поставщик не является доверенным источником для него, как в случае личной учетной записи GoogleДобавьте домен или пригласите пользователя
account_disabledУчетная запись существует и деактивированаАктивируйте ее в разделе Users and roles
email_mismatchАдрес учетной записи не совпадает с приглашенным, или Google не подтвердил егоВойдите с приглашенной учетной записью или пригласите правильный адрес
invite_expiredСрок действия приглашения истек, или его уже использовал кто-то другойОтправьте новое приглашение
invalid_stateВход занял более 10 минут, был начат в другом браузере или на другой вкладке, или ответ не соответствовал запросуНачните заново со страницы входа
provider_errorПоставщик отказал (согласие не предоставлено или отменено), не настроен или отключен, либо его ответ не прошел проверкуПроверьте параметры поставщика, описанные выше, и запись auth.login_refused в журнале серверной части

Выход из Excubius не означает выход из Microsoft или Google.