Keycloak

For at kunne bruge Keycloak sammen med NetHSM til sikkert at gemme private nøgler i NetHSM og samtidig give Keycloak mulighed for at underskrive adgangstokener og dekryptere JWE, skal du installere og konfigurere denne nøgleudbyder på følgende måde:

Oplysninger om kunstig intelligens

Denne udbyder er udviklet og gennemgået med betydelig hjælp fra kunstig intelligens.

Prepare the NetHSM

Forbered NetHSM på følgende måde. Se afsnittet administration for detaljerede instruktioner.

  • Hvis NetHSM bruger et selvunderskrevet certifikat, skal du notere dets fingeraftryk:

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

  • Opret en operatørbruger, der er dedikeret til Keycloak.

  • Keycloak-udvidelsen finder nøgler, men opretter dem ikke. Opret de ønskede nøgler manuelt:

    • Nøgle-ID’et skal begynde med det præfiks, som realm’et vil anvende. Vælg et passende navneskema, f.eks. kc-<realm>-<purpose>-<year> (f.eks. kc-staff-sig-rs256-2026, kc-partners-sig-es256-2026, kc-customers-enc-oaep-2026). ID’et bliver til kid, som Keycloak offentliggør. Fremtidig nøglerotation udføres ved at tilføje nye ID’er, og derfor anbefaler vi at bruge året som en del af nøgle-ID’et.

    • Mekanismerne bestemmer, hvilke JOSE-algoritmer nøglen kan anvendes til:

      NetHSM key type and mechanism

      JOSE algorithms served

      RSA + RSA_Signature_PKCS1

      RS256, RS384, RS512 — uafhængig af hash-algoritme, så én nøgle dækker alle tre

      RSA + RSA_Signature_PSS_SHA256 / _SHA384 / _SHA512

      PS256 / PS384 / PS512 — kun algoritmen, som mekanismen er opkaldt efter

      EC_P256 / EC_P384 / EC_P521 + ECDSA_Signature

      ES256 / ES384 / ES512 — kurven bestemmer algoritmen

      Curve25519 + EdDSA_Signature

      EdDSA

      RSA + RSA_Decryption_OAEP_SHA1 / _SHA256

      RSA-OAEP / RSA-OAEP-256, til dekryptering af indgående JWE

Installation

Download JAR-filen til Keycloak NetHSM-udbyderen ` <https://github.com/Nitrokey/nethsm-keycloak/releases>` __, og gem den i Keycloaks udbydermappe, f.eks. /opt/keycloak/providers/

Genopbyg udbyderregistret: /opt/keycloak/bin/kc.sh build

Konfiguration

Indstillingerne kan angives enten i conf/keycloak.conf eller som miljøvariabler. De to former svarer til hinanden; miljøvariabler har forrang, så værdier, der ikke er fortrolige, kan gemmes i filen, mens adgangskoden først indsættes ved kørsel.

Brug af 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

Foretrækkes ved container-implementeringer, da adgangskoden kan hentes fra en Docker- eller Kubernetes-secret i stedet for at blive skrevet til 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...

Bemærk

Navnet på miljøvariablen udledes automatisk fra konfigurationsnøglen: Der sættes præfikset KC_ foran, det konverteres til store bogstaver, og alle forekomster af - erstattes med _. De dobbelte understregninger følger af nøglens struktur, spi-<spi-name>--<provider-id>--<option>, som for denne udvidelse består af SPI keys, udbyder nethsm og navnet på indstillingen.

See also all available configuration options.

Restart Keycloak

Forbindelsesprofilen læses kun, når udbyderfabrikken initialiseres. Genstart Keycloak.

Confirm the server configuration

Tjek opstartsloggen, inden du konfigurerer et realm. På den måde kan du skelne mellem et problem med forbindelsen eller brugeroplysningerne og et problem med realm-konfigurationen.

Ved succes:

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

Otherwise:

Log message

Cause

Ingen besked eller en fejlfindingslinje, der angiver, at udbyderen er inaktiv

url is not set

NetHSM is not reachable or not Operational at startup

Forkert adresse, blokeret af en firewall, uoverensstemmelse i certifikat-PIN, eller NetHSM er låst eller ikke klargjort

NetHSM rejected the configured credential with HTTP 401

Wrong username or passphrase

Føj udbyderen til et realm

I administratorkonsollen skal du gå til Realm-indstillinger → Nøgler → Udbydere, vælge Tilføj udbyder og vælge nethsm.

Field

Betydning

Key use

sig til at underskrive tokens, enc til at dekryptere indgående JWE’er

Key ID prefix

Hver NetHSM-nøgle, hvis ID begynder med denne streng, offentliggøres af dette realm

Algorithm

Den algoritme, som disse nøgler er offentliggjort under

Priority

Se Indstil prioriteten til over 100

Enabled / Active

Begge skal være aktiveret, for at en nøgle kan fungere

En komponent implementerer én algoritme, hvilket afspejler Keycloaks indbyggede nøgleudbydere. Et realm, der har brug for både RS256 og ES256, har derfor to komponenter. Nøgler under præfikset, der ikke understøtter den valgte algoritme, springes over, så et præfiks kan uden problemer matche en blandet samling af nøgler.

Forsigtig

Du må ikke pege to komponenter mod den samme nøgle med forskellige algoritmer. Begge vil i så fald offentliggøre en JWKS-post under den samme kid.

Indstil prioriteten til over 100

Vigtigt

Et nyoprettet realm indeholder fire genererede nøgleudbydere — rsa-generated, rsa-enc-generated, hmac-generated og aes-generated — alle med prioriteten 100. NetHSM-komponenten skal have en højere prioritet, ellers fortsætter Keycloak med at underskrive med en genereret softwarenøgle, og konfigurationen ser ud til at fungere.

En værdi på 200 for NetHSM er en fornuftig standardindstilling.

Vælg algoritmen for området

Indstil » « under Realm-indstillinger → Tokens → Standard signaturalgoritme » « til den algoritme, der er konfigureret på komponenten. Hvis realm’et anmoder om en algoritme, som komponenten ikke offentliggør, falder Keycloak tilbage til en genereret nøgle uden at rapportere en fejl.

Bekræft

List the published keys:

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

Værdierne i ` `` og kid` skal være NetHSM-nøgle-ID’erne.

Den endelige kontrol sker ved hjælp af et udstedt token. Anmod om et, og afkod dets 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 + "==")))'

Hvis kid er NetHSM-nøgle-ID’et, blev signaturen genereret inde i HSM’en. Du kan også følge med i NetHSM’s logfil sideløbende, hvor der burde vises et relevant opkald.

Plan for tilfælde, hvor NetHSM ikke er tilgængeligt

Hvis NetHSM ikke kan nås, og der ikke er gemt nøglemetadata i cachen, har realm’et ingen brugbare nøgler, og udstedelsen af tokens mislykkes – i stedet for at falde tilbage på en genereret softwarenøgle.

Advarsel

Hvis et realms standard-signaturalgoritme håndteres af NetHSM-nøgler, og NetHSM ikke længere kan nås, kan der heller ikke udstedes administrator-tokens til det pågældende realm. Admin-API’et er i så fald utilgængeligt til at løse problemet.

Gendannelsen foregår via serverkonfigurationen og ikke via administratorkonsollen: Indstil spi-keys--nethsm--on-unavailable=degrade og genstart, eller deaktiver komponenten.

Af denne grund bør du først konfigurere et test-realm og lade realmet master fortsat bruge de nøgler, som Keycloak selv har genereret, så adminkonsollen forbliver tilgængelig.

Further Details

You find further details here.