Перейти к основному содержимому

Keycloak

Этот документ был подготовлен при помощи ИИ

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

Architeezy аутентифицирует пользователей через Keycloak. Встроенный контейнер keycloak содержит описание realm architeezy и провайдер русской локализации.

Импорт realm​

Realm появляется при первом запуске, пока база данных keycloak ещё пуста. Дальше Keycloak его не перезаписывает, поэтому ваши правки в консоли администратора сохранятся и при перезапуске, и при пересборке образа.

На том же первом запуске Keycloak забирает из окружения две настройки клиента: допустимый URI перенаправления API_GATEWAY_URL/login/oauth2/code/keycloak и URI перенаправления после выхода APPLICATION_URL. Подставляются они один раз, поэтому изменение APPLICATION_URL или API_GATEWAY_URL позже на них не влияет — правьте настройки клиента в консоли администратора.

Доступ к консоли администратора​

Откройте адрес из KEYCLOAK_URL — в стандартной конфигурации это http://localhost:8181. Войдите с помощью KEYCLOAK_ADMIN_USERNAME и KEYCLOAK_ADMIN_PASSWORD. Эта учётная запись принадлежит realm master и администрирует сервер; пользователем Architeezy она не является.

Чтобы перейти к realm приложения, выберите Manage realms, затем Architeezy.

Настройки realm​

Импортированный realm настроен так:

  • Отображаемое имя — Architeezy; входить можно и по имени пользователя, и по адресу электронной почты.
  • Самостоятельная регистрация и сброс пароля отключены — учётные записи создаёт администратор. Включить их можно в разделе Realm settings → Login.
  • Интернационализация включена: локали en и ru, по умолчанию en.
  • Время простоя SSO-сессии — 30 дней, время жизни access-токена — 5 минут. Время простоя сессии должно совпадать с переменной SESSION_TIMEOUT API-шлюза: меняя одно, меняйте и другое.
  • SSL требуется для внешних запросов.

Клиенты​

Кроме встроенных клиентов Keycloak (account, account-console, admin-cli, broker, realm-management, security-admin-console) realm содержит двух клиентов приложения.

architeezy​

Конфиденциальный клиент, под которым входит API-шлюз. Использует стандартный поток authorization code.

  • Valid redirect URIs должны содержать API_GATEWAY_URL/login/oauth2/code/keycloak.
  • Valid post logout redirect URIs должны содержать APPLICATION_URL.
  • Секрет на вкладке Credentials должен совпадать со значением, заданным в OAUTH2_CLIENT_SECRET.

Чтобы сменить секрет: откройте Clients → architeezy → Credentials, нажмите Regenerate, скопируйте новое значение в .env и перезапустите API-шлюз.

architeezy-api​

Публичный клиент для инструментов, которые обращаются к API от имени пользователя, — настольного приложения или скрипта. Его URI перенаправления http://localhost:* и http://127.0.0.1:* нужны локальному обработчику обратного вызова. Идентификатор этого клиента приложение читает из OAUTH2_API_CLIENT_ID.

Роли​

Realm содержит стандартные роли Keycloak — default-roles-architeezy, offline_access и uma_authorization — плюс роли realm-management, дающие права на администрирование самого realm. Выдайте учётной записи realm-management realm-admin — она сможет управлять пользователями, и пароль администратора realm master передавать не придётся.

Права внутри Architeezy с ролями realm не связаны. Все учётные записи, которым разрешён вход, начинают с одинаковыми правами; дальше доступ выдают владельцы — отдельно на каждый проект и каждое пространство моделирования.

Использование существующего Keycloak​

Если у вас уже есть Keycloak, направьте Architeezy на него, а встроенный контейнер не поднимайте:

  1. В своём Keycloak выберите Manage realms → Create realm, с помощью Browse выберите файл architeezy.json и создайте realm. Как вариант, создайте realm вручную и добавьте конфиденциального и публичного клиента с описанными выше URI перенаправления.
  2. Откройте Clients → architeezy → Credentials и скопируйте секрет.
  3. Заполните переменные OAUTH2_*. Адреса OAUTH2_ISSUER_URL, OAUTH2_AUTHORIZATION_URL и OAUTH2_ACCOUNT_URL открывает браузер, поэтому они должны быть публичными. Адреса OAUTH2_TOKEN_URL, OAUTH2_JWK_SET_URL и OAUTH2_USER_INFO_URL вызывает само приложение, и они могут быть внутренними.
  4. Удалите сервисы keycloak и keycloak-db из compose-файла и уберите их из списков depends_on у backend и api-gateway.

Точно так же подойдёт любой провайдер OAuth 2.0, который выдаёт JWT access-токены: в токене нужны утверждение sub с UUID и утверждение preferred_username.

Настройка обратного прокси​

Встроенный контейнер рассчитан на прокси, который терминирует TLS: он читает заголовки X-Forwarded-* и берёт публичное имя хоста из KEYCLOAK_URL. Выделите Keycloak отдельное имя хоста, например auth.example.com, и передавайте заголовки, перечисленные в конфигурации прокси на странице о готовых образах. Без этих заголовков Keycloak построит адреса перенаправления и издателя из внутреннего адреса, и вход не сработает.