Keycloak

Lai izmantotu Keycloak kopā ar NetHSM, lai droši uzglabātu privātos atslēgas NetHSM, vienlaikus ļaujot Keycloak parakstīt piekļuves žetonus un atšifrēt JWE, jums ir jāinstalē un jākonfigurē šis atslēgu nodrošinātājs šādi:

Informācija par mākslīgo intelektu

Šis pakalpojuma sniedzējs tika izstrādāts un pārskatīts, izmantojot ievērojamu mākslīgā intelekta palīdzību.

Prepare the NetHSM

Sagatavojiet NetHSM šādi. Sīkākas instrukcijas skatiet sadaļā „ ” administrēšana.

  • Ja NetHSM izmanto pašparakstītu sertifikātu, reģistrējiet tā pirkstu nospiedumu:

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

  • Izveidojiet lietotāju „Operator”, kas paredzēts tieši Keycloak lietošanai.

  • Keycloak paplašinājums atrod atslēgas, taču tās neizveido. Izveidojiet vajadzīgās atslēgas manuāli:

    • Atslēgas ID jāuzsāk ar prefiksu, ko izmantos domēns. Izvēlieties atbilstošu nosaukumu veidošanas shēmu, piemēram, kc-<realm>-<purpose>-<year> (piemēram, kc-staff-sig-rs256-2026, kc-partners-sig-es256-2026, kc-customers-enc-oaep-2026). Šis ID kļūst par kid, ko publicē Keycloak. Turpmākā atslēgu rotācija tiek veikta, pievienojot jaunus ID, tāpēc iesakām atslēgas ID sastāvā iekļaut gadu.

    • Mehānismi nosaka, kuriem JOSE algoritmiem šī atslēga var tikt izmantota:

      NetHSM key type and mechanism

      JOSE algorithms served

      RSA + RSA_Signature_PKCS1

      RS256, RS384, RS512 — neatkarīgi no izmantojamā hash algoritma, tādējādi viena atslēga der visiem trim

      RSA + RSA_Signature_PSS_SHA256 / _SHA384 / _SHA512

      PS256 / PS384 / PS512 — tikai algoritms, no kura cēlies mehānisma nosaukums

      EC_P256 / EC_P384 / EC_P521 + ECDSA_Signature

      ES256 / ES384 / ES512 — līkne nosaka algoritmu

      Curve25519 + EdDSA_Signature

      EdDSA

      RSA + RSA_Decryption_OAEP_SHA1 / _SHA256

      RSA-OAEP / RSA-OAEP-256, ienākošo JWE atšifrēšanai

Uzstādīšana

Lejupielādējiet Keycloak NetHSM pakalpojuma sniedzēja „ ” JAR failu, saglabājiet to Keycloak pakalpojuma sniedzēju mapē, piemēram, /opt/keycloak/providers/

Atjaunojiet pakalpojumu sniedzēju reģistru: /opt/keycloak/bin/kc.sh build

Konfigurācija

Iestatījumus var norādīt vai nu failā „ ` “ conf/keycloak.conf`, vai kā vides mainīgos. Abas formas atbilst vieniem un tiem pašiem iestatījumiem; vides mainīgie ir prioritāri, tādēļ failā var glabāt atklātas vērtības, bet paroli ievadīt tikai izpildes laikā.

Izmantojot 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 parasti izmanto konteineru ieviešanā, jo paroli var norādīt, izmantojot Docker vai Kubernetes slepeno informāciju, nevis ierakstot to 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...

Piezīme

Vides mainīgā nosaukums tiek iegūts mehāniski no konfigurācijas atslēgas: tai priekšā tiek pievienots KC_, nosaukums tiek pārvērsts lielajos burtiem, un katrs - tiek aizstāts ar _. Dubultie apakšsvītriņi izriet no atslēgas struktūras, spi-<spi-name>--<provider-id>--<option>, kur šim paplašinājumam ir SPI keys, pakalpojuma sniedzējs nethsm un opcijas nosaukums.

See also all available configuration options.

Restart Keycloak

Savienojuma profils tiek nolasīts tikai tad, kad tiek inicializēta pakalpojumu sniedzēju fabrika. Pārstartējiet Keycloak.

Confirm the server configuration

Pirms jebkuras sfēras konfigurēšanas pārbaudiet palaišanas žurnālu. Tas ļauj nošķirt savienojuma vai autentifikācijas datu problēmu no sfēras konfigurācijas problēmas.

Par panākumiem:

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

Otherwise:

Log message

Cause

Nav ziņojuma vai arī parādās atkļūdošanas rinda, kas norāda, ka pakalpojuma sniedzējs ir neaktīvs

url is not set

NetHSM is not reachable or not Operational at startup

Nepareiza adrese, bloķēts ar ugunsmūri, sertifikāta PIN koda neatbilstība vai NetHSM ir bloķēts vai nav konfigurēts

NetHSM rejected the configured credential with HTTP 401

Wrong username or passphrase

Pievienot pakalpojuma sniedzēju sfērai

Administratora konsolē atveriet Realm Settings → Keys → Providers, izvēlieties „ “ (Pievienot pakalpojumu sniedzēju) un atlasiet nethsm.

Field

Nozīme

Key use

sig, lai parakstītu žetonus, enc, lai atšifrētu ienākošos JWE

Key ID prefix

Katra NetHSM atslēga, kuras ID sākas ar šo virkni, tiek publicēta šajā sfērā

Algorithm

Algoritms, saskaņā ar kuru šīs atslēgas tiek publicētas

Priority

Skatīt . Iestatiet prioritāti virs 100

Enabled / Active

Lai atslēga varētu parakstīties, abiem jābūt ieslēgtiem

Viena komponente publicē vienu algoritmu, atspoguļojot Keycloak iebūvētos atslēgu nodrošinātājus. Tādējādi sfērai, kurai nepieciešami gan RS256, gan ES256, ir divas komponentes. Atslēgas ar prefiksu, kas neatbalsta izvēlēto algoritmu, tiek izlaistas, tādējādi prefikss var droši atbilst jauktam atslēgu kopumam.

Uzmanies

Nevirziet divus komponentus uz vienu un to pašu atslēgu, izmantojot atšķirīgus algoritmus. Abas sistēmas publicētu JWKS ierakstu zem tā paša kid.

Iestatiet prioritāti virs 100

Svarīgi

rsa-generated rsa-enc-generated hmac-generated aes-generated 100 . NetHSM komponentam ir jābūt ar augstāku prioritāti, pretējā gadījumā Keycloak turpina parakstīšanos ar ģenerētu programmatūras atslēgu, un konfigurācija šķietami darbojas.

NetHSM parametram „ ` ” 200` ir piemērota noklusējuma vērtība.

Izvēlieties algoritmu sfērai

ā iestatiet „Realm Settings“ → „Tokens“ → „Default Signature Algorithm“ uz algoritmu, kas konfigurēts komponentā. Ja realms pieprasa algoritmu, kuru komponents nepublicē, Keycloak izmanto ģenerētu atslēgu, neziņojot par kļūdu.

Pārbaudīt

List the published keys:

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

`` un kid` vērtībām jābūt NetHSM atslēgu identifikatoriem.

Galīgā pārbaude ir izsniegtais žetons. Pieprasiet to un dekodējiet tā galvenes informāciju:

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

Ja kid ir NetHSM atslēgas ID, paraksts tika ģenerēts HSM iekšienē. Vienlaikus varat arī pārbaudīt NetHSM žurnālu, kurā būtu jāparādās atbilstošajam izsaukumam.

Rīcības plāns gadījumam, ja NetHSM nav pieejams

Ja nav iespējams izveidot savienojumu ar NetHSM un atmiņā nav saglabāti atslēgu metadati, sfērā nav izmantojamu atslēgu un žetona izsniegšana neizdodas, nevis tiek izmantota ģenerēta programmatūras atslēga.

Brīdinājums

Ja kādas sfēras noklusējuma paraksta algoritmu nodrošina NetHSM atslēgas un NetHSM kļūst nepieejams, arī šīs sfēras administratora žetoni vairs nevar tikt izsniegti. Tādā gadījumā administratora API nav pieejams, lai novērstu šo problēmu.

Atjaunošana tiek veikta, izmantojot servera konfigurāciju, nevis administratora konsoli: iestatiet spi-keys--nethsm--on-unavailable=degrade un pārstartējiet serveri vai atspējojiet komponentu.

Tāpēc vispirms konfigurējiet testa sfēru un atstājiet sfēru „ master” ar Keycloak paša ģenerētajām atslēgām, lai administratora konsole joprojām būtu pieejama.

Further Details

You find further details here.