Keycloak¶

Norint naudoti „ “ „Keycloak“ kartu su „NetHSM“, kad privatūs raktai būtų saugiai saugomi „NetHSM“, o „Keycloak“ galėtų pasirašyti prieigos žetonus ir iššifruoti JWE, reikia įdiegti ir sukonfigūruoti šį raktų teikėją taip, kaip nurodyta toliau:

Informacija apie dirbtinį intelektą¶

Šis paslaugų teikėjas buvo sukurtas ir įvertintas pasitelkiant didelę dirbtinio intelekto pagalbą.

Prepare the NetHSM¶

Paruoškite „NetHSM“ taip, kaip nurodyta toliau. Išsamias instrukcijas rasite skyriuje „ “ administravimas.

Jei „NetHSM“ naudoja savarankiškai pasirašytą sertifikatą, užrašykite jo pirštų atspaudą:

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

Sukurkite „Operator“ vartotoją, skirtą „Keycloak“ sistemai.

„Keycloak“ plėtinys aptinka raktus, tačiau jų nesukuria. Norimus raktus sukurkite rankiniu būdu:

Raktų ID turi prasidėti nuo priešdėlio, kurį pasisavins sritis. Pasirinkite tinkamą pavadinimo schemą, pavyzdžiui, kc-<realm>-<purpose>-<year> (pavyzdžiui, kc-staff-sig-rs256-2026, kc-partners-sig-es256-2026, kc-customers-enc-oaep-2026). Šis ID tampa kid, kurį skelbia „Keycloak“. Ateityje raktų keitimas atliekamas pridedant naujus ID, todėl rekomenduojame raktų ID sudėtyje naudoti metus.

Mechanizmai nustato, kokiems JOSE algoritmams raktas gali būti naudojamas:

NetHSM key type and mechanism	JOSE algorithms served
`RSA` + `RSA_Signature_PKCS1`	RS256, RS384, RS512 — nepriklauso nuo naudojamo maišos algoritmo, taigi vienas raktas tinka visiems trims
`RSA` + `RSA_Signature_PSS_SHA256` / `_SHA384` / `_SHA512`	PS256 / PS384 / PS512 — tik algoritmas, kurį nurodo mechanizmo pavadinimai
`EC_P256` / `EC_P384` / `EC_P521` + `ECDSA_Signature`	ES256 / ES384 / ES512 — kreivė nulemia algoritmą
`Curve25519` + `EdDSA_Signature`	EdDSA
`RSA` + `RSA_Decryption_OAEP_SHA1` / `_SHA256`	RSA-OAEP / RSA-OAEP-256, skirtas gaunamų JWE iššifravimui

Įrengimas¶

Atsisiųskite „Keycloak NetHSM“ teikėjo „ “ JAR failą, išsaugokite jį „Keycloak“ teikėjų aplanke, pvz., /opt/keycloak/providers/

Atkurti paslaugų teikėjų registrą: /opt/keycloak/bin/kc.sh build

Konfigūracija¶

Nustatymai gali būti nurodyti faile „ ` “ conf/keycloak.conf` arba kaip aplinkos kintamieji. Abiem atvejais nustatymai yra vienodi; aplinkos kintamieji turi pirmenybę, todėl nekonfidencialios reikšmės gali būti saugomos faile, o slaptažodis įterpiamas tik vykdymo metu.

Naudojant „ ` “ 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¶

Tai yra pageidaujamas variantas diegiant konteineriuose, nes slaptažodį galima gauti iš „Docker“ arba „Kubernetes“ paslapties, o ne įrašyti į failą.

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

Pastaba

Aplinkos kintamojo pavadinimas automatiškai sudaromas iš konfigūracijos rakto: prieš jį pridedamas priešdėlis KC_, pavadinimas paverčiamas didžiosiomis raidėmis, o kiekvienas - pakeičiamas į _. Dvigubi apatiniai brūkšneliai kyla iš rakto struktūros, spi-<spi-name>--<provider-id>--<option>, kurią šiam plėtiniui sudaro SPI keys, teikėjas nethsm ir parinkties pavadinimas.

Restart Keycloak¶

Ryšio profilis nuskaitomas tik tada, kai inicijuojama paslaugų teikėjų gamykla. Paleiskite „Keycloak“ iš naujo.

Confirm the server configuration¶

Prieš konfigūruodami bet kurią sritį, patikrinkite paleidimo žurnalą. Tai padės atskirti ryšio ar prisijungimo duomenų problemą nuo srities konfigūracijos problemos.

Sėkmės atveju:

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

Otherwise:

Log message	Cause
Nėra pranešimo arba rodomas derinimo pranešimas, kad paslaugos teikėjas neveikia	`url` is not set
`NetHSM is not reachable or not Operational at startup`	Neteisingas adresas, užblokuotas ugniasienės, sertifikato PIN kodas nesutampa arba „NetHSM“ yra užrakintas arba nekonfigūruotas
`NetHSM rejected the configured credential with HTTP 401`	Wrong username or passphrase

Pridėti paslaugų teikėją prie srities¶

Administravimo konsolėje eikite į „ “ > „Realm Settings“ → „Keys“ → „Providers“, pasirinkite „ “, spustelėkite „Add provider“ ir pasirinkite „ ` “ nethsm`.

Field	Reikšmė
Key use	`sig` – žetonų pasirašymui, `enc` – gaunamų JWE iššifravimui
Key ID prefix	Kiekvienas „NetHSM“ raktas, kurio ID prasideda šia eilute, yra paskelbtas šioje sferoje
Algorithm	Algoritmas, pagal kurį šie raktų poros yra skelbiamos
Priority	Žr. „ . Nustatykite prioritetą didesnį nei 100
Enabled / Active	Abu turi būti įjungti, kad raktas galėtų pasirašyti

Vienas komponentas naudoja vieną algoritmą, atkartodamas „Keycloak“ įdiegtus raktų teikėjus. Todėl sričiai, kuriai reikalingi tiek RS256, tiek ES256, reikalingi du komponentai. Raktai su priešdėliu, kurie neatitinka pasirinktos algoritmo, yra praleidžiami, todėl priešdėlis gali saugiai atitikti mišrų raktų rinkinį.

Atsargiai

Nenukreipkite dviejų komponentų į tą patį raktą, naudodami skirtingus algoritmus. Abu komponentai paskelbtų JWKS įrašą pagal tą patį kid.

Nustatykite prioritetą didesnį nei 100¶

Svarbu

Naujai sukurtoje sferoje yra keturi sugeneruoti raktų teikėjai — rsa-generated, rsa-enc-generated, hmac-generated ir aes-generated — visi su prioritetu 100. „NetHSM“ komponentas turi turėti aukštesnį prioritetą, kitaip „Keycloak“ toliau pasirašys sugeneruotu programiniu raktu, o konfigūracija atrodys veikianti.

NetHSM parametrui „ ` “ reikšmė „200` “ yra priimtinas numatytasis nustatymas.

Pasirinkite srities algoritmą¶

Nustatykite „ “ srities parametrus → „Tokens“ → „Default Signature Algorithm“ taip, kad atitiktų komponente sukonfigūruotą algoritmą. Jei sritis prašo algoritmo, kurio komponentas neskelbia, „Keycloak“ naudoja generuotą raktą, nepranešdamas apie klaidą.

Patikrinti¶

List the published keys:

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

„ ` “ kid` reikšmės turėtų būti „NetHSM“ raktų identifikatoriai.

Galutinis patikrinimas – tai išduotas žetonas. Paprašykite jo ir iššifruokite jo antraš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 + "==")))'

Jei kid yra „NetHSM“ rakto identifikatorius, parašas buvo sukurtas HSM viduje. Taip pat galite lygiagrečiai stebėti „NetHSM“ žurnalą, kuriame turėtų būti rodomas atitinkamas iškvietimas.

Planas, jei „NetHSM“ neveiks¶

Jei nepavyksta prisijungti prie „NetHSM“ ir raktų metaduomenų nėra išsaugota talpykloje, sritis neturi tinkamų naudoti raktų, todėl žetonų išdavimas nepavyksta, o ne pereina prie generuoto programinio rakto.

Įspėjimas

Jei srities numatytasis parašo algoritmas yra aptarnaujamas naudojant „NetHSM“ raktus, o „NetHSM“ tampa nepasiekiamas, taip pat negalima išduoti tos srities administratorių žetonų. Tokiu atveju administravimo API tampa neprieinamas, todėl problemos išspręsti neįmanoma.

Atkūrimas atliekamas per serverio konfigūraciją, o ne per administratoriaus konsolę: nustatykite „ ` “ į „spi-keys–nethsm–on-unavailable=degrade` “ ir paleiskite iš naujo arba išjunkite komponentą.

Dėl šios priežasties pirmiausia sukonfigūruokite bandomąją sritį, o sritį „ ` “ master` palikite su pačios „Keycloak“ sugeneruotais raktas, kad administratoriaus konsolė liktų pasiekiama.

Further Details¶

You find further details here.