Keycloak

Om Keycloak met NetHSM te kunnen gebruiken om privésleutels veilig in NetHSM op te slaan en tegelijkertijd Keycloak in staat te stellen toegangstokens te ondertekenen en JWE te ontsleutelen, moet u deze sleutelprovider als volgt installeren en configureren:

Informatie over AI

Deze aanbieder is ontwikkeld en beoordeeld met aanzienlijke ondersteuning van kunstmatige intelligentie.

Prepare the NetHSM

Stel de NetHSM als volgt in. Raadpleeg paragraaf administration voor gedetailleerde instructies.

  • Als NetHSM een zelfondertekend certificaat gebruikt, noteer dan de vingerafdruk ervan:

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

  • Maak een Operator-gebruikers aan die uitsluitend voor Keycloak bestemd is.

  • De Keycloak-extensie detecteert sleutels, maar maakt deze niet aan. Maak de gewenste sleutels handmatig aan:

    • De sleutel-ID moet beginnen met het voorvoegsel dat het domein zal claimen. Kies een geschikt naamgevingsschema, zoals kc-<realm>-<purpose>-<year> (bijvoorbeeld kc-staff-sig-rs256-2026, kc-partners-sig-es256-2026, kc-customers-enc-oaep-2026). De ID wordt de kid die Keycloak publiceert. Toekomstige sleutelrotatie wordt uitgevoerd door nieuwe ID’s toe te voegen; daarom raden we aan om het jaar als onderdeel van de sleutel-ID te gebruiken.

    • De mechanismen bepalen voor welke JOSE-algoritmen de sleutel kan worden gebruikt:

      NetHSM key type and mechanism

      JOSE algorithms served

      RSA + RSA_Signature_PKCS1

      RS256, RS384, RS512 — hash-onafhankelijk, dus één sleutel is geldig voor alle drie

      RSA + RSA_Signature_PSS_SHA256 / _SHA384 / _SHA512

      PS256 / PS384 / PS512 — alleen de naam van het algoritme in de benaming van het mechanisme

      EC_P256 / EC_P384 / EC_P521 + ECDSA_Signature

      ES256 / ES384 / ES512 — de curve bepaalt het algoritme

      Curve25519 + EdDSA_Signature

      EdDSA

      RSA + RSA_Decryption_OAEP_SHA1 / _SHA256

      RSA-OAEP / RSA-OAEP-256, voor het ontsleutelen van inkomende JWE’s

Installatie

Download het JAR-bestand van de Keycloak NetHSM-provider ` <https://github.com/Nitrokey/nethsm-keycloak/releases>` __, en sla het op in de providermap van Keycloak, bijvoorbeeld /opt/keycloak/providers/

Het providerregister opnieuw opbouwen: /opt/keycloak/bin/kc.sh build

Configuratie

Instellingen kunnen worden opgegeven in het bestand ` `` of conf/keycloak.conf`, of als omgevingsvariabelen. Beide vormen vertegenwoordigen dezelfde instellingen; omgevingsvariabelen hebben voorrang, zodat niet-vertrouwelijke waarden in het bestand kunnen worden opgeslagen en alleen de wachtzin tijdens runtime wordt ingevoegd.

` gebruiken 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

Dit heeft de voorkeur bij containerimplementaties, omdat de wachtzin kan worden opgegeven via een Docker- of Kubernetes-secret in plaats van in een bestand te worden opgeslagen.

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

Notitie

De naam van de omgevingsvariabele wordt automatisch afgeleid uit de configuratiesleutel: er wordt het voorvoegsel KC_ aan toegevoegd, de tekst wordt omgezet naar hoofdletters en elke - wordt vervangen door _. De dubbele onderstrepingstekens vloeien voort uit de structuur van de sleutel, spi-<spi-name>--<provider-id>--<option>, die voor deze uitbreiding bestaat uit SPI keys, provider nethsm en de naam van de optie.

See also all available configuration options.

Restart Keycloak

Het verbindingsprofiel wordt alleen gelezen wanneer de providerfactory wordt geïnitialiseerd. Start Keycloak opnieuw op.

Confirm the server configuration

Controleer het opstartlogboek voordat je een realm configureert. Zo kun je onderscheid maken tussen een probleem met de verbinding of de inloggegevens en een probleem met de configuratie van de realm.

Als het lukt:

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

Otherwise:

Log message

Cause

Geen melding, of een foutmelding waarin staat dat de provider inactief is

url is not set

NetHSM is not reachable or not Operational at startup

Verkeerd adres, geblokkeerd door een firewall, certificaat-PIN-conflict, of de NetHSM is vergrendeld of niet geconfigureerd

NetHSM rejected the configured credential with HTTP 401

Wrong username or passphrase

Voeg de provider toe aan een realm

Ga in de beheerconsole naar Realm-instellingen → Sleutels → Aanbieders, kies , klik op ‘Aanbieder toevoegen’ en selecteer nethsm.

Field

Betekenis

Key use

sig om tokens te ondertekenen, enc om inkomende JWE’s te ontsleutelen

Key ID prefix

Elke NetHSM-sleutel waarvan het ID met deze tekenreeks begint, wordt door dit domein gepubliceerd

Algorithm

Het algoritme waaronder deze sleutels worden gepubliceerd

Priority

Zie Stel de prioriteit in op een waarde hoger dan 100

Enabled / Active

Beide moeten ingeschakeld zijn voor een sleutel die moet ondertekenen

Eén component implementeert één algoritme, naar het voorbeeld van de ingebouwde sleutelproviders van Keycloak. Een realm die zowel RS256 als ES256 nodig heeft, beschikt daarom over twee componenten. Sleutels onder het voorvoegsel die niet geschikt zijn voor het gekozen algoritme worden overgeslagen, zodat een voorvoegsel gerust kan overeenkomen met een gemengde verzameling sleutels.

Pas op

Richt geen twee componenten met verschillende algoritmen op dezelfde sleutel. Beide zouden dan een JWKS-vermelding publiceren onder dezelfde kid.

Stel de prioriteit in op een waarde hoger dan 100

Belangrijk

Een nieuw aangemaakt domein bevat vier gegenereerde sleutelproviders — rsa-generated, rsa-enc-generated, hmac-generated en aes-generated — allemaal met prioriteit 100. De NetHSM-component moet een hogere prioriteit hebben, anders blijft Keycloak ondertekenen met een gegenereerde softwaresleutel en lijkt de configuratie te werken.

Een waarde van 200 voor NetHSM is een redelijke standaardinstelling.

Selecteer het algoritme voor het domein

Stel in Realm-instellingen → Tokens → Standaardhandtekeningalgoritme in op het algoritme dat op de component is geconfigureerd. Als het realm een algoritme vraagt dat de component niet publiceert, valt Keycloak terug op een gegenereerde sleutel zonder een foutmelding te geven.

Controleer

List the published keys:

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

De waarden ` `` en kid` moeten de NetHSM-sleutel-ID’s zijn.

De definitieve controle vindt plaats aan de hand van een uitgegeven token. Vraag er een aan en decodeer de header ervan:

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

Als kid de NetHSM-sleutel-ID is, is de handtekening binnen de HSM gegenereerd. Je kunt ook tegelijkertijd het logboek van NetHSM in de gaten houden; daar zou een bijbehorende aanroep in moeten staan.

Plan voor het geval NetHSM niet beschikbaar is

Als NetHSM niet bereikbaar is en er geen metagegevens van sleutels in de cache zijn opgeslagen, beschikt het domein niet over bruikbare sleutels en mislukt de uitgifte van tokens, in plaats van dat er wordt teruggevallen op een gegenereerde softwaresleutel.

Waarschuwing

Als het standaardhandtekeningalgoritme van een realm wordt verzorgd door NetHSM-sleutels en de NetHSM niet meer bereikbaar is, kunnen er ook geen beheerders-tokens voor die realm worden uitgegeven. De beheer-API is dan niet beschikbaar om het probleem op te lossen.

Het herstel gebeurt via de serverconfiguratie in plaats van via de beheerconsole: stel spi-keys--nethsm--on-unavailable=degrade in en start de server opnieuw op, of schakel het onderdeel uit.

Configureer daarom eerst een testrealm en laat de realm master op de door Keycloak zelf gegenereerde sleutels staan, zodat de beheerconsole bereikbaar blijft.

Further Details

You find further details here.