Keycloak¶
Pour utiliser Keycloak avec NetHSM afin de stocker en toute sécurité les clés privées dans NetHSM tout en permettant à Keycloak de signer des jetons d’accès et de déchiffrer les JWE, vous devez installer et configurer ce fournisseur de clés comme suit :
Mention relative à l’IA¶
Ce service a été développé et révisé avec une aide importante de l’IA.
Prepare the NetHSM¶
Préparez le NetHSM comme suit. Reportez-vous à la section administration pour obtenir des instructions détaillées.
Si NetHSM utilise un certificat auto-signé, notez son empreinte digitale :
echo | openssl s_client -connect $NETHSM_HOST 2>/dev/null \ | openssl x509 -fingerprint -sha256 -noout
Créez un compte utilisateur de type « Opérateur » dédié à Keycloak.
L’extension Keycloak détecte les clés mais ne les crée pas. Créez manuellement les clés souhaitées :
L’identifiant de clé doit commencer par le préfixe que le domaine revendiquera. Choisissez une convention de nommage appropriée, telle que
kc-<realm>-<purpose>-<year>(par exemplekc-staff-sig-rs256-2026,kc-partners-sig-es256-2026,kc-customers-enc-oaep-2026). Cet identifiant devient l”kidpublié par Keycloak. La rotation future des clés s’effectue en ajoutant de nouveaux identifiants ; c’est pourquoi nous vous recommandons d’inclure l’année dans l’identifiant de clé.Les mécanismes déterminent les algorithmes JOSE pris en charge par la clé :
NetHSM key type and mechanism
JOSE algorithms served
RSA+RSA_Signature_PKCS1RS256, RS384, RS512 — compatible avec tous les algorithmes de hachage ; une seule clé suffit donc pour les trois
RSA+RSA_Signature_PSS_SHA256/_SHA384/_SHA512PS256 / PS384 / PS512 — seuls les noms des algorithmes et des mécanismes
EC_P256/EC_P384/EC_P521+ECDSA_SignatureES256 / ES384 / ES512 — la courbe détermine l’algorithme
Curve25519+EdDSA_SignatureEdDSA
RSA+RSA_Decryption_OAEP_SHA1/_SHA256RSA-OAEP / RSA-OAEP-256, pour le déchiffrement des JWE entrants
Installation¶
Téléchargez le fichier JAR du fournisseur NetHSM de Keycloak ` <https://github.com/Nitrokey/nethsm-keycloak/releases>` __, puis enregistrez-le dans le dossier des fournisseurs de Keycloak, par exemple /opt/keycloak/providers/
Recréer le registre des fournisseurs : /opt/keycloak/bin/kc.sh build
Configuration¶
Les paramètres peuvent être définis soit dans le fichier ` `` conf/keycloak.conf`, soit sous forme de variables d’environnement. Ces deux formes correspondent aux mêmes paramètres ; les variables d’environnement ayant la priorité, les valeurs non confidentielles peuvent être stockées dans le fichier, seule la phrase de passe étant injectée au moment de l’exécution.
À l’aide de 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¶
Préféré dans les déploiements en conteneurs, car la phrase secrète peut être fournie à partir d’un secret Docker ou Kubernetes au lieu d’être écrite dans un fichier.
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...
Note
Le nom de la variable d’environnement est dérivé automatiquement de la clé de configuration : on lui ajoute le préfixe KC_, on le met en majuscules, puis on remplace chaque - par _. Les deux traits de soulignement découlent de la structure de la clé, spi-<spi-name>--<provider-id>--<option>, qui, pour cette extension, se compose de SPI keys, du fournisseur nethsm et du nom de l’option.
See also all available configuration options.
Restart Keycloak¶
Le profil de connexion n’est lu qu’au moment de l’initialisation de la fabrique de fournisseurs. Redémarrez Keycloak.
Confirm the server configuration¶
Consultez le journal de démarrage avant de configurer un domaine. Cela permet de distinguer un problème de connexion ou d’identifiants d’un problème de configuration du domaine.
En cas de réussite :
NetHSM key provider ready: 1 instance(s), user 'keycloak',
discovery cache PT5M, on-unavailable fail
Otherwise:
Log message |
Cause |
|---|---|
Aucun message, ou une ligne de débogage indiquant que le fournisseur est inactif |
|
|
Adresse incorrecte, blocage par un pare-feu, incompatibilité de code PIN du certificat, ou le NetHSM est verrouillé ou n’a pas été provisionné |
|
Wrong username or passphrase |
Ajouter le fournisseur à un domaine¶
Dans la console d’administration, accédez à Paramètres du realm → Clés → Fournisseurs, choisissez Ajouter un fournisseur, puis sélectionnez nethsm.
Field |
Signification |
|---|---|
Key use |
|
Key ID prefix |
Chaque clé NetHSM dont l’identifiant commence par cette chaîne est publiée par ce domaine |
Algorithm |
L’algorithme sous lequel ces clés sont publiées |
Priority |
Voir . Définissez la priorité sur une valeur supérieure à 100 |
Enabled / Active |
Ces deux options doivent être activées pour qu’une clé puisse signer |
Un composant prend en charge un algorithme, à l’image des fournisseurs de clés intégrés à Keycloak. Un realm nécessitant à la fois RS256 et ES256 comporte donc deux composants. Les clés dont le préfixe ne correspond pas à l’algorithme choisi sont ignorées ; un préfixe peut ainsi correspondre en toute sécurité à un ensemble hétérogène de clés.
Prudence
Ne configurez pas deux composants sur la même clé avec des algorithmes différents. Les deux publieraient en effet une entrée JWKS sous la même adresse kid.
Définissez la priorité à une valeur supérieure à 100¶
Important
Un domaine nouvellement créé contient quatre fournisseurs de clés générés : rsa-generated, rsa-enc-generated, hmac-generated et aes-generated — tous avec la priorité 100. Le composant NetHSM doit avoir une priorité plus élevée, sinon Keycloak continue de signer avec une clé logicielle générée et la configuration semble fonctionner.
Une valeur de ` `` 200` pour NetHSM constitue une valeur par défaut raisonnable.
Sélectionnez l’algorithme pour le royaume¶
Définissez l’option « » ( ) dans Realm Settings → Tokens → Default Signature Algorithm sur l’algorithme configuré sur le composant. Si le realm demande un algorithme que le composant ne publie pas, Keycloak utilise alors une clé générée sans signaler d’erreur.
Vérifier¶
List the published keys:
curl -s https://<keycloak-host>/realms/<realm>/protocol/openid-connect/certs
Les valeurs « ` » kid` doivent correspondre aux identifiants de clé NetHSM.
La vérification définitive consiste à obtenir un jeton. Demandez-en un et décodez son en-tête :
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 + "==")))'
Si kid correspond à l’identifiant de la clé NetHSM, la signature a été générée au sein du HSM. Vous pouvez également consulter en parallèle le journal de NetHSM, qui devrait afficher un appel correspondant.
Further Details¶
You find further details here.