Аутентификация

Сами ключи свойств находятся в разделе Настройка Master — здесь мы рассказываем о ментальной модели.

Три варианта входа

Master поддерживает три независимых поставщика аутентификации. Можно одновременно использовать любую комбинацию. На экране входа в систему /login отображаются элементы управления для всех активных поставщиков.

Если включено несколько параметров, они отображаются на экране в виде списка: форма для ввода имени пользователя и пароля для суперадминистраторов и локальных пользователей, а затем одна кнопка «Войти с помощью OAuth2/OIDC Provider» при включённом OIDC.

Суперадминистратор

Встроенная учётная запись суперадминистратора — единственная, которая всегда активна. Суперадминистратора можно воспринимать как пользователя с «режимом бога» (God Mode) в Axelix:

1. Он обладает всеми возможными полномочиями.
2. Он встроенный и всегда активен. Его нельзя отключить или удалить (см. ниже почему).
3. Его нельзя редактировать или изменять, однако вы можете (и должны!) сменить его имя пользователя и пароль через настройки axelix.master.auth.options.super-admin.credentials.username / .password. Обратите внимание, что эти настройки применяются заново при каждом запуске Axelix Master — а не только при первоначальной настройке!

Когда её использовать

Суперадминистратор существует для двух ситуаций, а не для повседневной работы:

1. Первоначальная настройка. На только что развёрнутом Master ещё нет других учётных записей. Войдите как суперадминистратор, чтобы выполнить первичную настройку: установить лицензию, создать первых локальных пользователей и настроить привилегированные роли, которыми ваша команда будет пользоваться в дальнейшем.
2. Аварийный доступ (break-glass). Когда учётные записи, которыми ваша команда обычно пользуется, перестают работать — сопоставление ролей OIDC назначило всем VIEWER, опечатка в issuer-uri, случайно удалили/сломали администратора — суперадминистратор становится «запасным выходом». Поскольку он никогда не зависит от базы данных или внешнего провайдера идентификации, он продолжает пускать вас в систему, пока вы устраняете неполадку.

Для повседневной работы используйте локальную или OIDC-учётную запись. Суперадминистратора оставьте для настройки и восстановления.

Чем она отличается от других учётных записей

Две другие опции входа оставляют запись в базе данных Master; суперадминистратор — нет.

• Локальные пользователи полностью хранятся в базе данных Master и управляются на экране Пользователи.
• OIDC-пользователи принадлежат вашему провайдеру идентификации (OIDC провайдеру), но Master всё равно сохраняет запись о каждом из них — включая роль, вычисленную из role-attribute-path — чтобы показывать их на экране Пользователи и повторно использовать это сопоставление для организации RBAC.
• Суперадминистратор не имеет записи в базе данных вовсе. Его учётные данные хранятся только в конфигурации. Он никогда не отображается на экране Пользователи, а его имя пользователя зарезервировано: ни один локальный или OIDC-пользователь не может быть создан, переименован, отредактирован или удалён под этим именем. Поэтому саму учётную запись суперадминистратора нельзя изменить или удалить через интерфейс.

Прежде чем предоставлять доступ к Master кому бы то ни было, измените настройки по умолчанию — admin / admin даёт полный контроль над каждым мониторируемым сервисом и над Axelix Master.

Пароль может быть указан в одном из следующих форматов:

• Plaintext — пароль указывается в исходном виде.
• Encoded — перед значением указывается идентификатор в фигурных скобках, определяющий способ его проверки: {noop} для пароля в открытом виде, {bcrypt} для хеша BCrypt.

Если префикс отсутствует, значение рассматривается как plaintext. В целях безопасности настоятельно рекомендуется использовать хешированный формат пароля (например, {bcrypt}) вместо хранения пароля в открытом виде.

Примеры закодированных паролей:

• {bcrypt}$2a$10$KjkxE0Tt8L4B2kDYlSWcme0o/AjKE7LqyDaTqPr0sESbF85e3bDTC — пароль в формате bcrypt
• {noop}password — пароль в открытом виде с префиксом (эквивалентно простому password).

Локальные пользователи

Локальные пользователи хранятся в собственной базе данных Master (UserEntity). Пароли хешируются с помощью алгоритма BCrypt. Когда axelix.master.auth.options.local.enabled=true, DatabaseUserAuthenticator ищет введённое имя пользователя, BCrypt проверяет пароль и сопоставляет сохранённую строку роли (admin, editor, viewer) с одной из встроенных ролей. При входе в систему с неизвестной строкой роли возникает UserRoleNotFoundException.

Управление локальными пользователями осуществляется через экран «Пользователи» в пользовательском интерфейсе. Для их создания, обновления и удаления требуется полномочие USERS_MANAGEMENT — по умолчанию оно есть только у SUPER_ADMIN.

OAuth2 / OIDC

Master реализует стандартный поток авторизации с использованием кода. Включите его с помощью axelix.master.auth.options.oauth2.enabled=true и укажите issuer-uri, client-id, client-secret, а также общедоступный base-url этого развёртывания Master.

Полный процесс:

1. Пользователь нажимает «Войти с помощью OAuth2/OIDC Provider» на /login. Браузер перенаправляется на конечную точку авторизации поставщика удостоверений с параметрами client-id и redirect_uri, установленными на <base-url>/api/external/oauth2/callback.
2. Поставщик удостоверений аутентифицирует пользователя и перенаправляет его обратно на страницу обратного вызова с code.
3. OAuth2CallbackController обменивает code на токен ID и токен доступа через конечную точку токенов поставщика удостоверений, проверяет токен ID и извлекает имя пользователя.
4. Роль определяется путём сопоставления выражения JMESPath в axelix.master.auth.options.oauth2.role-attribute-path с ответом userinfo. Результат сопоставляется с admin, editor или viewer. Если role-attribute-path не задано, каждый пользователь OIDC получает роль VIEWER.
5. Перед выдачей cookie сеанса Master создаёт или обновляет пользователя в своей базе данных с origin OIDC, обновляет сохранённый email из userinfo, если он есть, и фиксирует Last login.
6. Master создаёт собственный JWT-токен сеанса (с тем же кодировщиком, что и в потоках паролей) и перенаправляет браузер на /wallboard с установленными файлами cookie сеанса.

Процесс авторизации с использованием кода авторизации запускается только через браузер. Сами токены OIDC никогда не сохраняются — Master использует их один раз для идентификации пользователя, а затем выдаёт собственный JWT-токен сеанса.

Поэтому каждый успешный вход через браузер оставляет после себя учётную запись OIDC на экране Пользователи. Если то же имя пользователя уже принадлежит не-OIDC учётной записи, Master отклоняет вход вместо объединения идентичностей.

При использовании axelix.master.auth.options.oauth2.enabled=true необходимо указать следующие свойства: issuer-uri, client-id, client-secret, base-url. scopes по умолчанию имеет значение openid и требует переопределения только в том случае, если вашему провайдеру идентификации требуются дополнительные области доступа. role-attribute-path — необязательный параметр. Если он не указан, каждый вошедший в систему пользователь будет иметь роль VIEWER.

Сеанс: cookie и JWT

Все пути входа в систему заканчиваются одинаково: Master генерирует JWT и возвращает его в виде cookie. Этот же cookie-файл используется для каждого последующего запроса к пользовательскому интерфейсу.

При входе в систему

POST /api/external/users/login (и при обратном вызове OIDC) создают два файла cookie через Set-Cookie:

• auth_token — сам JWT. HttpOnly, SameSite=Strict, Path=/, MaxAge=axelix.master.auth.jwt.lifespan (по умолчанию 12h). Secure контролируется свойством axelix.master.auth.cookie.secure — оставляйте его false только для обычного HTTP-доступа к localhost.
• authorities — закодированный в Base64 JSON-массив с именами полномочий, которыми обладает вошедший в систему пользователь, например ["ENV_VALUES_READ","SCHEDULED_TASKS_MODIFY"]. Не HttpOnly, потому что интерфейс считывает его, чтобы знать, какие кнопки отображать. Это всего лишь подсказка для пользовательского интерфейса. Серверная часть при каждом запросе заново определяет полномочия на основе JWT, поэтому изменение этого файла cookie влияет только на то, что предлагает пользовательский интерфейс, а не на то, что позволяет сервер.

Сам JWT подписан с помощью алгоритма HMAC (HMAC256, HMAC384 или HMAC512, задаётся через axelix.master.auth.jwt.algorithm) с использованием секрета в axelix.master.auth.jwt.signing-key. Его поля — это имя пользователя (sub), метки времени выдачи и истечения срока действия, а также поле roles, в котором кодируется каждая предоставленная роль вместе с её полномочиями и вложенными компонентами.

Через что проходит каждый запрос

CookieBasedJwtAuthorizationFilter выполняется при каждом /api/... запросе, кроме небольшого списка разрешённых (сама конечная точка входа, обратный вызов OAuth2, конечная точка общедоступных настроек, конечная точка самостоятельной регистрации и /api/mcp/** — для них предусмотрены собственные фильтры или они намеренно анонимны). Для всего остального:

1. Фильтр считывает файл cookie auth_token. Отсутствует или пуст → JwtProcessingException, отображается как 401 Unauthorized.
2. DefaultJwtDecoderService проверяет подпись и срок действия по axelix.master.auth.jwt.signing-key. Подделанный, неподписанный или просроченный токен → 401.
3. MasterAuthorityResolver ищет путь запроса + метод HTTP во встроенной таблице правил «для этой конечной точки требуется это полномочие». Для конечных точек, которых нет в таблице, требуется только действительный токен.
4. DefaultAuthorizer объединяет роли пользователя в полный набор полномочий и проверяет, включает ли он необходимые. Не хватает одного → AuthorizationException, отображается как 403 Forbidden.
5. В случае успешного выполнения запрос выполняется внутри DefaultSecurityContext с аутентифицированным User и исходным токеном, поэтому нижестоящий код может считать данные вызывающей стороны без повторного анализа.

Выход и ротация

POST /api/external/users/logout перезаписывает оба файла cookie пустыми значениями и MaxAge=0, поэтому браузер сразу же удаляет их. Сам JWT технически остаётся действительным до истечения его поля exp — Master не ведёт серверный блок-лист.

Чтобы принудительно завершить все активные сеансы (после компрометации ключа, устаревания общего секретного ключа или ежеквартальной ротации), измените axelix.master.auth.jwt.signing-key. Каждый выданный токен сразу же не пройдёт проверку при следующем запросе, поскольку подпись перестанет соответствовать новому секретному ключу. Пользователи вернутся на /login.

Роли и полномочия

Master использует фиксированный набор ролей и полномочий. Роли представляют собой набор полномочий; проверка авторизации всегда выполняется на основе полномочий, а не названий ролей. Это означает, что пользовательская роль, подключённая через сопоставление OIDC или уровень базы данных, должна соответствовать одному из встроенных названий — на сегодняшний день нет возможности определить новое полномочие в конфигурации.

Что защищает каждое полномочие:

• ENV_VALUES_READ — отображение значений свойств на экране «Окружение».
• CONFIG_PROPS_VALUES_READ — отображение значений свойств на экране «Свойства конфигурации».
• SCHEDULED_TASKS_MODIFY — включение, отключение, принудительное выполнение и изменение расписания запланированных задач.
• CACHES_CLEAR — очистка отдельных кэшей, кэш менеджеров или всего кэша сервиса.
• CACHES_TOGGLE — включение и отключение отдельных кэшей и кэш менеджеров во время выполнения.
• GARBAGE_COLLECTOR — запуск сборки мусора, включение и отключение мониторинга журнала сборки мусора.
• USERS_VIEW — чтение ленты пользователей.
• USERS_MANAGEMENT — создание, обновление и удаление локальных пользователей.

USERS_VIEW и USERS_MANAGEMENT сегодня зарезервированы для SUPER_ADMIN — ADMIN не может управлять пользователями без повышения уровня доступа.

Аутентификация на MCP-сервере

Встроенный MCP-сервер по адресу /api/mcp защищён собственным фильтром McpAuthorizationFilter, поскольку учётные данные, передаваемые MCP-клиентами, не являются cookie-файлами сеанса браузера. Фильтр анализирует заголовок Authorization и перенаправляет запрос обработчику, соответствующему схеме.

• Basic — BasicMcpAuthenticationHandler декодирует Authorization: Basic <base64(user:pass)> и делегирует тому же CompositeUserAuthenticator, который использует пользовательский интерфейс. Работают как суперадминистраторы, так и локальные учётные записи, Сопоставление ролей идентично входу через браузер.
• Bearer — BearerMcpAuthenticationHandler обрабатывает учётные данные как токен доступа OIDC. Он прогоняет токен через JmesPathOidcRoleExtractor (по тому же пути, что и при входе через браузер), чтобы определить роль, а затем выдаёт синтетический PasswordlessUser с именем AI_AGENT с этой ролью. Доступно только когда axelix.master.auth.options.oauth2.enabled=true.

После идентификации пользователя фильтр выполняет ту же проверку полномочий, что и веб-фильтр — требования к полномочиям по каждому инструменту разрешаются через McpEndpointResolver + McpEndpointAuthorityResolver. Инструмент, на использование которого у вызывающей стороны нет прав, возвращает 403 Forbidden. При использовании неизвестных или недействительных учётных данных возвращается 401 Unauthorized.

Если OIDC включён и запрос поступает без заголовка Authorization, ответ 401 также содержит:

WWW-Authenticate: Bearer resource_metadata="<base-url>/api/external/mcp-oauth2/.well-known/oauth-protected-resource"

MCP-клиенты, поддерживающие RFC 9728, используют этот заголовок, чтобы получить доступ к конфигурации OAuth2 в Master и самостоятельно провести пользователя через authorization flow.

См. также

• Настройка Master — свойства аутентификации — все ключи и дефолты, упомянутые на этой странице.
• Настройка Spring Boot Starter — сторона стартера для того же JWT-ключа подписи.
• Что такое Master? — более широкий контекст того, что делает Master, когда сессия установлена.