Keycloak¶
Pentru a utiliza Keycloak împreună cu NetHSM, în vederea stocării în siguranță a cheilor private în NetHSM, permițând în același timp Keycloak să semneze token-urile de acces și să decripteze JWE, trebuie să instalați și să configurați acest furnizor de chei după cum urmează:
Declarație privind IA¶
Acest furnizor a fost dezvoltat și revizuit cu ajutorul substanțial al inteligenței artificiale.
Prepare the NetHSM¶
Pregătiți NetHSM după cum urmează. Pentru instrucțiuni detaliate, consultați secțiunea administration.
Dacă NetHSM utilizează un certificat autosemnat, notați-i amprenta digitală:
echo | openssl s_client -connect $NETHSM_HOST 2>/dev/null \ | openssl x509 -fingerprint -sha256 -noout
Creați un utilizator de tip „Operator” dedicat pentru Keycloak.
Extensia Keycloak detectează cheile, dar nu le creează. Creați manual cheile dorite:
ID-ul cheii trebuie să înceapă cu prefixul pe care îl va revendica domeniul. Alegeți o schemă de denumire adecvată, cum ar fi
kc-<realm>-<purpose>-<year>(de exemplu,kc-staff-sig-rs256-2026,kc-partners-sig-es256-2026,kc-customers-enc-oaep-2026). ID-ul devinekid, pe care Keycloak îl publică. Rotirea viitoare a cheilor se realizează prin adăugarea de ID-uri noi, motiv pentru care vă sugerăm să folosiți anul ca parte a ID-ului cheii.Mecanismele determină pentru ce algoritmi JOSE poate fi utilizată cheia:
NetHSM key type and mechanism
JOSE algorithms served
RSA+RSA_Signature_PKCS1RS256, RS384, RS512 — independent de algoritmul hash, astfel încât o singură cheie acoperă toate cele trei
RSA+RSA_Signature_PSS_SHA256/_SHA384/_SHA512PS256 / PS384 / PS512 — denumirile se referă doar la algoritmul pe care îl utilizează mecanismul
EC_P256/EC_P384/EC_P521+ECDSA_SignatureES256 / ES384 / ES512 — curba determină algoritmul
Curve25519+EdDSA_SignatureEdDSA
RSA+RSA_Decryption_OAEP_SHA1/_SHA256RSA-OAEP / RSA-OAEP-256, pentru decriptarea fișierelor JWE primite
Instalare¶
Descărcați fișierul JAR al furnizorului Keycloak NetHSM de la adresa ` <https://github.com/Nitrokey/nethsm-keycloak/releases>` __, salvați-l în folderul furnizorilor din Keycloak, de exemplu /opt/keycloak/providers/
Reconstruiți registrul furnizorilor: /opt/keycloak/bin/kc.sh build
Configurație¶
Setările pot fi specificate fie în fișierul `` conf/keycloak.conf`, fie sub formă de variabile de mediu. Cele două forme corespund acelorași setări; variabilele de mediu au prioritate, astfel încât valorile care nu sunt confidențiale pot fi stocate în fișier, iar fraza de acces să fie introdusă doar în timpul rulării.
Folosind 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¶
Este preferată în implementările în containere, deoarece fraza de acces poate fi furnizată dintr-un secret Docker sau Kubernetes, în loc să fie scrisă într-un fișier.
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...
Notă
Numele variabilei de mediu se obține automat din cheia de configurare: se adaugă prefixul KC_, se transformă în majuscule și se înlocuiesc toate - cu _. Cele două linii de subliniere duble decurg din structura cheii, spi-<spi-name>--<provider-id>--<option>, care, pentru această extensie, este SPI keys, furnizor nethsm și numele opțiunii.
See also all available configuration options.
Restart Keycloak¶
Profilul de conectare este citit doar la inițializarea fabricii de furnizori. Reporniți Keycloak.
Confirm the server configuration¶
Verificați jurnalul de pornire înainte de a configura orice domeniu. Astfel, se poate face distincția între o problemă legată de conexiune sau de datele de autentificare și o problemă legată de configurarea domeniului.
În cazul reușitei:
NetHSM key provider ready: 1 instance(s), user 'keycloak',
discovery cache PT5M, on-unavailable fail
Otherwise:
Log message |
Cause |
|---|---|
Nu apare niciun mesaj sau apare o linie de depanare care indică faptul că furnizorul este inactiv |
|
|
Adresă incorectă, blocat de un firewall, neconcordanță între codul PIN al certificatului, sau NetHSM-ul este blocat sau neconfigurat |
|
Wrong username or passphrase |
Adăugați furnizorul într-un domeniu¶
În consola de administrare, accesați Setări realm → Chei → Furnizori, alegeți Adăugați furnizor și selectați nethsm.
Field |
Înțeles |
|---|---|
Key use |
|
Key ID prefix |
Fiecare cheie NetHSM al cărei ID începe cu acest șir este publicată de acest domeniu |
Algorithm |
Algoritmul în baza căruia sunt publicate aceste chei |
Priority |
|
Enabled / Active |
Ambele trebuie să fie activate pentru ca o cheie să poată semna |
O componentă publică un singur algoritm, urmând modelul furnizorilor de chei integrați în Keycloak. Prin urmare, un realm care necesită atât RS256, cât și ES256 are două componente. Cheile aflate sub prefixul respectiv care nu pot fi utilizate cu algoritmul ales sunt omise, astfel încât un prefix poate corespunde în siguranță unui set mixt de chei.
Avertisment
Nu indicați două componente către aceeași cheie folosind algoritmi diferiți. Ambele ar publica o intrare JWKS sub același kid.
Setați prioritatea la o valoare mai mare de 100¶
Important
Un domeniu nou creat conține patru furnizori de chei generați — rsa-generated, rsa-enc-generated, hmac-generated și aes-generated — toți având prioritatea 100. Componenta NetHSM trebuie să aibă o prioritate mai mare; în caz contrar, Keycloak continuă să semneze folosind o cheie software generată, iar configurația pare să funcționeze.
O valoare de 200 pentru NetHSM este o valoare implicită rezonabilă.
Selectați algoritmul pentru tărâm¶
Setați în „ ” (Setări domeniu) → „Tokens” (Jetoane) → „Default Signature Algorithm” (Algoritm de semnătură implicit) la algoritmul configurat pe componentă. Dacă domeniul solicită un algoritm pe care componenta nu îl publică, Keycloak va recurge la o cheie generată fără a raporta o eroare.
Verificați¶
List the published keys:
curl -s https://<keycloak-host>/realms/<realm>/protocol/openid-connect/certs
Valorile „ ` ” kid` ar trebui să fie ID-urile cheilor NetHSM.
Verificarea definitivă se face prin intermediul unui token emis. Solicitați unul și decodați antetul acestuia:
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 + "==")))'
Dacă kid este ID-ul cheii NetHSM, semnătura a fost generată în interiorul HSM-ului. De asemenea, puteți verifica în paralel jurnalul NetHSM, care ar trebui să afișeze o apelare corespunzătoare.
Further Details¶
You find further details here.