Keycloak

Da bi lahko uporabljali Keycloak skupaj z NetHSM za varno shranjevanje zasebnih ključev v NetHSM, hkrati pa omogočili Keycloaku podpisovanje dostopnih žetonov in dešifriranje JWE, morate namestiti in konfigurirati tega ponudnika ključev na naslednji način:

Razkritje informacij o umetni inteligenci

Ta ponudnik je bil razvit in pregledan z obsežno pomočjo umetne inteligence.

Prepare the NetHSM

NetHSM pripravite na naslednji način. Podrobna navodila najdete v poglavju »Upravljanje «.

  • Če NetHSM uporablja samopodpisano potrdilo, zabeležite njegov prstni odtis:

    echo | openssl s_client -connect $NETHSM_HOST 2>/dev/null \
  | openssl x509 -fingerprint -sha256 -noout

  • Ustvarite uporabnika »Operator«, namenjenega izključno za Keycloak.

  • Razširitev Keycloak odkrije ključe, vendar jih ne ustvari. Želene ključe ustvarite ročno:

    • ID ključa se mora začeti s predpono, ki jo bo uporabljal realm. Izberite ustrezen sistem poimenovanja, na primer kc-<realm>-<purpose>-<year> (na primer kc-staff-sig-rs256-2026, kc-partners-sig-es256-2026, kc-customers-enc-oaep-2026). ID postane kid, ki ga objavi Keycloak. Prihodnja rotacija ključev se izvaja z dodajanjem novih ID-jev, zato priporočamo, da kot del ID-ja ključa uporabite letnico.

    • Mehanizmi določajo, za katere algoritme JOSE se ključ lahko uporablja:

      NetHSM key type and mechanism

      JOSE algorithms served

      RSA + RSA_Signature_PKCS1

      RS256, RS384, RS512 — neodvisni od algoritma hash, zato en ključ pokriva vse tri

      RSA + RSA_Signature_PSS_SHA256 / _SHA384 / _SHA512

      PS256 / PS384 / PS512 — imena mehanizmov se nanašajo le na algoritem

      EC_P256 / EC_P384 / EC_P521 + ECDSA_Signature

      ES256 / ES384 / ES512 — krivulja določa algoritem

      Curve25519 + EdDSA_Signature

      EdDSA

      RSA + RSA_Decryption_OAEP_SHA1 / _SHA256

      RSA-OAEP / RSA-OAEP-256, za dešifriranje vhodnih JWE

Namestitev

Prenesite datoteko JAR ponudnika Keycloak NetHSM ` <https://github.com/Nitrokey/nethsm-keycloak/releases>` __ in jo shranite v mapo ponudnikov v Keycloaku, npr. /opt/keycloak/providers/

Ponovna vzpostavitev registra ponudnikov: /opt/keycloak/bin/kc.sh build

Konfiguracija

Nastavitve se lahko navedejo bodisi v datoteki conf/keycloak.conf bodisi kot spremenljivke okolja. Obe obliki predstavljata enake nastavitve; spremenljivke okolja imajo prednost, zato se vrednosti, ki niso zaupne, lahko shranijo v datoteki, medtem ko se geslo vnese šele ob izvajanju programa.

Uporaba 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

To je prednostna možnost pri namestitvah v kontejnerjih, saj je geslo mogoče pridobiti iz skrivnosti Dockerja ali Kubernetesa, namesto da bi ga bilo treba zapisati v datoteko.

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...

Opomba

Ime spremenljivke okolja se avtomatsko izpelje iz konfiguracijskega ključa: pred njim se doda predpona KC_, pretvori se v velike črke, vsak - pa se nadomesti z _. Dvojni podčrtaji izhajajo iz strukture ključa, spi-<spi-name>--<provider-id>--<option>, ki za to razširitev obsega SPI keys, ponudnika nethsm ter ime možnosti.

See also all available configuration options.

Restart Keycloak

Profil povezave se prebere le ob inicializaciji tovarne ponudnikov. Ponovno zaženite Keycloak.

Confirm the server configuration

Preden konfigurirate katero koli področje, preverite dnevnik zagona. S tem boste ločili težave s povezavo ali poverilnicami od težav s konfiguracijo področja.

Ob uspehu:

NetHSM key provider ready: 1 instance(s), user 'keycloak',
discovery cache PT5M, on-unavailable fail

Otherwise:

Log message

Cause

Ni sporočila ali pa se prikaže vrstica za odpravljanje napak, ki navaja, da je ponudnik neaktiven

url is not set

NetHSM is not reachable or not Operational at startup

Napačen naslov, blokiran s požarnim zidom, neskladje PIN-kode certifikata ali pa je NetHSM zaklenjen ali ni bil konfiguriran

NetHSM rejected the configured credential with HTTP 401

Wrong username or passphrase

Dodaj ponudnika v področje

V upraviteljski konzoli odprite Nastavitve realma → Ključi → Ponudniki, izberite Dodaj ponudnika in izberite nethsm.

Field

Pomen

Key use

sig za podpisovanje žetonov, enc za dešifriranje prejetih JWE-jev

Key ID prefix

Vsak ključ NetHSM, katerega ID se začne s tem nizom, je objavljen v tem področju

Algorithm

Algoritem, v skladu s katerim so ti ključi objavljeni

Priority

Glej Nastavi prioriteto nad 100

Enabled / Active

Obe morata biti vklopljeni, da bi ključ lahko podpisal

Ena komponenta podpira en algoritem, kar odraža vgrajene ponudnike ključev v Keycloaku. Realm, ki potrebuje tako RS256 kot ES256, ima zato dve komponenti. Ključi pod predpono, ki ne podpirajo izbranega algoritma, se preskočijo, zato se predpona lahko brez težav ujema z mešanim naborom ključev.

Previdno

Ne usmerjajte dveh komponent na isti ključ z različnimi algoritmi. Obe bi namreč objavili vnos JWKS pod isto kid.

Nastavite prioriteto nad 100

Pomembno

Novo ustvarjeno kraljestvo vsebuje štiri generirane ponudnike ključev — rsa-generated, rsa-enc-generated, hmac-generated in aes-generated — vsi s prioriteto 100. Komponenta NetHSM mora imeti višjo prioriteto, sicer Keycloak nadaljuje s podpisovanjem z generiranim programskim ključem in se zdi, da konfiguracija deluje.

Vrednost 200 za NetHSM je primerna privzeta vrednost.

Izberite algoritem za področje

V nastavitvah področja » « ( Realm Settings) → »Tokens« → »Default Signature Algorithm« ( ) nastavite algoritem, ki je konfiguriran na komponenti. Če področje zahteva algoritem, ki ga komponenta ne objavlja, Keycloak uporabi generirani ključ, ne da bi pri tem poročal o napaki.

Preveri

List the published keys:

curl -s https://<keycloak-host>/realms/<realm>/protocol/openid-connect/certs

Vrednosti v datoteki » ` « kid` morajo biti identifikatorji ključev NetHSM.

Končni preizkus je izdan žeton. Zahtevajte ga in dekodirajte njegov glavo:

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 + "==")))'

Če je kid identifikacijska številka ključa NetHSM, je bil podpis ustvarjen znotraj HSM-ja. Hkrati lahko spremljate tudi dnevnik NetHSM-ja, v katerem bi moral biti prikazan ustrezen klic.

Načrt za primer, ko NetHSM ni na voljo

Če NetHSM ni dosegljiv in v predpomnilniku ni shranjenih metapodatkov o ključih, področje nima uporabnih ključev, zato izdaja žetonov ne uspe, namesto da bi se sistem preusmeril na generiran programski ključ.

Opozorilo

Če privzeti algoritem za podpisovanje v domeni zagotavljajo ključi NetHSM in NetHSM postane nedostopen, ni mogoče izdati niti administrativnih žetonov za to domeno. Upraviteljski API je v tem primeru nedostopen za odpravo težave.

Obnovitev se izvede prek nastavitev strežnika in ne prek upraviteljske konzole: nastavite spi-keys--nethsm--on-unavailable=degrade in ponovno zaženite strežnik ali onemogočite komponento.

Zato najprej nastavite testno področje, področje master pa pustite na ključih, ki jih je sam Keycloak ustvaril, da bo administrativna konzola še naprej dostopna.

Further Details

You find further details here.