Keycloak

För att kunna använda Keycloak tillsammans med NetHSM för att på ett säkert sätt lagra privata nycklar i NetHSM och samtidigt göra det möjligt för Keycloak att signera åtkomsttoken och dekryptera JWE, måste du installera och konfigurera denna nyckelleverantör enligt följande:

Information om AI

Denna tjänst har utvecklats och granskats med omfattande hjälp av AI.

Prepare the NetHSM

Förbered NetHSM enligt följande. Se avsnittet administration för detaljerade anvisningar.

  • Om NetHSM använder ett självsignerat certifikat ska du notera dess fingeravtryck:

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

  • Skapa en operatörsanvändare som är avsedd enbart för Keycloak.

  • Keycloak-tillägget upptäcker nycklar men skapar dem inte. Skapa önskade nycklar manuellt:

    • Nyckel-ID:t måste inledas med det prefix som realm-instansen ska använda. Välj ett lämpligt namngivningsschema, till exempel kc-<realm>-<purpose>-<year> (till exempel kc-staff-sig-rs256-2026, kc-partners-sig-es256-2026, kc-customers-enc-oaep-2026). ID:t blir kid som Keycloak publicerar. Framtida nyckelrotation sker genom att lägga till nya ID:n, vilket är anledningen till att vi rekommenderar att man använder året som en del av nyckel-ID:t.

    • Mekanismerna avgör vilka JOSE-algoritmer nyckeln kan användas för:

      NetHSM key type and mechanism

      JOSE algorithms served

      RSA + RSA_Signature_PKCS1

      RS256, RS384, RS512 – oberoende av hash-algoritm, så en nyckel täcker alla tre

      RSA + RSA_Signature_PSS_SHA256 / _SHA384 / _SHA512

      PS256 / PS384 / PS512 — endast algoritmen som mekanismen benämns efter

      EC_P256 / EC_P384 / EC_P521 + ECDSA_Signature

      ES256 / ES384 / ES512 — kurvan avgör vilken algoritm som används

      Curve25519 + EdDSA_Signature

      EdDSA

      RSA + RSA_Decryption_OAEP_SHA1 / _SHA256

      RSA-OAEP / RSA-OAEP-256, för dekryptering av inkommande JWE

Installation

Ladda ner JAR-filen för Keycloak NetHSM-leverantören ` <https://github.com/Nitrokey/nethsm-keycloak/releases>` __ och spara den i Keycloaks leverantörsmapp, t.ex. /opt/keycloak/providers/

Återställ leverantörsregistret: /opt/keycloak/bin/kc.sh build

Konfiguration

Inställningarna kan anges antingen i conf/keycloak.conf eller som miljövariabler. De två formerna motsvarar samma inställningar; miljövariablerna har företräde, vilket innebär att värden som inte är hemliga kan lagras i filen, medan endast lösenfrasen läggs till vid körning.

Med hjälp av 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

Detta är att föredra vid containerbaserade installationer, eftersom lösenfrasen kan hämtas från en Docker- eller Kubernetes-hemlighet istället för att skrivas till en fil.

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

Observera

Namnet på miljövariabeln härleds automatiskt från konfigurationsnyckeln: lägg till prefixet KC_, konvertera till versaler och ersätt varje - med _. De dubbla understrecken följer av nyckelns struktur, spi-<spi-name>--<provider-id>--<option>, som för denna tilläggsfunktion består av SPI keys, leverantör nethsm och alternativnamnet.

See also all available configuration options.

Restart Keycloak

Anslutningsprofilen läses endast in när leverantörsfabriken initialiseras. Starta om Keycloak.

Confirm the server configuration

Kontrollera startloggen innan du konfigurerar någon realm. På så sätt kan du skilja mellan problem med anslutningen eller inloggningsuppgifterna och problem med realmkonfigurationen.

Vid framgång:

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

Otherwise:

Log message

Cause

Inget meddelande, eller en felsökningsrad som anger att leverantören är inaktiv

url is not set

NetHSM is not reachable or not Operational at startup

Felaktig adress, blockerad av en brandvägg, certifikat-PIN-kod stämmer inte överens, eller så är NetHSM låst eller inte konfigurerad

NetHSM rejected the configured credential with HTTP 401

Wrong username or passphrase

Lägg till leverantören i en realm

I administratörskonsolen går du till Realm-inställningar → Nycklar → Leverantörer, väljer Lägg till leverantör och väljer nethsm.

Field

Betydelse

Key use

sig för att signera token, enc för att dekryptera inkommande JWE

Key ID prefix

Varje NetHSM-nyckel vars ID inleds med denna sträng publiceras av denna realm

Algorithm

Den algoritm som dessa nycklar publiceras enligt

Priority

Se Ställ in prioriteten till ett värde över 100

Enabled / Active

Båda måste vara aktiverade för att en nyckel ska kunna signeras

En komponent publicerar en algoritm, vilket motsvarar Keycloaks inbyggda nyckelleverantörer. En realm som behöver både RS256 och ES256 har därför två komponenter. Nycklar under prefixet som inte stöder den valda algoritmen hoppas över, vilket innebär att ett prefix utan problem kan matcha en blandad uppsättning nycklar.

Varning

Rikta inte in två komponenter mot samma nyckel med olika algoritmer. Båda skulle då publicera en JWKS-post under samma kid.

Ställ in prioriteten till ett värde över 100

Viktigt

Ett nyskapat domänområde innehåller fyra genererade nyckelleverantörer — rsa-generated, rsa-enc-generated, hmac-generated och aes-generated — alla med prioriteten 100. NetHSM-komponenten måste ha en högre prioritet, annars fortsätter Keycloak att signera med en genererad programvarunyckel och konfigurationen verkar fungera.

Värdet 200 för NetHSM är ett rimligt standardvärde.

Välj algoritm för området

Ställ in ” ” under Realm-inställningar → Tokens → Standardalgoritm för signatur till den algoritm som är konfigurerad på komponenten. Om realmen begär en algoritm som komponenten inte publicerar, använder Keycloak istället en genererad nyckel utan att rapportera något fel.

Kontrollera

List the published keys:

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

Värdena för ” ` ” kid` ska vara NetHSM-nyckel-ID:n.

Det slutgiltiga verifieringsbeviset är en utfärdad token. Begär en sådan och avkoda dess rubrik:

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

Om kid är NetHSM-nyckel-ID:t, har signaturen genererats inuti HSM:en. Du kan också övervaka NetHSM:s logg parallellt, där ett motsvarande anrop bör visas.

Plan för fall där NetHSM inte är tillgängligt

Om NetHSM inte kan nås och inga nyckelmetadata finns i cachen, har domänen inga användbara nycklar och utfärdandet av token misslyckas, istället för att systemet faller tillbaka på en genererad programvarunyckel.

Varning

Om en realms standardalgoritm för signering hanteras av NetHSM-nycklar och NetHSM inte längre går att nå, kan inte heller administrativa token för den realmen utfärdas. Admin-API:et är då inte tillgängligt för att åtgärda problemet.

Återställningen sker via serverkonfigurationen istället för via administratörskonsolen: ställ in spi-keys--nethsm--on-unavailable=degrade och starta om, eller inaktivera komponenten.

Av denna anledning bör du först konfigurera en testrealm och låta realmen master använda de nycklar som Keycloak själv genererat, så att administratörskonsolen förblir tillgänglig.

Further Details

You find further details here.