Keycloak¶
Chcete-li používat Keycloak s NetHSM k bezpečnému ukládání soukromých klíčů v NetHSM a zároveň umožnit Keycloaku podepisovat přístupové tokeny a dešifrovat JWE, musíte nainstalovat a nakonfigurovat tohoto poskytovatele klíčů následujícím způsobem:
Informace o umělé inteligenci¶
Tento poskytovatel byl vyvinut a zkontrolován s významnou podporou umělé inteligence.
Prepare the NetHSM¶
Připravte zařízení NetHSM následujícím způsobem. Podrobné pokyny najdete v části administration.
Pokud NetHSM používá certifikát s vlastním podpisem, zaznamenejte jeho otisk:
echo | openssl s_client -connect $NETHSM_HOST 2>/dev/null \ | openssl x509 -fingerprint -sha256 -noout
Vytvořte uživatele typu „Operator“ určeného výhradně pro Keycloak.
Rozšíření Keycloak vyhledává klíče, ale nevytváří je. Požadované klíče vytvořte ručně:
ID klíče musí začínat předponou, kterou si daná doména vyhradí. Zvolte vhodné schéma pojmenování, například
kc-<realm>-<purpose>-<year>(napříkladkc-staff-sig-rs256-2026,kc-partners-sig-es256-2026,kc-customers-enc-oaep-2026). Toto ID se stanekid, které Keycloak zveřejní. Budoucí obměna klíčů se provádí přidáním nových ID, proto doporučujeme použít rok jako součást ID klíče.Mechanismy určují, pro které algoritmy JOSE lze daný klíč použít:
NetHSM key type and mechanism
JOSE algorithms served
RSA+RSA_Signature_PKCS1RS256, RS384, RS512 – nezávislé na typu hash, takže jeden klíč pokrývá všechny tři
RSA+RSA_Signature_PSS_SHA256/_SHA384/_SHA512PS256 / PS384 / PS512 — názvy mechanismů odkazují pouze na algoritmus
EC_P256/EC_P384/EC_P521+ECDSA_SignatureES256 / ES384 / ES512 — křivka určuje algoritmus
Curve25519+EdDSA_SignatureEdDSA
RSA+RSA_Decryption_OAEP_SHA1/_SHA256RSA-OAEP / RSA-OAEP-256, pro dešifrování příchozích JWE
Instalace¶
Stáhněte si soubor JAR s poskytovatelem Keycloak NetHSM ` <https://github.com/Nitrokey/nethsm-keycloak/releases>` __ a uložte jej do složky poskytovatelů Keycloaku, např. /opt/keycloak/providers/
Obnovit registr poskytovatelů: /opt/keycloak/bin/kc.sh build
Konfigurace¶
Nastavení lze zadat buď v souboru conf/keycloak.conf, nebo jako proměnné prostředí. Obě formy představují stejná nastavení; proměnné prostředí mají přednost, takže hodnoty, které nejsou důvěrné, mohou být uloženy v souboru a při spuštění se doplní pouze heslo.
Použití 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¶
Toto řešení se upřednostňuje při nasazení v kontejnerech, protože přístupovou frázi lze získat z tajného klíče Dockeru nebo Kubernetes, místo aby byla zapsána do souboru.
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...
Poznámka
Název proměnné prostředí se odvozuje automaticky z konfiguračního klíče: před klíče se přidá předpona KC_, převede se na velká písmena a každý výskyt - se nahradí _. Dvojité podtržítko vyplývá ze struktury klíče, spi-<spi-name>--<provider-id>--<option>, která pro toto rozšíření zahrnuje SPI keys, poskytovatele nethsm a název volby.
See also all available configuration options.
Restart Keycloak¶
Profil připojení se načte pouze při inicializaci továrny poskytovatelů. Restartujte Keycloak.
Confirm the server configuration¶
Před konfigurací jakékoli oblasti zkontrolujte protokol spouštění. Tímto způsobem lze odlišit problém s připojením nebo přihlašovacími údaji od problému s konfigurací oblasti.
V případě úspěchu:
NetHSM key provider ready: 1 instance(s), user 'keycloak',
discovery cache PT5M, on-unavailable fail
Otherwise:
Log message |
Cause |
|---|---|
Žádná zpráva nebo ladicí řádek s informací, že poskytovatel je neaktivní |
|
|
Nesprávná adresa, blokování firewallem, neshoda PIN kódu certifikátu nebo je zařízení NetHSM uzamčeno či není nakonfigurováno |
|
Wrong username or passphrase |
Přidat poskytovatele do sféry¶
V administrační konzoli přejděte na Nastavení realmů → Klíče → Poskytovatelé, vyberte možnost „ “ (Přidat poskytovatele) a vyberte nethsm.
Field |
Význam |
|---|---|
Key use |
|
Key ID prefix |
Každý klíč NetHSM, jehož ID začíná tímto řetězcem, je zveřejněn touto doménou |
Algorithm |
Algoritmus, na jehož základě jsou tyto klíče zveřejňovány |
Priority |
|
Enabled / Active |
Aby klíč mohl podepsat, musí být zapnuty obě funkce |
Jedna komponenta podporuje jeden algoritmus, což odpovídá vestavěným poskytovatelům klíčů v Keycloaku. Realm, který vyžaduje jak RS256, tak ES256, má proto dvě komponenty. Klíče pod daným prefixem, které nepodporují zvolený algoritmus, jsou přeskočeny, takže prefix může bez obav odpovídat smíšené sadě klíčů.
Upozornění
Nenastavujte dvě komponenty tak, aby používaly stejný klíč s různými algoritmy. Obě by totiž zveřejnily záznam JWKS pod stejným kid.
Nastavte prioritu na hodnotu vyšší než 100¶
Důležité
Nově vytvořená doména obsahuje čtyři vygenerované poskytovatele klíčů — rsa-generated, rsa-enc-generated, hmac-generated a aes-generated — všechny s prioritou 100. Komponenta NetHSM musí mít vyšší prioritu, jinak Keycloak pokračuje v podepisování pomocí vygenerovaného softwarového klíče a konfigurace se jeví jako funkční.
Pro NetHSM je jako rozumné výchozí nastavení hodnota 200.
Vyberte algoritmus pro danou oblast¶
V nastavení „ “ (Nastavení domény) → „Tokens“ (Tokeny) → „Default Signature Algorithm“ (Výchozí algoritmus podpisu) nastavte algoritmus nakonfigurovaný v dané komponentě. Pokud doména požaduje algoritmus, který komponenta nezveřejňuje, Keycloak použije generovaný klíč, aniž by vygeneroval chybovou zprávu.
Ověřit¶
List the published keys:
curl -s https://<keycloak-host>/realms/<realm>/protocol/openid-connect/certs
Hodnoty v souboru „ ` “ kid` by měly odpovídat identifikátorům klíčů NetHSM.
Rozhodujícím důkazem je vydaný token. Požádejte o něj a dekódujte jeho hlavičku:
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 + "==")))'
Pokud je kid identifikátorem klíče NetHSM, byl podpis vygenerován uvnitř HSM. Můžete také souběžně sledovat protokol NetHSM, kde by se mělo objevit příslušné volání.
Further Details¶
You find further details here.