Полное руководство: импорт предхешированных паролей Argon2 в Keycloak

Импорт предварительно хешированных паролей Argon2 в Keycloak

Для успешного импорта предварительно хешированных паролей Argon2 в Keycloak необходимо использовать правильную структуру CredentialRepresentation с корректно отформатированным JSON в полях secretData и credentialData. Наиболее распространенная проблема, с которой сталкиваются пользователи, - это неправильное форматирование параметров или отсутствие обязательных полей в структуре учетных данных.

Содержание

• Правильная структура учетных данных для Argon2
• Требуемые параметры и форматирование
• Распространенные проблемы импорта и их решения
• Полный пример импорта
• Проверка и тестирование
• Альтернативные методы импорта

Правильная структура учетных данных для Argon2

Keycloak ожидает, что учетные данные Argon2 будут структурированы с полями secretData и credentialData, содержащими данные JSON. Поле secretData содержит фактическое значение хеша и соль, в то время как credentialData содержит параметры алгоритма.

{
  "type": "password",
  "secretData": "{\"value\":\"<your_hash_here>\",\"salt\":\"<your_salt_here>\",\"additionalParameters\":{}}",
  "credentialData": "{\"algorithm\":\"argon2\",\"hashIterations\":5,\"additionalParameters\":{\"hashLength\":[\"32\"],\"memory\":[\"7168\"],\"parallelism\":[\"1\"],\"type\":[\"id\"],\"version\":[\"19\"]}}"
}

Требуемые параметры и форматирование

Требования к credentialData

Поле credentialData должно включать:

• algorithm: Установлено в "argon2"
• hashIterations: Количество итераций (5 в вашем случае)
• additionalParameters: Объект, содержащий массивы для каждого параметра:
  • hashLength: Массив со строковым значением ["32"]
  • memory: Массив со строковым значением ["7168"]
  • parallelism: Массив со строковым значением ["1"]
  • type: Массив со строковым значением ["id"]
  • version: Массив со строковым значением ["19"] (для Argon2id v1.9)

Важно: Все параметры в additionalParameters должны быть отформатированы как массивы со строковыми значениями, а не как прямые значения. Это распространенная ошибка, которая приводит к сбоям при аутентификации.

Требования к secretData

Поле secretData требует:

• value: Ваш Argon2 хеш (кодированный в base64 при необходимости)
• salt: Ваша соль (кодированная в base64 при необходимости)
• additionalParameters: Пустой объект {}

Распространенные проблемы импорта и их решения

1. Неправильное форматирование параметров

Если вы используете прямые значения вместо массивов:

// НЕПРАВИЛЬНО - прямые значения
"credentialData": "{\"algorithm\":\"argon2\",\"additionalParameters\":{\"memory\":7168,\"parallelism\":1}}"

// ПРАВИЛЬНО - массивы со строковыми значениями  
"credentialData": "{\"algorithm\":\"argon2\",\"additionalParameters\":{\"memory\":[\"7168\"],\"parallelism\":[\"1\"]}}"

2. Отсутствие параметра версии

Keycloak требует наличия параметра версии в credentialData:

// НЕПРАВИЛЬНО - отсутствует версия
"credentialData": "{\"algorithm\":\"argon2\",\"additionalParameters\":{\"memory\":[\"7168\"],\"parallelism\":[\"1\"]}}"

// ПРАВИЛЬНО - с версией
"credentialData": "{\"algorithm\":\"argon2\",\"additionalParameters\":{\"memory\":[\"7168\"],\"parallelism\":[\"1\"],\"version\":[\"19\"]}}"

3. Проблемы с форматом хеша

Убедитесь, что ваш Argon2 хеш находится в правильном формате, который ожидает Keycloak. Согласно документации Keycloak, хеш должен соответствовать стандартному формату Argon2:

$argon2id$v=19$m=7168,t=5,p=1$salt$hash

4. Кодирование соли

Если у вас по-прежнему возникают проблемы, попробуйте закодировать вашу соль в base64:

// Пример кодирования в base64 на JavaScript
const salt = "your_salt_here";
const base64Salt = btoa(salt);

Полный пример импорта

Вот полный рабочий пример для импорта пароля Argon2:

{
  "username": "testuser",
  "enabled": true,
  "credentials": [
    {
      "type": "password",
      "secretData": "{\"value\":\"PMj1VthGWlVYthrRiAjw76UQf0Hqjcwn+jMRxTfS0GE\",\"salt\":\"ULCOILY1KOlp6uOW\",\"additionalParameters\":{}}",
      "credentialData": "{\"algorithm\":\"argon2\",\"hashIterations\":5,\"additionalParameters\":{\"hashLength\":[\"32\"],\"memory\":[\"7168\"],\"parallelism\":[\"1\"],\"type\":[\"id\"],\"version\":[\"19\"]}}"
    }
  ]
}

Проверка и тестирование

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

1. Проверка в консоли администратора Keycloak: Перейдите на вкладку учетных данных пользователя, чтобы проверить импортированный хеш и параметры
2. Тестирование входа в систему: Попробуйте войти в систему с исходным паролем
3. Использование API Keycloak: Запросите учетные данные пользователя для проверки структуры

Альтернативные методы импорта

Если подход с использованием REST API продолжает не работать, вы можете:

1. Прямой импорт в базу данных: Вставьте учетные данные непосредственно в таблицу CREDENTIAL, как упоминалось в обсуждении в Google Groups

2. Пользовательский скрипт миграции: Используйте скрипт, который использует Java API Keycloak для большего контроля над процессом создания учетных данных

3. Использование пользовательского провайдера хеширования паролей: Реализуйте пользовательский провайдер хеширования, который соответствует вашей существующей реализации Argon2, как показано в примере Argon2 Password Hash Provider for Keycloak

Ключом к успешному импорту паролей Argon2 является обеспечение правильного форматирования всех параметров в виде массивов в поле credentialData и отсутствие отсутствующих обязательных параметров, особенно указания версии.

Источники

1. Миграция хешированных паролей в Keycloak - Stack Overflow
2. Создание пользователя через API Keycloak с учетными данными - GitHub Issue
3. Импорт хешированного пароля в Keycloak - Google Groups
4. Добавление пользовательского типа учетных данных - Keycloak Discourse
5. Документация API CredentialRepresentation
6. Руководство администратора сервера - Документация Red Hat

Заключение

Для успешного импорта предварительно хешированных паролей Argon2 в Keycloak:

• Используйте правильную структуру CredentialRepresentation с полями JSON secretData и credentialData
• Форматируйте все параметры алгоритма как массивы со строковыми значениями в credentialData.additionalParameters
• Включите обязательный параметр версии ("version":["19"])
• Убедитесь, что формат вашего хеша соответствует ожиданиям Keycloak
• Проверьте, что параметры точно соответствуют конфигурации Argon2 в Keycloak

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