Keycloak

`Keycloak<https://www.keycloak.org/>`__ を NetHSM と組み合わせて使用し、NetHSM に秘密鍵を安全に保存しつつ、Keycloak がアクセストークンの署名や JWE の復号化を行えるようにするには、`このキープロバイダー<https://github.com/Nitrokey/nethsm-keycloak>`__ を次のようにインストールして設定する必要があります：

AIに関する開示

このプロバイダーは、AIの多大な支援を受けて開発・検証されました。

Prepare the NetHSM

NetHSMを次のように準備してください。詳細な手順については、「`の管理」のセクション（<../administration.html>`__）を参照してください。

  • NetHSMが自己署名証明書を使用している場合は、そのフィンガープリントを記録してください：

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

  • `Keycloak専用の「Operator」ユーザーを作成します。<../administration.html#user-management>`__

  • Keycloak拡張機能*は、* のキーを検出しますが、それらを作成することはありません。`必要なキー<../operation.html#key-management>`__ を手動で作成してください：

    • キーID「 」は、レルムが主張するプレフィックスで始まる必要があります。`` や kc-<realm>-<purpose>-<year>` といった適切な命名規則を選択してください（例：kc-staff-sig-rs256-2026、kc-partners-sig-es256-2026、kc-customers-enc-oaep-2026）。このIDは、Keycloakが公開する``kid`` となります。将来のキーローテーションは新しいIDを追加することで行われるため、キーIDの一部として年号を含めることをお勧めします。

    • **** のメカニズムにより、その鍵がどの JOSE アルゴリズムに対応できるかが決定されます：

      NetHSM key type and mechanism

      JOSE algorithms served

      RSA + RSA_Signature_PKCS1

      RS256、RS384、RS512 — ハッシュアルゴリズムに依存しないため、1つの鍵でこれら3つすべてをカバーできます

      RSA +``RSA_Signature_PSS_SHA256`` /_SHA384 /_SHA512

      PS256 / PS384 / PS512 — これらは単にアルゴリズムの名称に過ぎない

      EC_P256 /EC_P384 /EC_P521 +``ECDSA_Signature``

      ES256 / ES384 / ES512 — 曲線によってアルゴリズムが決まる

      Curve25519 + EdDSA_Signature

      EdDSA

      RSA +``RSA_Decryption_OAEP_SHA1`` /_SHA256

      RSA-OAEP / RSA-OAEP-256：受信JWEの復号用

インストール

Keycloak NetHSM プロバイダーの`JAR ファイルを<https://github.com/Nitrokey/nethsm-keycloak/releases>`__ からダウンロードし、Keycloak のプロバイダーフォルダ（例：/opt/keycloak/providers/）に保存してください。

プロバイダ・レジストリを再構築する：/opt/keycloak/bin/kc.sh build

構成

設定は、`` や conf/keycloak.conf` といった形式で指定するか、環境変数として指定することができます。これら2つの形式は同じ設定を表しますが、環境変数が優先されるため、機密情報以外の値はファイルに記述しておき、実行時にパスフレーズのみを挿入することも可能です。

`` を使用 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

コンテナ環境でのデプロイにおいて推奨されます。これは、パスフレーズをファイルに書き込む代わりに、ドッカーや 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_`` を付け、大文字に変換し、- をすべて``_`` に置換します。アンダースコアが2つ並んでいるのは、キーの構造``spi-<spi-name>--<provider-id>--<option>`` に由来しており、この拡張機能の場合、SPI``keys``、プロバイダー``nethsm``、およびオプション名で構成されています。

See also all available configuration options.

Restart Keycloak

接続プロファイルは、プロバイダーファクトリが初期化される際にのみ読み込まれます。Keycloakを再起動してください。

Confirm the server configuration

レルムを設定する前に、起動ログを確認してください。これにより、接続や認証情報の問題と、レルムの設定上の問題を区別することができます。

成功した場合：

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

Otherwise:

Log message

Cause

メッセージが表示されないか、プロバイダーが非アクティブであることを示すデバッグ行が表示される

url is not set

NetHSM is not reachable or not Operational at startup

アドレスが間違っている、ファイアウォールによってブロックされている、証明書のPIN不一致、またはNetHSMがロックされているか、プロビジョニングされていない

NetHSM rejected the configured credential with HTTP 401

Wrong username or passphrase

プロバイダーをレルムに追加する

管理コンソールで、の「レルム設定」→「キー」→「プロバイダー」 に移動し、「**」を選択して、「プロバイダーの追加」** を行い、「nethsm」を選択します。

Field

意味

Key use

sig：トークンの署名用、enc：受信JWEの復号用

Key ID prefix

IDがこの文字列で始まるすべてのNetHSMキーは、このレルムによって公開されます

Algorithm

これらの鍵が公開されているアルゴリズム

Priority

優先度を 100 より大きく設定する を参照してください。

Enabled / Active

署名を行うべき鍵については、両方が有効になっている必要があります

1つのコンポーネントは1つのアルゴリズムを公開し、これはKeycloakに組み込まれているキープロバイダーと同様の仕組みです。したがって、RS256とES256の両方が必要なレルムには、2つのコンポーネントが存在します。選択されたアルゴリズムに対応できないプレフィックス下のキーはスキップされるため、1つのプレフィックスに異なるアルゴリズムのキーが混在していても問題ありません。

注意

異なるアルゴリズムを持つ2つのコンポーネントを、同じキーに向けないでください。そうすると、両方が同じ``kid``の下にJWKSエントリを発行してしまいます。

優先度を100より大きく設定する

重要

rsa-generated rsa-enc-generated hmac-generated `aes-generated`XML-PH-0000@deepl.internal ` XML-PH-0001@deepl.internal `、XML-PH-0002@deepl.internal ` XML-PH-0003@deepl.internal `、XML-PH-0004@deepl.internal ` XML-PH-0005@deepl.internal `、およびXML-PH-0006@deepl.internal ` XML-PH-0007@deepl.internal `です。これらすべての優先度は**100** に設定されています。NetHSMコンポーネントの優先度はこれよりも高く設定する必要があります。そうしないと、Keycloakは生成されたソフトウェアキーを使用して署名し続け、設定は正常に機能しているように見えます。

NetHSM の値として、`` または 200` を設定するのが妥当なデフォルトです。

レルムに適用するアルゴリズムを選択してください

の「Realm Settings」→「Tokens」→「Default Signature Algorithm」 を、コンポーネントで設定されたアルゴリズムに設定してください。Realmが、コンポーネントが公開していないアルゴリズムを要求した場合、Keycloakはエラーを報告せずに、生成された鍵にフォールバックします。

確認する

List the published keys:

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

`` および kid` の値は、NetHSMのキーIDである必要があります。

最終的な確認は、発行されたトークンです。トークンをリクエストし、そのヘッダーをデコードしてください：

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 のキー ID である場合、署名は HSM 内で生成されたことになります。併せて NetHSM のログを確認すると、該当する呼び出しが記録されているはずです。

NetHSMが利用できない場合の対応計画

NetHSM に接続できず、キーのメタデータもキャッシュされていない場合、そのレルムには使用可能なキーが存在しないため、生成されたソフトウェアキーにフォールバックすることなく、トークンの発行は失敗します。

警告

あるレルムのデフォルトの署名アルゴリズムがNetHSMキーによって提供されており、NetHSMに接続できなくなった場合、そのレルムの管理用トークンも発行できなくなります。その結果、この問題を解決するための管理用APIも利用できなくなります。

復旧は、管理コンソールではなくサーバーの設定を通じて行います。` を`spi-keys--nethsm--on-unavailable=degrade``に設定して再起動するか、コンポーネントを無効にしてください。

このため、まずテスト用レルムを設定し、master のレルムについては、Keycloakが自動的に生成したキーのままにしておくことで、管理コンソールへのアクセスを維持できるようにしてください。

Further Details

You find further details here.