Keycloak¶
Για να χρησιμοποιήσετε το Keycloak με το NetHSM, ώστε να αποθηκεύετε με ασφάλεια τα ιδιωτικά κλειδιά στο NetHSM και ταυτόχρονα να επιτρέπετε στο Keycloak να υπογράφει διακριτικά πρόσβασης και να αποκρυπτογραφεί JWE, πρέπει να εγκαταστήσετε και να διαμορφώσετε αυτόν τον πάροχο κλειδιών ως εξής:
Γνωστοποίηση σχετικά με την τεχνητή νοημοσύνη¶
Αυτός ο πάροχος δημιουργήθηκε και ελέγχθηκε με σημαντική βοήθεια από την τεχνητή νοημοσύνη.
Prepare the NetHSM¶
Προετοιμάστε το NetHSM ως εξής. Ανατρέξτε στην ενότητα «Διαχείριση του » για λεπτομερείς οδηγίες.
Εάν το NetHSM χρησιμοποιεί αυτο-υπογεγραμμένο πιστοποιητικό, καταγράψτε το δακτυλικό του αποτύπωμα:
echo | openssl s_client -connect $NETHSM_HOST 2>/dev/null \ | openssl x509 -fingerprint -sha256 -noout
Δημιουργήστε έναν χρήστη τύπου «Operator» αποκλειστικά για το Keycloak.
Η επέκταση Keycloak εντοπίζει τα κλειδιά, αλλά δεν τα δημιουργεί. Δημιουργήστε τα επιθυμητά κλειδιά χειροκίνητα:
Το αναγνωριστικό κλειδιού πρέπει να ξεκινά με το πρόθεμα που θα διεκδικήσει ο τομέας. Επιλέξτε ένα κατάλληλο σχήμα ονοματολογίας, όπως
kc-<realm>-<purpose>-<year>(για παράδειγμαkc-staff-sig-rs256-2026,kc-partners-sig-es256-2026,kc-customers-enc-oaep-2026). Το αναγνωριστικό μετατρέπεται στοkidπου δημοσιεύει το Keycloak. Η μελλοντική εναλλαγή κλειδιών πραγματοποιείται με την προσθήκη νέων αναγνωριστικών, γι’ αυτό προτείνουμε να χρησιμοποιείτε το έτος ως μέρος του αναγνωριστικού κλειδιού.Οι μηχανισμοί καθορίζουν για ποιους αλγόριθμους JOSE μπορεί να χρησιμοποιηθεί το κλειδί:
NetHSM key type and mechanism
JOSE algorithms served
RSA+RSA_Signature_PKCS1RS256, RS384, RS512 — ανεξάρτητα από τον αλγόριθμο κατακερματισμού, οπότε ένα κλειδί καλύπτει και τα τρία
RSA+RSA_Signature_PSS_SHA256/_SHA384/_SHA512PS256 / PS384 / PS512 — οι ονομασίες αυτές αναφέρονται αποκλειστικά στον αλγόριθμο
EC_P256/EC_P384/EC_P521+ECDSA_SignatureES256 / ES384 / ES512 — η καμπύλη καθορίζει τον αλγόριθμο
Curve25519+EdDSA_SignatureEdDSA
RSA+RSA_Decryption_OAEP_SHA1/_SHA256RSA-OAEP / RSA-OAEP-256, για την αποκρυπτογράφηση εισερχόμενων JWE
Εγκατάσταση¶
Κατεβάστε το αρχείο JAR του παρόχου Keycloak NetHSM ` <https://github.com/Nitrokey/nethsm-keycloak/releases>` __, αποθηκεύστε το στο φάκελο παρόχων του Keycloak, π.χ. /opt/keycloak/providers/
Επαναδημιουργία του μητρώου παρόχων: /opt/keycloak/bin/kc.sh build
Διαμόρφωση¶
Οι ρυθμίσεις μπορούν να καθοριστούν είτε στο αρχείο conf/keycloak.conf είτε ως μεταβλητές περιβάλλοντος. Και οι δύο μορφές αντιστοιχούν στις ίδιες ρυθμίσεις· οι μεταβλητές περιβάλλοντος έχουν προτεραιότητα, οπότε οι μη απόρρητες τιμές μπορούν να παραμείνουν στο αρχείο, ενώ μόνο η φράση πρόσβασης εισάγεται κατά την εκτέλεση.
Χρησιμοποιώντας το 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¶
Προτιμάται σε εγκαταστάσεις μέσω κοντέινερ, καθώς η φράση πρόσβασης μπορεί να παρέχεται από ένα «secret» του Docker ή του Kubernetes, αντί να αποθηκεύεται σε αρχείο.
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...
Σημείωση
Το όνομα της μεταβλητής περιβάλλοντος προκύπτει αυτόματα από το κλειδί διαμόρφωσης: προστίθεται το πρόθεμα KC_, μετατρέπεται σε κεφαλαία και κάθε - αντικαθίσταται με _. Οι διπλές κάτω παύλες προκύπτουν από τη δομή του κλειδιού, spi-<spi-name>--<provider-id>--<option>, η οποία για την παρούσα επέκταση αποτελείται από το SPI keys, τον πάροχο nethsm και το όνομα της επιλογής.
See also all available configuration options.
Restart Keycloak¶
Το προφίλ σύνδεσης διαβάζεται μόνο κατά την αρχικοποίηση του provider factory. Επανεκκινήστε το Keycloak.
Confirm the server configuration¶
Ελέγξτε το αρχείο καταγραφής εκκίνησης πριν προχωρήσετε στη διαμόρφωση οποιουδήποτε realm. Με αυτόν τον τρόπο διαχωρίζετε ένα πρόβλημα σύνδεσης ή διαπιστευτηρίων από ένα πρόβλημα διαμόρφωσης του realm.
Σε περίπτωση επιτυχίας:
NetHSM key provider ready: 1 instance(s), user 'keycloak',
discovery cache PT5M, on-unavailable fail
Otherwise:
Log message |
Cause |
|---|---|
Δεν εμφανίζεται κανένα μήνυμα ή εμφανίζεται μια γραμμή εντοπισμού σφαλμάτων που αναφέρει ότι ο πάροχος είναι ανενεργός |
|
|
Λανθασμένη διεύθυνση, αποκλεισμός από τείχος προστασίας, ασυμφωνία κωδικού PIN πιστοποιητικού ή το NetHSM είναι κλειδωμένο ή δεν έχει διαμορφωθεί |
|
Wrong username or passphrase |
Προσθήκη του παρόχου σε ένα realm¶
Στην κονσόλα διαχείρισης, μεταβείτε στη διεύθυνση , επιλέξτε «Ρυθμίσεις Realm» → «Κλειδιά» → «Πάροχοι», επιλέξτε « », κάντε κλικ στο «Προσθήκη παρόχου» και επιλέξτε « nethsm».
Field |
Σημασία |
|---|---|
Key use |
|
Key ID prefix |
Κάθε κλειδί NetHSM του οποίου το αναγνωριστικό αρχίζει με αυτή τη συμβολοσειρά δημοσιεύεται από αυτόν τον τομέα |
Algorithm |
Ο αλγόριθμος βάσει του οποίου δημοσιεύονται αυτά τα κλειδιά |
Priority |
Δείτε το Ορίστε την προτεραιότητα σε τιμή μεγαλύτερη από 100 |
Enabled / Active |
Και τα δύο πρέπει να είναι ενεργοποιημένα για ένα κλειδί που πρέπει να υπογράψει |
Κάθε στοιχείο δημοσιεύει έναν αλγόριθμο, ακολουθώντας το μοντέλο των ενσωματωμένων παρόχων κλειδιών του Keycloak. Επομένως, ένας τομέας που απαιτεί τόσο RS256 όσο και ES256 διαθέτει δύο στοιχεία. Τα κλειδιά κάτω από το πρόθεμα που δεν μπορούν να εξυπηρετήσουν τον επιλεγμένο αλγόριθμο παραλείπονται, οπότε ένα πρόθεμα μπορεί να αντιστοιχεί με ασφάλεια σε ένα μεικτό σύνολο κλειδιών.
Προσοχή
Μην αντιστοιχίζετε δύο στοιχεία στο ίδιο κλειδί χρησιμοποιώντας διαφορετικούς αλγόριθμους. Και τα δύο θα δημοσιεύσουν μια καταχώριση JWKS κάτω από το ίδιο kid.
Ορίστε την προτεραιότητα σε τιμή μεγαλύτερη από 100¶
Σημαντικό
Ένας νεοδημιουργημένος τομέας περιέχει τέσσερις δημιουργημένους παρόχους κλειδιών — rsa-generated, rsa-enc-generated, hmac-generated και aes-generated — όλοι με προτεραιότητα 100. Το στοιχείο NetHSM πρέπει να έχει υψηλότερη προτεραιότητα, διαφορετικά το Keycloak συνεχίζει να υπογράφει με ένα δημιουργημένο λογισμικό κλειδί και η διαμόρφωση φαίνεται να λειτουργεί.
Μια τιμή του τύπου 200 για το NetHSM αποτελεί μια λογική προεπιλογή.
Επιλέξτε τον αλγόριθμο για το realm¶
Ορίστε τη ρύθμιση « » (Προεπιλεγμένος αλγόριθμος υπογραφής) στο «Realm Settings» (Ρυθμίσεις περιβάλλοντος) → «Tokens» (Διακριτικά) → «Default Signature Algorithm» (Προεπιλεγμένος αλγόριθμος υπογραφής) στον αλγόριθμο που έχει ρυθμιστεί στο στοιχείο. Εάν το περιβάλλον ζητήσει έναν αλγόριθμο που το στοιχείο δεν δημοσιεύει, το Keycloak θα χρησιμοποιήσει ένα κλειδί που δημιουργείται αυτόματα χωρίς να αναφέρει σφάλμα.
Επαλήθευση¶
List the published keys:
curl -s https://<keycloak-host>/realms/<realm>/protocol/openid-connect/certs
Οι τιμές « ` » kid` πρέπει να είναι τα αναγνωριστικά κλειδιών NetHSM.
Ο οριστικός έλεγχος γίνεται μέσω ενός εκδοθέντος token. Ζητήστε ένα και αποκωδικοποιήστε την κεφαλίδα του:
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 + "==")))'
Εάν kid είναι το αναγνωριστικό κλειδιού του NetHSM, η υπογραφή δημιουργήθηκε εντός του HSM. Μπορείτε επίσης να παρακολουθήσετε παράλληλα το αρχείο καταγραφής του NetHSM, το οποίο θα πρέπει να εμφανίζει την αντίστοιχη κλήση.
Further Details¶
You find further details here.