Настройка Keycloak

Двухфакторная аутентификация для бизнеса Контур.ID

Попробовать бесплатно

Keycloak — это решение с открытым исходным кодом для SSO. Позволяет управлять аутентификацией и авторизацией пользователей. Перед настройкой проверьте, что Keycloak развернут на вашем сервере.

Шаги, необходимые для настройки двухфакторной аутентификации в Keycloak:

Предварительная подготовка

1. Зайдите в кабинет администратора.
2. Перейдите в «Ресурсы» и выберите Keycloak.
3. Добавьте новую конфигурацию.

4. Заполните настройки:

   • Название конфигурации: укажите любое имя, например, Kontur.ID.

   • Запрос второго фактора: укажите «У всех» или настройте ограничения по группам пользователей.
   • Домен: укажите домен, с которым будет взаимодействовать система.
5. Нажмите на кнопку «Сохранить и скачать».

6. В результате вы получите zip-архив, в котором содержится папка с настройками двухфакторной аутентификации.

   Файлы конфигурации уже настроены и готовы к использованию для защиты на второй фактор.

Установка адаптера

1. Распакуйте архив, в котором находится файл kid-2fa-plugin.jar.
2. Скопируйте файл kid-2fa-plugin.jar в папку по адресу <путь до keycloak>/providers:

Настройка конфигурации ресурса

При необходимости настройте конфигурацию согласно инструкции Описание файла Keycloak, либо пропустите этот шаг.

Для настройки отредактируйте файл конфигурации appsettings.json.

В зависимости от вашей операционной системы отредактировать файл можно следующим образом:

Windows

1. В папке providers, в которую скопировали плагин kid-2fa-plugin.jar на предыдущем шаге, найдите appsettings.json. Для этого нажмите на файл правой клавишей мышки и выберите «Открыть с помощью» программы архиватора, которая умеет работать с форматом zip. В нашем случае, выберем — 7-zip File Manager. В окне 7-zip File Manager нажмите на appsettings.json, чтобы открыть файл в любом редакторе.
   

   

2. Внесите изменения.
3. Сохраните и закройте файл.
4. В форме программы 7-zip File Manager появится предупреждение, что appsettings.json был изменен. Нажмите да, чтобы обновить измененный файл в архиве.

Linux

1. В папке providers, в которую скопировали плагин kid-2fa-plugin.jar на предыдущем шаге, извлеките файл appsettings.json из архива. 

   Для этого в терминале наберите команду:

   unzip -j kid-2fa-plugin.jar appsettings.json

   Эта команда извлечет файл appsettings.json из архива kid-2fa-plugin.jar и сохранит его в текущем каталоге, игнорируя любую структуру каталогов внутри архива.
    

2. Откройте appsettings.json и внесите изменения.
3. Сохраните и закройте appsettings.json.

4. Добавьте изменённый файл appsettings.json в архив. В терминале наберите команду:

   zip -u kid-2fa-plugin.jar appsettings.json

   Эта команда обновит файл appsettings.json в kid-2fa-plugin-orig.jar, если он уже существует или добавит его в архив, если он отсутствует.

После настройки файла конфигурации appsettings.json, перезапустите Keycloak.

Настройка адаптера

1. Перейдите в панель администратора Keycloak и авторизуйтесь под учетной записью администратора.

2. В левом верхнем углу нажмите на выпадающий список и выберите ваш Realm.

3. В разделе «Authentication» на вкладке «Flows» откройте меню «Browser flow» и выполните «Duplicate».

   

4. Введите удобное имя для копии, например, «Custom browser». Нажмите «Duplicate».

   

5. Перейдите на карточку нового Flow. В шаге «Custom browser forms» нажмите «Add step».

   

6. Далее выберите в списке Kontur ID 2fa.

   

   Важно: адаптер Kontur ID 2fa требует аутентифицированного пользователя, поэтому этот шаг должен располагаться после «Username Password Form».

   

   

7. В столбце «Requirement» для Kontur ID 2fa укажите «Required».

   

   

8. Custom Flow можно привязать глобально для всех клиентов: «Authentication→Flow→Custom Flow→Bind flow». Выберите «Browser Flow».

   

   

   Custom Flow можно привязать к конкретному клиенту: «Clients →{client}→Advanced→Authentication flow overrides→Browser Flow». Выберите «Custom Browser».

   

   

Исключение по группам пользователей

Адаптер работает с исключениями по группам пользователей. Исключить пользователей можно одним из способов:

• По локальным группам Keycloak.
• По группам Active Directory.

Локальные группы Keycloak

1. Нажмите «Groups» в панели «Manage», чтобы перейти в список групп Realm. 

   

   

2. Нажмите «Create group» и введите имя группы.

   

3. Включите пользователя в группу:

   • перейдите на карточку требуемой группы из списка;
   • откройте вкладку «Members»;
   • нажмите «Add member»;

   

   • выберите необходимых пользователей;
   • нажмите «Add».

   

   

Пример настройки политики исключений:

"PolicyConfiguration": {
  "Policy": "AllUsers",
  "Exceptions": {
    "Domains": {
      "default": {
        "Groups": [
          "2FA"
        ]
      }
    },
    "Users": [
      "guid1",
      "guid2"
    ]
  }
}

Настройка двухфакторной аутентификации в Keycloak завершена.

Обновление Keycloak

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

Процедура обновления Keycloak включает следующие шаги: 

1. Скачайте актуальный адаптер. Это может быть новая конфигурация или существующая, которую вы хотите обновить.

2. Проверьте технические требования. Перед обновлением адаптера убедитесь, что установлен Keycloak  22.0.0 и выше.

3. Распакуйте архив, в котором находится файл kid-2fa-plugin.jar.
4. Скопируйте файл kid-2fa-plugin.jar в папку по адресу <путь до keycloak>/providers.
5. Настройте файл appsettings.json в соответствии с вашими текущими настройками.
6. Перезапустите Keycloak для применения обновлений.

Таким образом, вы обновите Keycloak и при этом сохраните текущие настройки.

Устранение неполадок