Настройка поставщиков входа
Пользователи входят в 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) не поддерживаются.
- В 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.
- На странице Overview скопируйте Directory (tenant) ID и Application (client) ID.
- В разделе Certificates & secrets › Client secrets выберите New client secret и скопируйте его Value, а не ID. Значение показывается только один раз. Запишите дату истечения срока действия: когда срок действия секрета истекает, вход перестает работать, поэтому заранее создайте следующий секрет и замените значение.
- В разделе Authentication оставьте отключенными Access tokens и ID tokens для неявного и гибридного потоков, а поле Front-channel logout URL оставьте пустым. Excubius использует поток кода авторизации с PKCE.
- В разделе API permissions оставьте делегированные разрешения Microsoft Graph
openid,profileиemail. РазрешениеUser.Read, добавляемое по умолчанию, не мешает. Предоставьте согласие администратора, если ваш клиент не разрешает пользователям давать согласие самостоятельно. - В разделе Token configuration выберите Add optional claim, тип токена ID, утверждение
emailи примите запрос на добавление разрешения Graphemail. Без этого Excubius используетpreferred_username, что подходит, если имена участников-пользователей являются адресами электронной почты. - При необходимости, чтобы назначать роли группам каталога, выберите 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 считает, что пользователь не входит ни в одну группу каталога.
- При необходимости в разделе Enterprise applications › ваше приложение › Properties задайте для Assignment required? значение Yes. Тогда войти смогут только пользователи и группы, назначенные приложению, еще до того, как Excubius применит собственные правила.
Теперь передайте значения в Excubius:
-
Подключитесь к серверу, перейдите в учетную запись службы командой
sudo -iu excubiusи добавьте три значения в/opt/excubius/.env:ENTRA_TENANT_ID=8f6a1c2e-4b3d-4e5f-9a8b-7c6d5e4f3a2bENTRA_CLIENT_ID=11111111-2222-3333-4444-555555555555ENTRA_CLIENT_SECRET=<the secret value> -
Перезапустите платформу:
export XDG_RUNTIME_DIR=/run/user/$(id -u)systemctl --user restart excubius.service
Когда все три значения заданы, на странице входа появляется кнопка Sign in with Microsoft. Секрет клиента считывается только из файла конфигурации: он никогда не записывается в базу данных, не возвращается API и не попадает в журналы.
Регистрация Excubius в Google
- В Google Cloud console откройте Google Auth Platform.
- Audience: Internal, если у всех пользователей есть учетная запись Google Workspace вашей организации; в противном случае External. Опубликуйте приложение или на время тестирования добавьте тестовых пользователей.
- Data access: области
openid,.../auth/userinfo.emailи.../auth/userinfo.profile.
- В разделе Clients выберите Create client, тип Web application, и добавьте разрешенный URI перенаправления
https://<primary name>/api/v1/auth/google/callback. Источники JavaScript не нужны. - Скопируйте Client ID и Client secret в
/opt/excubius/.envкакGOOGLE_CLIENT_IDиGOOGLE_CLIENT_SECRET, затем перезапустите платформу, как описано в шагах для Entra ID. - Убедитесь, что функция
access.google_loginвключена в разделе Settings › Instance. По умолчанию она включена.
На странице входа появляется кнопка Sign in with Google. Пока access.google_login отключена, вход через Google отклоняется, а не просто скрывается.
Любой человек может создать личную учетную запись Google с любым адресом электронной почты, на который он получает почту. Поэтому вход через Google засчитывается для разрешенного домена, только если Google является доверенным источником для этого адреса: это учетная запись Google Workspace именно этого домена с подтвержденным адресом. Для личных учетных записей Google всегда требуется приглашение, и для приглашения Google должен сообщить, что адрес подтвержден.
Кто получает учетную запись
У каждой сущности есть режим регистрации, который действует для нее и для всего, что находится ниже, пока сущность ниже не задаст собственный режим.
| Режим | Первый вход без приглашения | Назначаемая роль |
|---|---|---|
| By invitation (по умолчанию) | Отклоняется | — |
| Allowed domains | Принимается, если домен адреса электронной почты есть в списке. Требуется точное совпадение; поддомены не учитываются | Default role (Наблюдатель, если вы не выберете другую; никогда не Суперадминистратор) в сущности, задающей регистрацию, которая наследуется ниже, как любая роль |
Чтобы задать режим, выполните следующие действия.
- Откройте Settings › Users and roles и выберите сущность в средстве выбора, например ООО «Лукоморье».
- Выберите вкладку Registration. На странице указано, откуда взят текущий параметр: из этой сущности, из сущности выше или из установки.
- Выберите By invitation или Allowed domains.
- Для Allowed domains введите Domains через запятую или пробел (не более 50), например
ciguapa.example, и выберите Default role. - Выберите 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.