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
Инсталиране на приложението Nitrokey¶
Изтеглете JAR файла на NetHSM доставчика за Keycloak ` <https://github.com/Nitrokey/nethsm-keycloak/releases>` __, запазете го в папката с доставчиците на Keycloak, например /opt/keycloak/providers/
Преизграждане на регистъра на доставчиците: /opt/keycloak/bin/kc.sh build
Статична конфигурация на DNS¶
Настройките могат да бъдат зададени или във файла 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...
Note
Името на променливата на средата се извлича автоматично от конфигурационния ключ: добавя се префиксът 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 |
Добавете доставчика към реалм¶
В административната конзола отидете на Настройки на реалма → Ключове → Доставчици, изберете „ “ („Добавяне на доставчик“) и изберете nethsm.
Field |
Значение |
|---|---|
Key use |
|
Key ID prefix |
Всеки ключ NetHSM, чийто идентификатор започва с този низ, се публикува от тази реалма |
Algorithm |
Алгоритъмът, съгласно който се публикуват тези ключове |
Priority |
|
Enabled / Active |
И двете трябва да са включени, за да може ключът да се подпише |
Всеки компонент поддържа един алгоритъм, което отразява вградените доставчици на ключове в Keycloak. Следователно, една реалма, която се нуждае както от RS256, така и от ES256, разполага с два компонента. Ключовете под даден префикс, които не поддържат избрания алгоритъм, се пропускат, така че един префикс може спокойно да съответства на смесен набор от ключове.
Caution
Не насочвайте два компонента към един и същ ключ с различни алгоритми. И двата биха публикували JWKS запис под същия kid.
Задайте приоритет над 100¶
Important
В новосъздаденото царство има четири генерирани доставчика на ключове — rsa-generated, rsa-enc-generated, hmac-generated и aes-generated — всички с приоритет 100. Компонентът NetHSM трябва да има по-висок приоритет, в противен случай Keycloak продължава да подписва с генериран софтуерен ключ и конфигурацията изглежда, че работи.
Стойността „ 200“ за NetHSM е подходяща по подразбиране.
Изберете алгоритъма за реалма¶
Задайте в „ “ (Настройки на реалма) → „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.