Keycloak¶
Ahhoz, hogy a Keycloak szolgáltatást a NetHSM-mel együtt használhassa – így a titkos kulcsokat biztonságosan tárolhassa a NetHSM-ben, miközben a Keycloak aláírhatja a hozzáférési tokeneket és visszafejtheti a JWE-ket –, telepítenie és konfigurálnia kell ezt a kulcsszolgáltatót az alábbiak szerint:
Mesterséges intelligencia – közzétételi kötelezettség¶
Ezt a szolgáltatót jelentős mértékű mesterséges intelligencia segítségével fejlesztették ki és vizsgálták át.
Prepare the NetHSM¶
A NetHSM-et az alábbiak szerint állítsa be. A részletes utasításokat a „ -kezelés” című szakaszban találja:.
Ha a NetHSM önaláírt tanúsítványt használ, jegyezze fel annak ujjlenyomatát:
echo | openssl s_client -connect $NETHSM_HOST 2>/dev/null \ | openssl x509 -fingerprint -sha256 -noout
Hozzon létre egy „Operator” felhasználót, amely kizárólag a Keycloak számára van fenntartva.
A Keycloak-bővítmény ( ) felismeri a kulcsokat, de nem hozza létre őket. A kívánt kulcsokat kézzel kell létrehozni:
A kulcsazonosítónak ( ) a tartomány által igényelt előtaggal kell kezdődnie. Válasszon megfelelő névadási sémát, például
kc-<realm>-<purpose>-<year>(példáulkc-staff-sig-rs256-2026,kc-partners-sig-es256-2026,kc-customers-enc-oaep-2026). Az azonosító lesz az akid, amelyet a Keycloak közzétesz. A jövőbeli kulcsváltás új azonosítók hozzáadásával történik, ezért javasoljuk, hogy az azonosító részeként az évet is használja.A oldalon található mechanizmusok határozzák meg, hogy a kulcs mely JOSE-algoritmusokhoz használható:
NetHSM key type and mechanism
JOSE algorithms served
RSA+RSA_Signature_PKCS1RS256, RS384, RS512 — hash-független, így egy kulcs mindháromra érvényes
RSA+RSA_Signature_PSS_SHA256/_SHA384/_SHA512PS256 / PS384 / PS512 — a mechanizmus nevei kizárólag az algoritmusra utalnak
EC_P256/EC_P384/EC_P521+ECDSA_SignatureES256 / ES384 / ES512 — a görbe határozza meg az algoritmust
Curve25519+EdDSA_SignatureEdDSA
RSA+RSA_Decryption_OAEP_SHA1/_SHA256RSA-OAEP / RSA-OAEP-256, a bejövő JWE-k visszafejtéséhez
Telepítés¶
Töltsd le a Keycloak NetHSM szolgáltató „ ” JAR-fájlját, és mentsd el a Keycloak szolgáltatói mappájába, pl. /opt/keycloak/providers/
A szolgáltatói nyilvántartás újjáépítése: /opt/keycloak/bin/kc.sh build
Konfiguráció¶
A beállításokat megadhatjuk akár a ` `` conf/keycloak.conf` fájlban, akár környezeti változókként. A két forma ugyanazt a beállítást jelenti; a környezeti változók élveznek elsőbbséget, így a nem titkos értékek a fájlban maradhatnak, és csak a jelszót kell futásidőben beilleszteni.
` használata 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¶
Konténeres telepítések esetén előnyösebb, mivel a jelszót fájlba írás helyett egy Docker- vagy Kubernetes-titokból lehet megadni.
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...
Megjegyzés
A környezeti változó neve automatikusan a konfigurációs kulcsból származik: előtte a „ ` ” KC_` előtagot kell hozzáadni, nagybetűvé kell alakítani, majd minden „ ` ” -` kifejezést „ ` ” _`-re kell cserélni. A kettős aláhúzójelek a kulcs szerkezetéből adódnak: „ ` ” spi-<spi-name>–<provider-id>–<option>`, amely ebben a kiterjesztésben az SPI-t jelenti: „ ` ” keys`, a szolgáltatót: „ ` ” nethsm`, valamint az opció nevét.
See also all available configuration options.
Restart Keycloak¶
A kapcsolati profil csak a szolgáltatói gyár inicializálásakor kerül beolvasásra. Indítsa újra a Keycloakot.
Confirm the server configuration¶
Mielőtt bármelyik tartományt konfigurálná, ellenőrizze az indítási naplót. Ezzel megkülönböztetheti a kapcsolati vagy hitelesítési problémákat a tartománykonfigurációs problémáktól.
Siker esetén:
NetHSM key provider ready: 1 instance(s), user 'keycloak',
discovery cache PT5M, on-unavailable fail
Otherwise:
Log message |
Cause |
|---|---|
Nincs üzenet, vagy egy hibakeresési sor, amely jelzi, hogy a szolgáltató inaktív |
|
|
Helytelen cím, tűzfal általi blokkolás, tanúsítvány PIN-kódjának eltérése, vagy a NetHSM zárolva van, illetve nincs beállítva |
|
Wrong username or passphrase |
A szolgáltató hozzáadása egy tartományhoz¶
Az adminisztrációs konzolban lépjen a következő menüpontra: Realm Settings → Keys → Providers, válassza ki a „ ” lehetőséget, majd kattintson az „Add provider” gombra, és válassza ki a „ nethsm” elemet.
Field |
Jelentés |
|---|---|
Key use |
|
Key ID prefix |
Minden olyan NetHSM-kulcsot, amelynek azonosítója ezzel a karakterlánccal kezdődik, ez a tartomány teszi közzé |
Algorithm |
Az algoritmus, amely alapján ezeket a kulcsokat közzétették |
Priority |
|
Enabled / Active |
Mindkettőnek be kell lennie kapcsolva ahhoz, hogy egy kulcs aláírhasson |
Egy komponens egy algoritmust támogat, ami a Keycloak beépített kulcsszolgáltatóit tükrözi. Egy olyan tartománynak, amelynek mind az RS256-ra, mind az ES256-ra szüksége van, ezért két komponense van. Az előtag alatt található kulcsok közül azokat, amelyek nem támogatják a kiválasztott algoritmust, a rendszer kihagyja, így egy előtag nyugodtan illeszkedhet vegyes kulcskészlethez is.
Figyelem
Ne rendeljen két komponenst ugyanahhoz a kulcshoz különböző algoritmusokkal. Mindkettő ugyanazon a kid alatt tenné közzé a JWKS-bejegyzést.
Állítsa a prioritást 100 fölé¶
Fontos
Egy újonnan létrehozott tartomány négy generált kulcsszolgáltatót tartalmaz — rsa-generated, rsa-enc-generated, hmac-generated és aes-generated — mindegyik prioritása 100. A NetHSM-komponensnek magasabb prioritással kell rendelkeznie, ellenkező esetben a Keycloak továbbra is a generált szoftverkulccsal ír alá, és úgy tűnik, hogy a konfiguráció működik.
A NetHSM esetében a ` `` 200` értékek ésszerű alapértelmezett beállításnak számítanak.
Válassza ki a birodalom algoritmusát¶
Állítsa be a „ ” ( ) menüpont alatt a Realm Settings → Tokens → Default Signature Algorithm (Realm beállítások → Tokenek → Alapértelmezett aláírási algoritmus) mezőt értékre, amely megegyezik a komponensen konfigurált algoritmussal. Ha a realm olyan algoritmust kér, amelyet a komponens nem tesz közzé, a Keycloak hibaüzenet nélkül egy generált kulcsra vált át.
Ellenőrizze¶
List the published keys:
curl -s https://<keycloak-host>/realms/<realm>/protocol/openid-connect/certs
A „ ` ” kid` értékeknek a NetHSM kulcsazonosítóknak kell lenniük.
A végleges ellenőrzés egy kiadott token. Kérjen egyet, és dekódolja a fejlécét:
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 + "==")))'
Ha kid a NetHSM kulcsazonosítója, akkor az aláírás a HSM-en belül készült. Ezzel párhuzamosan megnézheted a NetHSM naplófájlját is, amelyben egy megfelelő hívásnak kell szerepelnie.
Further Details¶
You find further details here.