Keycloak

Ak chcete používať Keycloak spolu s NetHSM na bezpečné ukladanie súkromných kľúčov v NetHSM a zároveň umožniť Keycloaku podpisovať prístupové tokeny a dešifrovať JWE, musíte nainštalovať a nakonfigurovať tohto poskytovateľa kľúčov nasledovne:

Informácie o umelej inteligencii

Tento poskytovateľ bol vyvinutý a posúdený s výraznou podporou umelej inteligencie.

Prepare the NetHSM

Pripravte zariadenie NetHSM nasledovne. Podrobné pokyny nájdete v časti „ administration“.

  • Ak NetHSM používa certifikát s vlastným podpisom, zaznamenajte jeho odtlačok:

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

  • Vytvorte používateľa typu „Operator“ určeného výhradne pre Keycloak.

  • Rozšírenie Keycloak vyhľadáva kľúče, ale nevytvára ich. Vytvorte požadované kľúče ručne:

    • ID kľúča sa musí začínať predponou, ktorú si bude doména nárokovať. Zvoľte vhodné schéma pomenovania, napríklad kc-<realm>-<purpose>-<year> (napríklad kc-staff-sig-rs256-2026, kc-partners-sig-es256-2026, kc-customers-enc-oaep-2026). Toto ID sa stane kid, ktoré Keycloak zverejňuje. Budúca rotácia kľúčov sa vykonáva pridaním nových ID, preto odporúčame použiť rok ako súčasť ID kľúča.

    • Mechanizmy určujú, pre ktoré algoritmy JOSE môže kľúč slúžiť:

      NetHSM key type and mechanism

      JOSE algorithms served

      RSA + RSA_Signature_PKCS1

      RS256, RS384, RS512 — nezávislé na hashovacom algoritme, takže jeden kľúč pokrýva všetky tri

      RSA + RSA_Signature_PSS_SHA256 / _SHA384 / _SHA512

      PS256 / PS384 / PS512 — ide len o názvy algoritmov

      EC_P256 / EC_P384 / EC_P521 + ECDSA_Signature

      ES256 / ES384 / ES512 — krivka určuje algoritmus

      Curve25519 + EdDSA_Signature

      EdDSA

      RSA + RSA_Decryption_OAEP_SHA1 / _SHA256

      RSA-OAEP / RSA-OAEP-256, na dešifrovanie prichádzajúcich JWE

Inštalácia

Stiahnite si súbor JAR poskytovateľa Keycloak NetHSM ` <https://github.com/Nitrokey/nethsm-keycloak/releases>` __, uložte ho do priečinka poskytovateľov Keycloaku, napr. /opt/keycloak/providers/

Obnovte registre poskytovateľov: /opt/keycloak/bin/kc.sh build

Konfigurácia

Nastavenia je možné zadať buď v súbore conf/keycloak.conf, alebo ako premenné prostredia. Obe formy predstavujú rovnaké nastavenia; premenné prostredia majú prednosť, takže hodnoty, ktoré nie sú dôverné, môžu zostať v súbore a pri spustení sa doplní iba heslo.

Použitie 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

Uprednostňuje sa pri nasadzovaní v kontajneroch, pretože heslo je možné získať z tajného kľúča v Docker alebo Kubernetes namiesto toho, aby bolo zapísané do súboru.

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ázov premennej prostredia sa automaticky odvodí z konfiguračného kľúča: na začiatok sa pridá predpona KC_, premení sa na veľké písmená a každý výskyt - sa nahradí _. Dvojité podčiarknutia vyplývajú zo štruktúry kľúča, spi-<spi-name>--<provider-id>--<option>, ktorá pre toto rozšírenie pozostáva z SPI keys, poskytovateľa nethsm a názvu možnosti.

See also all available configuration options.

Restart Keycloak

Profil pripojenia sa načíta iba pri inicializácii továrne poskytovateľov. Spustite Keycloak nanovo.

Confirm the server configuration

Pred konfiguráciou akejkoľvek sféry skontrolujte protokol spúšťania. Týmto spôsobom odlíšite problém s pripojením alebo prihlasovacími údajmi od problému s konfiguráciou sféry.

V prípade úspechu:

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

Otherwise:

Log message

Cause

Žiadna správa alebo ladiaci riadok uvádzajúci, že poskytovateľ je neaktívny

url is not set

NetHSM is not reachable or not Operational at startup

Nesprávna adresa, blokovanie bránou firewall, nezhoda PIN kódu certifikátu alebo je NetHSM uzamknutý alebo nenakonfigurovaný

NetHSM rejected the configured credential with HTTP 401

Wrong username or passphrase

Pridať poskytovateľa do sféry

V administrátorskej konzole prejdite na Nastavenia sféry → Kľúče → Poskytovatelia, vyberte možnosť „ “ (Pridať poskytovateľa) a vyberte nethsm.

Field

Význam

Key use

sig na podpisovanie tokenov, enc na dešifrovanie prichádzajúcich JWE

Key ID prefix

Každý kľúč NetHSM, ktorého ID začína týmto reťazcom, je zverejnený touto sférou

Algorithm

Algoritmus, na základe ktorého sú tieto kľúče zverejnené

Priority

Pozri Nastavte prioritu na hodnotu vyššiu ako 100

Enabled / Active

Obe musia byť zapnuté, aby kľúč mohol podpísať

Jedna komponenta poskytuje jeden algoritmus, čo zodpovedá integrovaným poskytovateľom kľúčov v Keycloaku. Realm, ktorý potrebuje algoritmy RS256 aj ES256, má preto dve komponenty. Kľúče pod danou predponou, ktoré nepodporujú zvolený algoritmus, sa preskočia, takže predpona môže bez obáv zodpovedať zmiešanej sade kľúčov.

Upozornenie

Nenastavujte dva komponenty tak, aby používali rovnaký kľúč s rôznymi algoritmami. Oba by totiž publikovali záznam JWKS pod rovnakým kid.

Nastavte prioritu na hodnotu vyššiu ako 100

Dôležité

Novovytvorená doména obsahuje štyroch vygenerovaných poskytovateľov kľúčov — rsa-generated, rsa-enc-generated, hmac-generated a aes-generated — všetci s prioritou 100. Komponent NetHSM musí mať vyššiu prioritu, inak Keycloak pokračuje v podpisovaní pomocou vygenerovaného softvérového kľúča a konfigurácia sa javí ako funkčná.

Hodnota 200 pre NetHSM je primeraným predvoleným nastavením.

Vyberte algoritmus pre danú oblasť

V nastaveniach sféry ( ) v časti Nastavenia sféry → Tokeny → Predvolený algoritmus podpisu ( ) nastavte algoritmus nakonfigurovaný v komponente. Ak sféra požaduje algoritmus, ktorý komponent nezverejňuje, Keycloak prejde na generovaný kľúč bez hlásenia chyby.

Overiť

List the published keys:

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

Hodnoty v súbore „ ` “ kid` by mali byť identifikátory kľúčov NetHSM.

Rozhodujúcou kontrolou je vydaný token. Vyžiadajte si ho 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 + "==")))'

Ak je kid identifikátorom kľúča NetHSM, podpis bol vygenerovaný vnútri HSM. Môžete zároveň sledovať protokol NetHSM, v ktorom by sa malo zobraziť príslušné volanie.

Plán pre prípad, že služba NetHSM nebude dostupná

Ak nie je možné nadviazať spojenie s NetHSM a v cache nie sú uložené žiadne metadáta kľúčov, doména nemá k dispozícii žiadne použiteľné kľúče a vydanie tokenu zlyhá, namiesto toho, aby sa systém prešiel na generovaný softvérový kľúč.

Varovanie

Ak je predvolený algoritmus podpisu v danej sfére zabezpečovaný kľúčmi NetHSM a NetHSM sa stane nedostupným, nie je možné vydávať ani administratívne tokeny pre túto sféru. Administrátorské rozhranie API potom nie je k dispozícii na vyriešenie tohto problému.

Obnovenie sa vykonáva prostredníctvom konfigurácie servera, nie cez administrátorskú konzolu: nastavte spi-keys--nethsm--on-unavailable=degrade a reštartujte, alebo deaktivujte túto zložku.

Z tohto dôvodu najskôr nakonfigurujte testovaciu doménu a nechajte doménu master s kľúčmi vygenerovanými samotným Keycloakom, aby bola konzola správcu naďalej dostupná.

Further Details

You find further details here.