Keycloak¶
Selleks, et kasutada Keycloaki koos NetHSM-iga, et salajasi võtmeid turvaliselt NetHSM-is hoida ning samal ajal võimaldada Keycloakil allkirjastada juurdepääsutokeneid ja dešifreerida JWE-sid, peate paigaldama ja konfigureerima selle võtmepakkumise järgmiselt:
Tehisintellekti avalikustamine¶
Selle teenusepakkuja väljatöötamisel ja läbivaatamisel kasutati ulatuslikult tehisintellekti abi.
Prepare the NetHSM¶
Valmistage NetHSM ette järgmiselt. Täpsemad juhised leiate jaotisest „ “.
Kui NetHSM kasutab iseallkirjastatud sertifikaati, salvesta selle sõrmejälg:
echo | openssl s_client -connect $NETHSM_HOST 2>/dev/null \ | openssl x509 -fingerprint -sha256 -noout
Keycloak-laiendus tuvastab võtmed, kuid ei loo neid. Loo soovitud võtmed käsitsi:
Võtme ID peab algama eesliitega, mida valdkond endale nõuab. Valige sobiv nimetamisskeem, näiteks
kc-<realm>-<purpose>-<year>(ntkc-staff-sig-rs256-2026,kc-partners-sig-es256-2026,kc-customers-enc-oaep-2026). Sellest ID-st saabkid, mille Keycloak avaldab. Tulevikus toimub võtmete vahetamine uute ID-de lisamise teel, mistõttu soovitame kasutada võtme ID osana aastanumbrit.**** -is määratud mehhanismid määravad kindlaks, milliste JOSE-algoritmide puhul võtit saab kasutada:
NetHSM key type and mechanism
JOSE algorithms served
RSA+RSA_Signature_PKCS1RS256, RS384, RS512 — sõltumatu hash-funktsioonist, seega üks võti katab kõiki kolme
RSA+RSA_Signature_PSS_SHA256/_SHA384/_SHA512PS256 / PS384 / PS512 — nimetused viitavad ainult algoritmile
EC_P256/EC_P384/EC_P521+ECDSA_SignatureES256 / ES384 / ES512 — kõver määrab algoritmi
Curve25519+EdDSA_SignatureEdDSA
RSA+RSA_Decryption_OAEP_SHA1/_SHA256RSA-OAEP / RSA-OAEP-256, sissetulevate JWE-de dekodeerimiseks
Paigaldamine¶
Lae alla Keycloaki NetHSM-pakkuja JAR-fail ja salvesta see Keycloaki pakkujate kausta, nt /opt/keycloak/providers/
Teenusepakkujate registri taastamine: /opt/keycloak/bin/kc.sh build
Konfiguratsioon¶
Seaded võib määrata kas failis ` `` conf/keycloak.conf` või keskkonnamuutujatena. Mõlemad vormid tähistavad samu seadeid; keskkonnamuutujad on ülimuslikud, seega võivad failis olla avalikud väärtused, kusjuures parool lisatakse alles käivitamisel.
Kasutades 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¶
Eelistatakse konteineripõhistes rakendustes, kuna salasõna saab edastada Docker’i või Kubernetesi salajase andmevälja kaudu, selle asemel et seda faili kirjutada.
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...
Märkus
Keskkonnamuutuja nimi tuletatakse automaatselt konfiguratsioonivõtmest: lisatakse ette KC_, muudetakse suurtähtedeks ning asendatakse iga - järgmisega: _. Kahekordsed alaviirud tulenevad võtme struktuurist, spi-<spi-name>--<provider-id>--<option>, mis käesoleva laienduse puhul on SPI keys, pakkuja nethsm ja valiku nimi.
See also all available configuration options.
Restart Keycloak¶
Ühendusprofiili loetakse ainult teenusepakkuja tehase algseadistamisel. Käivita Keycloak uuesti.
Confirm the server configuration¶
Enne mis tahes valdkonna konfigureerimist kontrollige käivituslogi. See aitab eristada ühendus- või autentimisandmete probleemi valdkonna konfiguratsiooni probleemist.
Edu korral:
NetHSM key provider ready: 1 instance(s), user 'keycloak',
discovery cache PT5M, on-unavailable fail
Otherwise:
Log message |
Cause |
|---|---|
Sõnum puudub või kuvatakse silumisteade, milles märgitakse, et teenusepakkuja on mitteaktiivne |
|
|
Vale aadress, tulemüüri poolt blokeeritud, sertifikaadi PIN-koodi mittevastavus või NetHSM on lukustatud või konfigureerimata |
|
Wrong username or passphrase |
Lisa teenusepakkuja valdkonda¶
Mine halduskonsolis aadressile Realm Settings → Keys → Providers, vali Add provider ning vali nethsm.
Field |
Tähendus |
|---|---|
Key use |
|
Key ID prefix |
Kõik NetHSM-võtmed, mille ID algab selle stringiga, avaldab see realm |
Algorithm |
Algoritm, mille alusel need võtmed avaldatakse |
Priority |
|
Enabled / Active |
Mõlemad peavad olema sisse lülitatud, et võti saaks allkirjastada |
Üks komponent avaldab ühe algoritmi, mis peegeldab Keycloaki sisseehitatud võtmepakkijaid. Seega on valdkonnal, mis vajab nii RS256 kui ka ES256, kaks komponenti. Eesliite all olevaid võtmeid, mis ei toeta valitud algoritmi, jäetakse vahele, mistõttu võib eesliide ohutult sobida segatud võtmete kogumiga.
Ettevaatust
Ärge suunake kahte komponenti, mis kasutavad erinevaid algoritme, samale võtmele. Mõlemad avaldaksid JWKS-kande sama kid all.
Määra prioriteet suuremaks kui 100¶
NetHSM-i puhul on mõistlikuks vaikimisi väärtuseks ` `` 200`.
Vali valdkonna jaoks sobiv algoritm¶
Määrake „ ” valikus „Realm Settings” → „Tokens” → „Default Signature Algorithm” väärtuseks „ ”, mis vastab komponendis konfigureeritud algoritmile. Kui realm nõuab algoritmi, mida komponent ei avalda, kasutab Keycloak selle asemel genereeritud võtit, ilma et selle kohta veateadet kuvataks.
Kinnita¶
List the published keys:
curl -s https://<keycloak-host>/realms/<realm>/protocol/openid-connect/certs
Väärtused „ ` “ ja „kid` “ peaksid olema NetHSM-võtme ID-d.
Lõplik kontroll toimub väljastatud tokeni abil. Taotlege seda ja dekodeerige selle päis:
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 + "==")))'
Kui kid on NetHSM-i võtme ID, siis loodi allkiri HSM-i sees. Samal ajal võid jälgida ka NetHSM-i logifaili, kus peaks olema näha vastav kutsung.
Further Details¶
You find further details here.