Установка Keycloak на свой сервер

Установка Keycloak через Docker Compose с PostgreSQL#

1. Поставьте Docker скриптом curl -fsSL https://get.docker.com | sh и создайте каталог keycloak с файлом compose.yaml.
2. Впишите свой домен и пароли в файл ниже. В быстром старте версия образа указана явно, и это верный подход: тег latest в работе не используют.
3. Запустите docker compose up -d. Первый старт занимает несколько минут, пока Keycloak создаёт таблицы.
4. Откройте консоль по адресу https://auth.example.com/admin и войдите под администратором из переменных. Затем создайте постоянного администратора и удалите временного.

services:
  db:
    image: postgres:17
    restart: unless-stopped
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: change_me
    volumes:
      - kc_db:/var/lib/postgresql/data
  keycloak:
    image: quay.io/keycloak/keycloak:26.8.1
    command: start
    restart: unless-stopped
    depends_on:
      - db
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://db/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: change_me
      KC_HOSTNAME: https://auth.example.com
      KC_HTTP_ENABLED: "true"
      KC_PROXY_HEADERS: xforwarded
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: change_me_too
    ports:
      - "127.0.0.1:8080:8080"
volumes:
  kc_db:

Переменные KC_BOOTSTRAP_ADMIN_USERNAME и KC_BOOTSTRAP_ADMIN_PASSWORD нужны только для первого входа. Порт привязан к 127.0.0.1, так что снаружи Keycloak виден лишь через прокси.

Первый realm в Keycloak и вход через него в другие приложения#

Realm в Keycloak это отдельное пространство пользователей и приложений. Не работайте в стандартном realm master: он служит для администраторов самого Keycloak.

1. Создайте realm, например company, и заведите в нём пользователей или включите самостоятельную регистрацию.
2. Добавьте клиент для приложения: тип OpenID Connect, адрес приложения и redirect URI из его инструкции.
3. Скопируйте Client ID и секрет в настройки приложения и укажите адрес https://auth.example.com/realms/company как провайдера.
4. Включите второй фактор для администраторов: Keycloak умеет одноразовые коды и ключи WebAuthn.

Вопросы об установке Keycloak#

Какой порт использует Keycloak в Docker?

Внутри контейнера 8080 для HTTP и 8443 для HTTPS. В быстром старте консоль открывается на порту 8080, в работе наружу выставляют только 443 через обратный прокси.

Чем отличается start-dev от start в Keycloak?

Режим start-dev предназначен для проверки: он упрощает настройки и использует встроенную базу. Режим start требует внешней базы, hostname и HTTPS, зато подходит для рабочего сервера.

Как задать администратора Keycloak в Docker?

Переменными KC_BOOTSTRAP_ADMIN_USERNAME и KC_BOOTSTRAP_ADMIN_PASSWORD при первом запуске. После входа создайте постоянного администратора, а временного удалите.

Нужен ли Keycloak, если пользователей всего несколько?

Не обязательно. Единый вход оправдан, когда сервисов несколько и людей приходится заводить в каждом отдельно. Для одного человека хватит менеджера паролей.