Keycloak

Um Keycloak mit NetHSM zu verwenden, um private Schlüssel sicher in NetHSM zu speichern und gleichzeitig Keycloak die Signierung von Zugriffstoken und die Entschlüsselung von JWE zu ermöglichen, müssen Sie diesen Schlüsselanbieter wie folgt installieren und konfigurieren:

Offenlegung von KI-Informationen

Dieser Anbieter wurde unter umfangreicher Unterstützung durch künstliche Intelligenz entwickelt und geprüft.

Prepare the NetHSM

Bereiten Sie das NetHSM wie folgt vor. Ausführliche Anweisungen finden Sie im Abschnitt „ -Verwaltung“.

• Falls NetHSM ein selbstsigniertes Zertifikat verwendet, notieren Sie dessen Fingerabdruck:

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

• Erstellen Sie eine „Operator“-Benutzer <../administration.html#user-management>, die ausschließlich für Keycloak vorgesehen ist.

• Die Keycloak-Erweiterung erkennt Schlüssel, erstellt diese jedoch nicht. Erstellen Sie die gewünschten Schlüssel manuell:

  • Die Schlüssel-ID muss mit dem Präfix beginnen, das der Realm beanspruchen wird. Wählen Sie ein geeignetes Namensschema, wie beispielsweise kc-<realm>-<purpose>-<year> (zum Beispiel kc-staff-sig-rs256-2026, kc-partners-sig-es256-2026, kc-customers-enc-oaep-2026). Die ID wird zur kid, die Keycloak veröffentlicht. Die zukünftige Schlüsselrotation erfolgt durch Hinzufügen neuer IDs, weshalb wir empfehlen, das Jahr als Teil der Schlüssel-ID zu verwenden.

  • Die Mechanismen unter legen fest, für welche JOSE-Algorithmen der Schlüssel verwendet werden kann:

    NetHSM key type and mechanism	JOSE algorithms served
    RSA + RSA_Signature_PKCS1	RS256, RS384, RS512 – hash-unabhängig, sodass ein einziger Schlüssel für alle drei ausreicht
    RSA + RSA_Signature_PSS_SHA256 / _SHA384 / _SHA512	PS256 / PS384 / PS512 – nur der Algorithmus, den die Bezeichnungen andeuten
    EC_P256 / EC_P384 / EC_P521 + ECDSA_Signature	ES256 / ES384 / ES512 – die Kurve bestimmt den Algorithmus
    Curve25519 + EdDSA_Signature	EdDSA
    RSA + RSA_Decryption_OAEP_SHA1 / _SHA256	RSA-OAEP / RSA-OAEP-256, zum Entschlüsseln eingehender JWE

Installation

Laden Sie die JAR-Datei des Keycloak-NetHSM-Providers herunter, und speichern Sie sie im Provider-Ordner von Keycloak, z. B. /opt/keycloak/providers/

Provider-Registrierung neu erstellen: /opt/keycloak/bin/kc.sh build

Konfiguration

Einstellungen können entweder in der Datei „ ` “ unter „conf/keycloak.conf` “ oder als Umgebungsvariablen angegeben werden. Beide Formen entsprechen denselben Einstellungen; Umgebungsvariablen haben Vorrang, sodass nicht vertrauliche Werte in der Datei verbleiben können, während die Passphrase erst zur Laufzeit eingefügt wird.

Verwendung von 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

Wird bei Container-Bereitstellungen bevorzugt, da die Passphrase aus einem Docker- oder Kubernetes-Secret bereitgestellt werden kann, anstatt in eine Datei geschrieben zu werden.

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

Bemerkung

Der Name der Umgebungsvariablen wird automatisch aus dem Konfigurationsschlüssel abgeleitet: Dem Schlüssel wird das Präfix „ ` “ KC_` vorangestellt, er wird in Großbuchstaben umgewandelt und jedes „ ` “ -` wird durch „ ` “ _` ersetzt. Die doppelten Unterstriche ergeben sich aus der Struktur des Schlüssels, „ ` “ spi-<spi-name>–<provider-id>–<option>`, der für diese Erweiterung aus „SPI“ keys, „Provider“ nethsm und dem Optionsnamen besteht.

See also all available configuration options.

Restart Keycloak

Das Verbindungsprofil wird nur bei der Initialisierung der Provider-Factory gelesen. Starten Sie Keycloak neu.

Confirm the server configuration

Überprüfen Sie das Startprotokoll, bevor Sie einen Realm konfigurieren. So können Sie ein Problem mit der Verbindung oder den Anmeldedaten von einem Problem mit der Realm-Konfiguration unterscheiden.

Bei Erfolg:

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

Otherwise:

Log message	Cause
Keine Meldung oder eine Debug-Zeile, aus der hervorgeht, dass der Anbieter inaktiv ist	url is not set
NetHSM is not reachable or not Operational at startup	Falsche Adresse, durch eine Firewall blockiert, PIN-Diskrepanz beim Zertifikat oder das NetHSM ist gesperrt oder nicht provisioniert
NetHSM rejected the configured credential with HTTP 401	Wrong username or passphrase

Den Anbieter zu einem Bereich hinzufügen

Gehen Sie in der Verwaltungskonsole zu „ “, dann zu „Realm-Einstellungen“ → „Schlüssel“ → „Anbieter“, wählen Sie „ “ aus, klicken Sie auf „Anbieter hinzufügen“ und wählen Sie „ ` “ nethsm` aus.

Field	Bedeutung
Key use	sig zum Signieren von Tokens, enc zum Entschlüsseln eingehender JWEs
Key ID prefix	Jeder NetHSM-Schlüssel, dessen ID mit dieser Zeichenfolge beginnt, wird von diesem Realm veröffentlicht.
Algorithm	Der Algorithmus, unter dem diese Schlüssel veröffentlicht werden
Priority	Siehe . Stellen Sie die Priorität auf einen Wert über 100 ein
Enabled / Active	Beide müssen aktiviert sein, damit ein Schlüssel signiert werden kann

Eine Komponente veröffentlicht einen Algorithmus und entspricht damit den in Keycloak integrierten Schlüsselanbietern. Ein Realm, der sowohl RS256 als auch ES256 benötigt, verfügt daher über zwei Komponenten. Schlüssel unter dem Präfix, die den gewählten Algorithmus nicht unterstützen, werden übersprungen, sodass ein Präfix problemlos einer gemischten Gruppe von Schlüsseln zugeordnet werden kann.

Vorsicht

Richten Sie nicht zwei Komponenten mit unterschiedlichen Algorithmen auf denselben Schlüssel aus. Beide würden einen JWKS-Eintrag unter derselben kid veröffentlichen.

Stellen Sie die Priorität auf einen Wert über 100 ein

Wichtig

Ein neu erstelltes Realm enthält vier generierte Schlüsselanbieter – rsa-generated, rsa-enc-generated, hmac-generated und aes-generated – alle mit der Priorität 100. Die NetHSM-Komponente muss eine höhere Priorität haben, andernfalls signiert Keycloak weiterhin mit einem generierten Software-Schlüssel, und die Konfiguration scheint zu funktionieren.

Ein Wert von 200 für NetHSM ist eine sinnvolle Standardeinstellung.

Wählen Sie den Algorithmus für den Bereich aus

Legen Sie unter „ “ unter „Realm-Einstellungen“ → „Token“ → „Standard-Signaturalgorithmus“ auf den in der Komponente konfigurierten Algorithmus fest. Wenn der Realm einen Algorithmus anfordert, den die Komponente nicht veröffentlicht, greift Keycloak auf einen generierten Schlüssel zurück, ohne einen Fehler zu melden.

Überprüfen

List the published keys:

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

Die Werte „ ` “ und „kid` “ sollten die NetHSM-Schlüssel-IDs sein.

Der endgültige Nachweis ist ein ausgestelltes Token. Fordern Sie eines an und entschlüsseln Sie dessen Header:

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

Wenn kid die NetHSM-Schlüssel-ID ist, wurde die Signatur im HSM erstellt. Sie können parallel dazu auch das Protokoll von NetHSM einsehen, in dem ein entsprechender Aufruf angezeigt werden sollte.

Maßnahmen für den Fall, dass NetHSM nicht verfügbar ist

Wenn NetHSM nicht erreichbar ist und keine Schlüsselmetadaten zwischengespeichert sind, verfügt der Bereich über keine verwendbaren Schlüssel, und die Token-Ausstellung schlägt fehl, anstatt auf einen generierten Software-Schlüssel zurückzugreifen.

Warnung

Wenn der Standard-Signaturalgorithmus eines Bereichs durch NetHSM-Schlüssel bereitgestellt wird und der NetHSM nicht mehr erreichbar ist, können auch keine Administrator-Token für diesen Bereich ausgestellt werden. Die Admin-API steht dann nicht zur Behebung des Problems zur Verfügung.

Die Wiederherstellung erfolgt über die Serverkonfiguration und nicht über die Verwaltungskonsole: Setzen Sie „ ` “ auf „spi-keys–nethsm–on-unavailable=degrade` “ und starten Sie den Server neu oder deaktivieren Sie die Komponente.

Konfigurieren Sie daher zunächst einen Test-Realm und belassen Sie den Realm „ master“ auf den von Keycloak selbst generierten Schlüsseln, damit die Admin-Konsole weiterhin erreichbar bleibt.

Further Details

You find further details here.