Keycloak

Jotta voit käyttää Keycloakia yhdessä NetHSM:n kanssa ja tallentaa yksityisiä avaimia turvallisesti NetHSM:ään samalla, kun Keycloak voi allekirjoittaa pääsytunnuksia ja purkaa JWE-salauksen, sinun on asennettava ja määritettävä tämä avainpalveluntarjoaja seuraavasti:

Tietoa tekoälystä

Tämä palveluntarjoaja on kehitetty ja arvioitu laajasti tekoälyn avulla.

Prepare the NetHSM

Valmistele NetHSM seuraavasti. Katso yksityiskohtaiset ohjeet kohdasta administration.

• Jos NetHSM käyttää itse allekirjoitettua varmennetta, kirjaa sen sormenjälki muistiin:

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

• Luo Keycloakille oma Operator-käyttäjä.

• Keycloak-laajennus tunnistaa avaimet, mutta ei luo niitä. Luo haluamasi avaimet manuaalisesti:

  • Avain-ID:n on alettava etuliitteellä, jonka realm ottaa käyttöön. Valitse sopiva nimeämiskäytäntö, kuten kc-<realm>-<purpose>-<year> (esimerkiksi kc-staff-sig-rs256-2026, kc-partners-sig-es256-2026, kc-customers-enc-oaep-2026). Tästä ID:stä tulee kid, jonka Keycloak julkaisee. Tulevaisuudessa avainten kierrätys tapahtuu lisäämällä uusia ID:itä, minkä vuoksi suosittelemme käyttämään vuotta osana avain-ID:tä.

  • **** -mekanismit määrittävät, mitä JOSE-algoritmeja avain voi tukea:

    NetHSM key type and mechanism	JOSE algorithms served
    RSA + RSA_Signature_PKCS1	RS256, RS384, RS512 — algoritmista riippumaton, joten yksi avain kattaa kaikki kolme
    RSA + RSA_Signature_PSS_SHA256 / _SHA384 / _SHA512	PS256 / PS384 / PS512 — vain algoritmi, jota mekanismin nimet viittaavat
    EC_P256 / EC_P384 / EC_P521 + ECDSA_Signature	ES256 / ES384 / ES512 — käyrä määrää algoritmin
    Curve25519 + EdDSA_Signature	EdDSA
    RSA + RSA_Decryption_OAEP_SHA1 / _SHA256	RSA-OAEP / RSA-OAEP-256, saapuvien JWE-tiedostojen salauksen purkamiseen

Asennus

Lataa Keycloakin NetHSM-palveluntarjoajan JAR-tiedosto ja tallenna se Keycloakin palveluntarjoajakansioon, esim. /opt/keycloak/providers/

Luo palveluntarjoajarekisteri uudelleen: /opt/keycloak/bin/kc.sh build

Konfigurointi

Asetukset voidaan määrittää joko tiedostossa conf/keycloak.conf tai ympäristömuuttujina. Nämä kaksi muotoa vastaavat samoja asetuksia; ympäristömuuttujat ovat etusijalla, joten tiedostoon voidaan tallentaa avoimia arvoja, ja vain salasanalause syötetään suorituksen aikana.

Käyttämällä 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

Suositellaan konttiympäristöissä, koska salasana voidaan hakea Docker- tai Kubernetes-salaisuudesta sen sijaan, että se kirjoitettaisiin tiedostoon.

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

Muista

Ympäristömuuttujan nimi johdetaan automaattisesti konfiguraatioavaimesta: sen alkuun lisätään KC_, se muutetaan isoiksi kirjaimiksi ja jokainen - korvataan _:llä. Kaksinkertaiset alaviivat johtuvat avaimen rakenteesta, spi-<spi-name>--<provider-id>--<option>, joka tässä laajennuksessa koostuu SPI:stä keys, palveluntarjoajasta nethsm sekä vaihtoehdon nimestä.

See also all available configuration options.

Restart Keycloak

Yhteysprofiili luetaan vain palveluntarjoajan tehtaalla alustuksen yhteydessä. Käynnistä Keycloak uudelleen.

Confirm the server configuration

Tarkista käynnistysloki ennen kuin määrität mitään realmia. Näin voidaan erottaa yhteys- tai tunnistetietojen ongelma realm-määritysongelmasta.

Onnistuessa:

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

Otherwise:

Log message	Cause
Ei viestiä tai virheilmoitus, jossa todetaan, että palveluntarjoaja on pois käytöstä	url is not set
NetHSM is not reachable or not Operational at startup	Väärä osoite, palomuurin estämä, varmenteen PIN-koodin epäyhtenäisyys tai NetHSM on lukittu tai sitä ei ole otettu käyttöön
NetHSM rejected the configured credential with HTTP 401	Wrong username or passphrase

Lisää palveluntarjoaja toimialueeseen

Siirry hallintakonsolissa kohtaan Realm-asetukset → Avaimet → Palveluntarjoajat, valitse Lisää palveluntarjoaja ja valitse nethsm.

Field	Merkitys
Key use	sig tunnisteiden allekirjoittamiseen, enc saapuvien JWE-tunnisteiden salauksen purkamiseen
Key ID prefix	Tämä alue julkaisee kaikki NetHSM-avaimet, joiden tunniste alkaa tällä merkkijonolla
Algorithm	Algoritmi, jonka nojalla nämä avaimet on julkaistu
Priority	Katso Aseta prioriteetti yli 100
Enabled / Active	Molempien on oltava päällä, jotta avain voi allekirjoittaa

Yksi komponentti tukee yhtä algoritmia, mikä vastaa Keycloakin sisäänrakennettuja avainpalvelimia. Realm, joka tarvitsee sekä RS256- että ES256-algoritmeja, sisältää siis kaksi komponenttia. Etuliitteen alla olevat avaimet, jotka eivät tue valittua algoritmia, ohitetaan, joten etuliite voi turvallisesti vastata sekalaista avainjoukkoa.

Varoitus

Älä osoita kahta komponenttia samaan avaimeen eri algoritmeilla. Molemmat julkaisisivat JWKS-merkinnän saman kid alla.

Aseta prioriteetti yli 100:ksi

Tärkeä

Äskettäin luotu realm sisältää neljä luotua avainpalvelinta — rsa-generated, rsa-enc-generated, hmac-generated ja aes-generated — joiden kaikkien prioriteetti on 100. NetHSM-komponentin prioriteetin on oltava korkeampi, muuten Keycloak jatkaa allekirjoittamista luodulla ohjelmistoavaimella ja kokoonpano näyttää toimivan.

NetHSM:n arvoksi 200 on järkevä oletusarvo.

Valitse algoritmi alueelle

Määritä kohdassa Realm Settings → Tokens → Default Signature Algorithm algoritmiksi se, joka on määritetty komponentissa. Jos realm pyytää algoritmia, jota komponentti ei julkaise, Keycloak käyttää varamenetelmänä luotua avainta ilmoittamatta virheestä.

Vahvista

List the published keys:

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

-kentän `kid` arvojen tulisi olla NetHSM-avainten tunnisteet.

Lopullinen tarkistus tehdään myönnetyn tunnuksen avulla. Pyydä sellainen ja pura sen otsikko:

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

Jos kid on NetHSM-avaimen tunniste, allekirjoitus on luotu HSM:n sisällä. Voit myös seurata samanaikaisesti NetHSM:n lokia, jossa pitäisi näkyä asianmukainen kutsu.

Suunnitelma NetHSM:n käyttökatkoksen varalle

Jos NetHSM:ään ei saada yhteyttä eikä avainmetatietoja ole välimuistissa, toimialueella ei ole käyttökelpoisia avaimia ja tunnuksen myöntäminen epäonnistuu sen sijaan, että järjestelmä siirtyisi käyttämään luotua ohjelmistoavainta.

Varoitus

Jos tietyn toimialueen oletusarvoista allekirjoitusalgoritmia hallinnoidaan NetHSM-avaimilla ja NetHSM:ään ei saada yhteyttä, kyseisen toimialueen järjestelmänvalvojan tunnuksia ei myöskään voida myöntää. Tällöin hallintarajapintaa ei voida käyttää ongelman korjaamiseen.

Palautus tapahtuu palvelimen asetusten kautta, ei hallintakonsolin kautta: aseta spi-keys--nethsm--on-unavailable=degrade ja käynnistä palvelin uudelleen tai poista komponentti käytöstä.

Tästä syystä määritä ensin testialue ja jätä alue master käyttämään Keycloakin itse luomia avaimia, jotta hallintakonsoliin pääsee edelleen.

Further Details

You find further details here.