Keycloak¶
Per poter utilizzare Keycloak con NetHSM al fine di archiviare in modo sicuro le chiavi private in NetHSM, consentendo al contempo a Keycloak di firmare i token di accesso e decrittografare i JWE, è necessario installare e configurare questo provider di chiavi come segue:
Informativa sull’intelligenza artificiale¶
Questo contenuto è stato sviluppato e revisionato con un contributo significativo da parte dell’intelligenza artificiale.
Prepare the NetHSM¶
Preparare NetHSM come segue. Per istruzioni dettagliate, consultare la sezione administration.
Se NetHSM utilizza un certificato autofirmato, registrare la sua impronta digitale:
echo | openssl s_client -connect $NETHSM_HOST 2>/dev/null \ | openssl x509 -fingerprint -sha256 -noout
Crea un utente operatore dedicato a Keycloak.
L’estensione Keycloak rileva le chiavi ma non le crea. Crea manualmente le chiavi desiderate:
L’ID della chiave deve iniziare con il prefisso che il realm rivendicherà. Scegli uno schema di denominazione appropriato, come ad esempio
kc-<realm>-<purpose>-<year>(ad esempiokc-staff-sig-rs256-2026,kc-partners-sig-es256-2026,kc-customers-enc-oaep-2026). L’ID diventa l”kidpubblicato da Keycloak. La futura rotazione delle chiavi viene eseguita aggiungendo nuovi ID; per questo motivo consigliamo di includere l’anno nell’ID della chiave.I meccanismi determinano a quali algoritmi JOSE la chiave può essere associata:
NetHSM key type and mechanism
JOSE algorithms served
RSA+RSA_Signature_PKCS1RS256, RS384, RS512 — indipendenti dall’algoritmo di hash, quindi un’unica chiave copre tutti e tre
RSA+RSA_Signature_PSS_SHA256/_SHA384/_SHA512PS256 / PS384 / PS512 — solo l’algoritmo, i nomi dei meccanismi
EC_P256/EC_P384/EC_P521+ECDSA_SignatureES256 / ES384 / ES512 — la curva determina l’algoritmo
Curve25519+EdDSA_SignatureEdDSA
RSA+RSA_Decryption_OAEP_SHA1/_SHA256RSA-OAEP / RSA-OAEP-256, per la decrittografia dei JWE in entrata
Installazione¶
Scarica il file JAR del provider Keycloak NetHSM ` <https://github.com/Nitrokey/nethsm-keycloak/releases>` __, salvalo nella cartella dei provider di Keycloak, ad esempio /opt/keycloak/providers/
Ricostruire il registro dei provider: /opt/keycloak/bin/kc.sh build
Configurazione¶
Le impostazioni possono essere specificate nel file ` `` conf/keycloak.conf` oppure come variabili d’ambiente. Le due forme corrispondono alle stesse impostazioni; le variabili d’ambiente hanno la precedenza, quindi i valori non riservati possono essere contenuti nel file, mentre la passphrase viene inserita solo in fase di esecuzione.
Utilizzando 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¶
Preferibile nelle implementazioni su container, poiché la passphrase può essere fornita tramite un secret di Docker o Kubernetes anziché essere scritta su un file.
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...
Nota
Il nome della variabile d’ambiente viene ricavato automaticamente dalla chiave di configurazione: si antepone il prefisso KC_, si converte in maiuscolo e si sostituisce ogni - con _. I due trattini bassi consecutivi derivano dalla struttura della chiave, spi-<spi-name>--<provider-id>--<option>, che per questa estensione è SPI keys, provider nethsm e il nome dell’opzione.
See also all available configuration options.
Restart Keycloak¶
Il profilo di connessione viene letto solo al momento dell’inizializzazione della factory del provider. Riavvia Keycloak.
Confirm the server configuration¶
Controlla il log di avvio prima di configurare qualsiasi realm. In questo modo è possibile distinguere un problema di connessione o di credenziali da un problema di configurazione del realm.
In caso di esito positivo:
NetHSM key provider ready: 1 instance(s), user 'keycloak',
discovery cache PT5M, on-unavailable fail
Otherwise:
Log message |
Cause |
|---|---|
Nessun messaggio oppure una riga di debug che indica che il provider è inattivo |
|
|
Indirizzo errato, blocco da parte di un firewall, mancata corrispondenza del PIN del certificato oppure il NetHSM è bloccato o non configurato |
|
Wrong username or passphrase |
Aggiungi il provider a un realm¶
Nella console di amministrazione, vai su Impostazioni del realm → Chiavi → Provider, scegli Aggiungi provider e seleziona nethsm.
Field |
Significato |
|---|---|
Key use |
|
Key ID prefix |
Ogni chiave NetHSM il cui ID inizia con questa stringa viene pubblicata da questo realm |
Algorithm |
L’algoritmo in base al quale vengono pubblicate queste chiavi |
Priority |
|
Enabled / Active |
Entrambe devono essere attive affinché una chiave possa firmare |
Un componente gestisce un algoritmo, rispecchiando i provider di chiavi integrati in Keycloak. Un realm che richiede sia RS256 che ES256 dispone quindi di due componenti. Le chiavi con un prefisso che non supportano l’algoritmo scelto vengono ignorate, pertanto un prefisso può tranquillamente corrispondere a un insieme misto di chiavi.
Attenzione
Non associare due componenti alla stessa chiave utilizzando algoritmi diversi. Entrambe pubblicherebbero una voce JWKS sotto lo stesso kid.
Imposta la priorità su un valore superiore a 100¶
Importante
Un regno appena creato contiene quattro provider di chiavi generati — rsa-generated, rsa-enc-generated, hmac-generated e aes-generated — tutti con priorità 100. Il componente NetHSM deve avere una priorità più alta, altrimenti Keycloak continua a firmare con una chiave software generata e la configurazione sembra funzionare.
Un valore pari a 200 per NetHSM è un’impostazione predefinita ragionevole.
Selezionare l’algoritmo per il regno¶
Impostare Realm Settings → Tokens → Default Signature Algorithm sull’algoritmo configurato sul componente. Se il realm richiede un algoritmo che il componente non pubblica, Keycloak ricorre a una chiave generata senza segnalare alcun errore.
Verifica¶
List the published keys:
curl -s https://<keycloak-host>/realms/<realm>/protocol/openid-connect/certs
I valori di ` `` e kid` devono corrispondere agli ID delle chiavi NetHSM.
La verifica definitiva consiste in un token emesso. Richiedine uno e decodifica la sua intestazione:
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 + "==")))'
Se kid è l’ID della chiave NetHSM, la firma è stata generata all’interno dell’HSM. È inoltre possibile monitorare contemporaneamente il log di NetHSM, che dovrebbe riportare una chiamata corrispondente.
Further Details¶
You find further details here.