Двухфакторная аутентификация (2FA)

KeyStack использует mTLS (mutual TLS) в качестве механизма двухфакторной аутентификации для повышения безопасности доступа к системе. При включённой двухфакторной аутентификации пользователи должны предоставить два фактора:

  1. Клиентский сертификат (первый фактор) — подтверждает, что запрос исходит с доверенного устройства.

  2. Учётные данные (второй фактор) — логин и пароль пользователя.

Включение двухфакторной аутентификации

Для активации двухфакторной аутентификации в регионе KeyStack выполните следующие действия:

  1. Откройте веб-интерфейс GitLab.

  2. Перейдите в репозиторий региона project_k / deployments / <имя региона>.

  3. Отредактируйте файл конфигурации региона globals.d/REGION.yml. Добавьте или измените следующие параметры:

    kolla_enable_mtls_external: yes
kolla_enable_tls_external: yes

    Примечание

    Параметр kolla_enable_tls_external обеспечивает шифрование соединения (HTTPS), а kolla_enable_mtls_external активирует взаимную аутентификацию клиента и сервера через сертификаты.

    Файл REGION.yml в GitLab вашего региона

    Файл REGION.yml в GitLab вашего региона

  4. Создайте новый пайплайн: Build > Pipelines > New Pipeline.

  5. В открывшемся окне добавьте значение переменной KOLLA_ARGS равное -t haproxy,horizon.

  6. Запустите пайплайн, нажав кнопку New pipeline.

    Окно создания нового пайплайна

    Окно создания нового пайплайна

    Развёртывание обновит конфигурацию прокси-сервера HAProxy для поддержки mTLS и перенастроит веб-интерфейс Horizon.

  7. После успешного выполнения развёртывания двухфакторная аутентификация будет активна для всех внешних подключений к региону.

Отключение двухфакторной аутентификации

Для отключения двухфакторной аутентификации выполните следующие шаги:

  1. Откройте веб-интерфейс GitLab.

  2. Перейдите в репозиторий региона project_k / deployments / <имя региона>.

  3. Отредактируйте файл конфигурации региона globals.d/REGION.yml, изменив параметры:

    kolla_enable_mtls_external: no
kolla_enable_tls_external: yes

    Предупреждение

    Не рекомендуется отключать параметр kolla_enable_tls_external, так как это приведёт к передаче данных (включая пароли) в незашифрованном виде.

    Файл REGION.yml в GitLab вашего региона

    Файл REGION.yml в GitLab вашего региона

  4. В левой панели меню выберите раздел Build > Pipelines > New Pipeline.

  5. В поле переменной KOLLA_ARGS введите значение -t haproxy,horizon.

  6. Запустите пайплайн, нажав кнопку New pipeline.

    Окно создания нового пайплайна

    Окно создания нового пайплайна

Генерация клиентского сертификата через LCM

Для работы с двухфакторной аутентификацией каждому пользователю необходим персональный клиентский сертификат. Генерация сертификатов выполняется через веб-интерфейс HashiCorp Vault, интегрированный в LCM.

Получение корневого сертификата

  1. Войдите в хранилище секретов Vault и перейдите в директорию secret_v2 / deployments / <LCM FQDN> / secrets / ca.crt.

    Страница с ca.crt в Vault

    Страница с файлом ca.crt в Vault

  2. Скачайте корневой сертификат ca.crt.

  3. Установите корневой сертификат в хранилище доверенных корневых центров сертификации вашей операционной системы:

    • Windows: откройте скачанный файл, нажмите Установить сертификат и выберите хранилище «Доверенные корневые центры сертификации».

    • Linux: скопируйте сертификат в директорию /usr/local/share/ca-certificates/ и выполните команду update-ca-certificates.

    • macOS: откройте приложение «Связка ключей» (Keychain Access), перетащите сертификат в раздел «Система» и отметьте его как доверенный.

Генерация клиентского сертификата

  1. Войдите в хранилище секретов Vault и перейдите в интерфейс генерации сертификатов по адресу installer / Roles / certs.

    Страница роли certs в Vault

    Страница роли certs в Vault

  2. Нажмите Generate Certificate.

    Форма генерации сертификата в Vault

    Форма генерации сертификата в Vault

  3. В форме генерации сертификата заполните поле Common name: client.<LCM FQDN>, где <LCM FQDN> — полное доменное имя региона KeyStack.

    Важно

    Common name (CN) должен строго соответствовать формату client.<домен региона>. Это обязательное требование системы безопасности KeyStack для валидации сертификата.

  4. Установите параметры сертификата:

    • TTL: выберите срок действия сертификата (по умолчанию: 365 дней).

    • Format: оставьте значение pem.

    • Private key format: оставьте значение pem.

  5. Нажмите Generate для создания сертификата.

  6. Сохраните полученные данные:

    • Certificate — сохраните содержимое в файл cert.pem.

    • Private key — сохраните содержимое в файл key.pem.

    Предупреждение

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

Подготовка сертификата для браузера

Для использования сертификата в веб-браузере необходимо преобразовать пару «сертификат + ключ» в формат PKCS#12:

  1. Зайдите на узел LCM по SSH.

    $ ssh <Имя пользователя>@ks-lcm.<REGION FQDN>.itkey.com -i id_rsa # Либо указываете прямой путь до вашего публичного .pub ssh-ключа

    Предупреждение

    Убедитесь что у вас уже создан ssh-ключ и его публичное содержимое из файла .pub было добавлено на LCM в файл - ~/.ssh/authorized_keys.

  2. Объедините сертификат и ключ в один файл:

    $ cat cert.pem > pkcs12.pem
$ echo >> pkcs12.pem
$ cat key.pem >> pkcs12.pem

  3. Создайте файл в формате PKCS#12:

    $ openssl pkcs12 -in pkcs12.pem -export -out client.p12

    При выполнении команды система запросит ввод пароля для защиты файла экспорта. Этот пароль потребуется при импорте сертификата в браузер.

Импорт сертификата в браузер

Процесс импорта различается в зависимости от используемого браузера:

  1. Откройте настройки браузера.

  2. Перейдите в раздел Конфиденциальность и безопасность > Безопасность > Настроить сертификаты.

  3. Выберите вкладку Личные (или Your certificates в английской версии).

  4. Нажмите Импорт и выберите файл client.p12.

  5. Введите пароль, который вы указали при создании файла в формате PKCS#12.

  6. Сертификат будет добавлен в хранилище браузера.

Использование двухфакторной аутентификации

Доступ через веб-интерфейс

При включённой двухфакторной аутентификации процесс входа в Horizon или AdminUI происходит следующим образом:

  1. При переходе по адресу https://<REGION FQDN> браузер отобразит системное окно выбора сертификата.

  2. Выберите ранее импортированный клиентский сертификат. В списке отобразится информация:

    • Тема (Subject): должна содержать client.<REGION FQDN>.

    • Издатель: KeyStack Root CA.

    • Срок действия: даты начала и окончания действия сертификата.

  3. После выбора сертификата нажмите OK.

  4. На странице аутентификации введите имя пользователя и пароль вашей учётной записи KeyStack.

  5. После успешной проверки обоих факторов (сертификат + пароль) вы получите доступ к системе.

Примечание

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

Доступ через OpenStack CLI

Для работы с командной строкой OpenStack (CLI) при включённой двухфакторной аутентификации необходимо явно указывать пути к сертификатам. Используйте следующий синтаксис:

$ openstack --os-cacert <CA_CERT> --os-cert <CLIENT_CERT> --os-key <CLIENT_KEY> <команда>

Параметры команды:

  • [--os-cacert <ca-cert>] — путь к файлу корневого сертификата или цепочке сертификатов (CA).

  • [--os-cert <client-cert>] — путь к файлу клиентского сертификата (PEM).

  • [--os-key <client-key>] — путь к файлу приватного ключа клиента.

Пример использования:

$ openstack --os-cacert /path/to/ca.crt \
            --os-cert /path/to/cert.pem \
            --os-key /path/to/key.pem \
            server list

Для удобства повседневной работы пути к сертификатам можно экспортировать в переменные окружения, чтобы не указывать их в каждой команде:

$ export OS_CACERT=/path/to/ca.crt
$ export OS_CERT=/path/to/cert.pem
$ export OS_KEY=/path/to/key.pem

$ openstack server list

Требования к клиентскому сертификату

Клиентский сертификат для корректной работы с двухфакторной аутентификацией должен соответствовать следующим техническим требованиям:

  • Центр сертификации (Issuer): сертификат должен быть подписан корневым CA региона KeyStack.

  • Common Name (CN): поле CN в Subject должно строго соответствовать формату client.<REGION FQDN> (где <REGION FQDN> — основной домен региона).

  • Расширения использования ключа (Key Usage):

    • Цифровая подпись (Digital Signature).

    • Шифрование ключей (Key Encipherment).

  • Расширенное использование ключа (Extended Key Usage):

    • Проверка подлинности сервера (Server Authentication, OID: 1.3.6.1.5.5.7.3.1).

    • Проверка подлинности клиента (Client Authentication, OID: 1.3.6.1.5.5.7.3.2).

  • Срок действия: сертификат должен быть валидным на момент проверки (дата Not After не наступила).

Устранение проблем

Браузер не предлагает выбрать сертификат:

  • Убедитесь, что сертификат корректно импортирован в «Личное» хранилище сертификатов браузера.

  • Проверьте срок действия сертификата.

  • Попробуйте очистить кеш SSL в браузере или использовать режим «Инкогнито».

  • Убедитесь, что в конфигурации региона действительно применён параметр kolla_enable_mtls_external: yes.

Ошибка «Сертификат не подходит» или 400 Bad Request:

  • Проверьте, что CN сертификата точно соответствует формату client.<REGION FQDN>.

  • Убедитесь, что сертификат подписан именно тем CA, который установлен в KeyStack.

OpenStack CLI возвращает ошибку SSL:

  • Убедитесь, что указаны правильные абсолютные пути к файлам сертификатов.

  • Проверьте права доступа: текущий пользователь ОС должен иметь права на чтение файлов key.pem и cert.pem.

  • Убедитесь, что OS_CACERT указывает на актуальный корневой сертификат региона.