Keycloak¶
Чтобы использовать Keycloak с NetHSM для безопасного хранения закрытых ключей в NetHSM, одновременно позволяя Keycloak подписывать токены доступа и расшифровывать JWE, необходимо установить и настроить этот поставщик ключей следующим образом:
Раскрытие информации об ИИ¶
Данный контент был разработан и проверен с использованием значительной помощи искусственного интеллекта.
Prepare the NetHSM¶
Подготовьте NetHSM следующим образом. Подробные инструкции см. в разделе «Администрирование ».
Если NetHSM использует самоподписанный сертификат, запишите его отпечаток:
echo | openssl s_client -connect $NETHSM_HOST 2>/dev/null \ | openssl x509 -fingerprint -sha256 -noout
Создайте пользователя-оператора, предназначенного исключительно для Keycloak.
Расширение Keycloak обнаруживает ключи, но не создаёт их. Создайте нужные ключи вручную:
Идентификатор ключа должен начинаться с префикса, который будет использоваться в данной области. Выберите подходящую схему именования, например:
kc-<realm>-<purpose>-<year>(например,kc-staff-sig-rs256-2026,kc-partners-sig-es256-2026,kc-customers-enc-oaep-2026). Этот идентификатор станетkid, который публикует Keycloak. В будущем ротация ключей будет осуществляться путем добавления новых идентификаторов, поэтому мы рекомендуем использовать год в качестве части идентификатора ключа.Механизмы определяют, для каких алгоритмов JOSE может использоваться данный ключ:
NetHSM key type and mechanism
JOSE algorithms served
RSA+RSA_Signature_PKCS1RS256, RS384, RS512 — не зависят от алгоритма хеширования, поэтому один ключ подходит для всех трёх
RSA+RSA_Signature_PSS_SHA256/_SHA384/_SHA512PS256 / PS384 / PS512 — в названиях этих механизмов указаны только алгоритмы
EC_P256/EC_P384/EC_P521+ECDSA_SignatureES256 / ES384 / ES512 — кривая определяет алгоритм
Curve25519+EdDSA_SignatureEdDSA
RSA+RSA_Decryption_OAEP_SHA1/_SHA256RSA-OAEP / RSA-OAEP-256 — для расшифровки входящих JWE
Установка¶
Скачайте JAR-файл провайдера Keycloak NetHSM ` <https://github.com/Nitrokey/nethsm-keycloak/releases>` __, сохраните его в папке провайдеров Keycloak, например: /opt/keycloak/providers/
Перестроить реестр провайдеров: /opt/keycloak/bin/kc.sh build
Конфигурация¶
Параметры можно указать либо в файле ` `` conf/keycloak.conf`, либо в виде переменных среды. Обе формы представляют собой одни и те же настройки; при этом переменные среды имеют приоритет, поэтому в файле могут храниться неконфиденциальные значения, а парольная фраза добавляется только во время выполнения.
С помощью conf/keycloak.conf¶
spi-keys--nethsm--url=https://nethsm.internal:8443/api/v1
spi-keys--nethsm--username=keycloak
spi-keys--nethsm--passphrase=<passphrase>
spi-keys--nethsm--tls-fingerprints=aabbcc...
Using environment variables¶
Предпочтительно при развертывании в контейнерах, поскольку парольную фразу можно получить из секрета Docker или Kubernetes вместо записи в файл.
KC_SPI_KEYS__NETHSM__URL=https://nethsm.internal:8443/api/v1
KC_SPI_KEYS__NETHSM__USERNAME=keycloak
KC_SPI_KEYS__NETHSM__PASSPHRASE="<passphrase>"
KC_SPI_KEYS__NETHSM__TLS_FINGERPRINTS=aabbcc...
Примечание
Имя переменной окружения формируется автоматически на основе ключа конфигурации: к нему добавляется префикс KC_, оно преобразуется в верхний регистр, а все - заменяются на _. Двойные подчеркивания обусловлены структурой ключа: spi-<spi-name>--<provider-id>--<option>, которая для данного расширения состоит из SPI keys, провайдера nethsm и имени опции.
See also all available configuration options.
Restart Keycloak¶
Профиль подключения считывается только при инициализации фабрики провайдеров. Перезапустите Keycloak.
Confirm the server configuration¶
Перед настройкой любого реалма проверьте журнал запуска. Это позволит отличить проблему с подключением или учетными данными от проблемы с настройкой реалма.
В случае успеха:
NetHSM key provider ready: 1 instance(s), user 'keycloak',
discovery cache PT5M, on-unavailable fail
Otherwise:
Log message |
Cause |
|---|---|
Сообщение отсутствует или отображается отладочная строка, указывающая, что провайдер неактивен |
|
|
Неверный адрес, блокировка брандмауэром, несоответствие PIN-кода сертификата или устройство NetHSM заблокировано либо не настроено |
|
Wrong username or passphrase |
Добавить провайдера в область¶
В консоли администратора перейдите в раздел «Настройки реалма» ( ) → «Ключи» (Keys) → «Провайдеры» (Providers), выберите « », нажмите «Добавить провайдера» (Add provider) и выберите nethsm.
Field |
Значение |
|---|---|
Key use |
|
Key ID prefix |
Каждый ключ NetHSM, идентификатор которого начинается с этой строки, публикуется данной областью |
Algorithm |
Алгоритм, в соответствии с которым публикуются эти ключи |
Priority |
|
Enabled / Active |
Оба параметра должны быть включены для ключа, который должен использоваться для подписи |
Один компонент поддерживает один алгоритм, что соответствует встроенным поставщикам ключей Keycloak. Таким образом, для реалма, в котором требуются как RS256, так и ES256, необходимо два компонента. Ключи с префиксом, которые не поддерживают выбранный алгоритм, пропускаются, поэтому префикс может безопасно соответствовать смешанному набору ключей.
Осторожно
Не следует назначать один и тот же ключ двум компонентам, использующим разные алгоритмы. В обоих случаях будет опубликована запись JWKS под одним и тем же kid.
Установите приоритет выше 100¶
Важно
Вновь созданное царство содержит четыре сгенерированных поставщика ключей — rsa-generated, rsa-enc-generated, hmac-generated и aes-generated — все с приоритетом 100. Компонент NetHSM должен иметь более высокий приоритет, в противном случае Keycloak продолжит подписывать данные с помощью сгенерированного программного ключа, и конфигурация будет казаться работоспособной.
Для параметра NetHSM разумным значением по умолчанию является 200.
Выберите алгоритм для области¶
В настройках реалма « » (Настройки реалма) → «Tokens» (Токены) → «Default Signature Algorithm» (Алгоритм подписи по умолчанию) установите значение, соответствующее алгоритму, настроенному в компоненте. Если реалм запрашивает алгоритм, который компонент не публикует, Keycloak использует сгенерированный ключ, не выдавая ошибку.
Проверить¶
List the published keys:
curl -s https://<keycloak-host>/realms/<realm>/protocol/openid-connect/certs
Значения kid должны соответствовать идентификаторам ключей NetHSM.
Окончательной проверкой служит выданный токен. Запросите его и расшифруйте его заголовок:
curl -s \
-d "client_id=<client>" \
-d "client_secret=<secret>" \
-d "grant_type=client_credentials" \
https://$NETHSM_HOST/realms/<realm>/protocol/openid-connect/token \
| python3 -c 'import sys, json, base64
header = json.load(sys.stdin)["access_token"].split(".")[0]
print(json.loads(base64.urlsafe_b64decode(header + "==")))'
Если kid — это идентификатор ключа NetHSM, значит, подпись была сгенерирована внутри HSM. Вы также можете параллельно просматривать журнал NetHSM, в котором должен отобразиться соответствующий вызов.
Further Details¶
You find further details here.