Keycloak¶
Aby korzystać z Keycloak wraz z NetHSM w celu bezpiecznego przechowywania kluczy prywatnych w NetHSM, umożliwiając jednocześnie Keycloak podpisywanie tokenów dostępu i odszyfrowywanie JWE, należy zainstalować i skonfigurować ten dostawca kluczy w następujący sposób:
Informacja dotycząca sztucznej inteligencji¶
Niniejszy serwis został opracowany i zweryfikowany przy znacznym wsparciu sztucznej inteligencji.
Prepare the NetHSM¶
Przygotuj urządzenie NetHSM w następujący sposób. Szczegółowe instrukcje znajdziesz w sekcji „ administration”.
Jeśli NetHSM korzysta z certyfikatu z podpisem własnym, zapisz jego odcisk:
echo | openssl s_client -connect $NETHSM_HOST 2>/dev/null \ | openssl x509 -fingerprint -sha256 -noout
Utwórz konto użytkownika typu „Operator” przeznaczone wyłącznie dla Keycloak.
Rozszerzenie Keycloak wykrywa klucze, ale ich nie tworzy. Utwórz żądane klucze ręcznie:
Identyfikator klucza musi zaczynać się od prefiksu, który będzie przypisany do danej domeny. Należy wybrać odpowiedni schemat nazewnictwa, np.
kc-<realm>-<purpose>-<year>(na przykładkc-staff-sig-rs256-2026,kc-partners-sig-es256-2026,kc-customers-enc-oaep-2026). Identyfikator ten staje się adresemkidpublikowanym przez Keycloak. Przyszła rotacja kluczy odbywa się poprzez dodawanie nowych identyfikatorów, dlatego zalecamy uwzględnienie roku w identyfikatorze klucza.Mechanizmy opisane na stronie określają, w jakich algorytmach JOSE klucz może być wykorzystywany:
NetHSM key type and mechanism
JOSE algorithms served
RSA+RSA_Signature_PKCS1RS256, RS384, RS512 — niezależne od algorytmu haszującego, więc jeden klucz obejmuje wszystkie trzy
RSA+RSA_Signature_PSS_SHA256/_SHA384/_SHA512PS256 / PS384 / PS512 — nazwy te odnoszą się wyłącznie do algorytmu
EC_P256/EC_P384/EC_P521+ECDSA_SignatureES256 / ES384 / ES512 — krzywa określa algorytm
Curve25519+EdDSA_SignatureEdDSA
RSA+RSA_Decryption_OAEP_SHA1/_SHA256RSA-OAEP / RSA-OAEP-256, do odszyfrowywania przychodzących plików JWE
Instalacja¶
Pobierz plik JAR dostawcy Keycloak NetHSM ` <https://github.com/Nitrokey/nethsm-keycloak/releases>` __, zapisz go w folderze dostawców Keycloak, np. /opt/keycloak/providers/
Odbuduj rejestr dostawców: /opt/keycloak/bin/kc.sh build
Konfiguracja¶
Ustawienia można podać albo w pliku ` `` conf/keycloak.conf`, albo jako zmienne środowiskowe. Obie formy odpowiadają tym samym ustawieniom; zmienne środowiskowe mają pierwszeństwo, więc wartości, które nie są poufne, mogą znajdować się w pliku, a hasło jest wstawiane dopiero w czasie wykonywania.
Korzystając z 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¶
Rozwiązanie to jest preferowane w przypadku wdrożeń kontenerowych, ponieważ hasło można pobrać z sekretu Docker lub Kubernetes zamiast zapisywać je w pliku.
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...
Informacja
Nazwa zmiennej środowiskowej jest generowana automatycznie na podstawie klucza konfiguracyjnego: należy dodać przedrostek KC_, zamienić na wielkie litery oraz zastąpić każde - na _. Podwójne podkreślenia wynikają ze struktury klucza, spi-<spi-name>--<provider-id>--<option>, który w przypadku tego rozszerzenia składa się z SPI keys, dostawcy nethsm oraz nazwy opcji.
See also all available configuration options.
Restart Keycloak¶
Profil połączenia jest odczytywany wyłącznie podczas inicjalizacji fabryki dostawców. Uruchom ponownie Keycloak.
Confirm the server configuration¶
Przed skonfigurowaniem jakiegokolwiek obszaru należy sprawdzić dziennik uruchamiania. Pozwala to odróżnić problem z połączeniem lub danymi uwierzytelniającymi od problemu z konfiguracją obszaru.
W przypadku powodzenia:
NetHSM key provider ready: 1 instance(s), user 'keycloak',
discovery cache PT5M, on-unavailable fail
Otherwise:
Log message |
Cause |
|---|---|
Brak komunikatu lub wiersz debugowania informujący, że dostawca jest nieaktywny |
|
|
Nieprawidłowy adres, blokada przez zaporę sieciową, niezgodność kodu PIN certyfikatu lub urządzenie NetHSM jest zablokowane lub nie zostało skonfigurowane |
|
Wrong username or passphrase |
Dodaj dostawcę do obszaru¶
W konsoli administracyjnej przejdź do sekcji „ ” (Ustawienia królestwa) → „Keys” (Klucze) → „Providers” (Dostawcy), wybierz opcję „ ” (Dodać dostawcę), a następnie wybierz nethsm.
Field |
Znaczenie |
|---|---|
Key use |
|
Key ID prefix |
Każdy klucz NetHSM, którego identyfikator zaczyna się od tego ciągu znaków, jest publikowany przez tę domenę |
Algorithm |
Algorytm, na podstawie którego opublikowano te klucze |
Priority |
Zobacz Ustaw priorytet powyżej 100 |
Enabled / Active |
Oba muszą być włączone, aby klucz mógł podpisać |
Jeden komponent obsługuje jeden algorytm, na wzór wbudowanych dostawców kluczy w Keycloak. Realm, który wymaga zarówno RS256, jak i ES256, posiada zatem dwa komponenty. Klucze pod prefiksem, które nie obsługują wybranego algorytmu, są pomijane, więc prefiks może bez problemu odpowiadać mieszanemu zestawowi kluczy.
Ostrzeżenie
Nie należy kierować dwóch komponentów na ten sam klucz przy użyciu różnych algorytmów. Oba opublikowałyby wpis JWKS pod tym samym adresem kid.
Ustaw priorytet powyżej 100¶
Ważne
Nowo utworzona instancja zawiera cztery wygenerowane dostawcy kluczy — rsa-generated, rsa-enc-generated, hmac-generated oraz aes-generated — wszystkie z priorytetem 100. Komponent NetHSM musi mieć wyższy priorytet, w przeciwnym razie Keycloak będzie nadal podpisywać dane za pomocą wygenerowanego klucza programowego, a konfiguracja będzie sprawiać wrażenie, że działa.
Wartość 200 dla NetHSM stanowi rozsądne ustawienie domyślne.
Wybierz algorytm dla królestwa¶
W sekcji „ ” (Ustawienia domeny) → „Tokens” (Tokeny) → „Default Signature Algorithm” (Domyślny algorytm podpisu) należy ustawić algorytm skonfigurowany w komponencie. Jeśli domena zażąda algorytmu, którego komponent nie udostępnia, Keycloak zastosuje klucz wygenerowany automatycznie, nie zgłaszając błędu.
Sprawdź¶
List the published keys:
curl -s https://<keycloak-host>/realms/<realm>/protocol/openid-connect/certs
Wartości w pliku ` `` kid` powinny odpowiadać identyfikatorom kluczy NetHSM.
Ostatecznym potwierdzeniem jest wygenerowany token. Poproś o niego i odszyfruj jego nagłówek:
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 + "==")))'
Jeśli kid to identyfikator klucza NetHSM, podpis został wygenerowany wewnątrz modułu HSM. Można również równolegle śledzić dziennik NetHSM, w którym powinno pojawić się odpowiednie wywołanie.
Further Details¶
You find further details here.