3.9. レルムキーの設定
Keycloak で使用される認証プロトコルには、暗号化署名が必要であり、場合によっては暗号化も必要です。Red Hat build of Keycloak は、これを実現するために非対称のキーペア (秘密鍵と公開鍵) を使用します。
Red Hat build of Keycloak では、同時に持てるアクティブキーペアは 1 つですが、複数のパッシブキーを持つこともできます。アクティブキーペアは新しい署名の作成に使用され、パッシブキーペアは以前の署名の検証に使用できます。これにより、ダウンタイムやユーザーの中断なしにキーを定期的にローテーションできます。
レルムが作成されると、キーペアと自己署名付き証明書が自動的に生成されます。
手順
- メニューで Realm settings をクリックします。
- Keys をクリックします。
- パッシブキー を表示するには、フィルタードロップダウンからパッシブキーを選択します。
- フィルタードロップダウンから Disabled keys を選択して、無効なキーを表示します。
キーペアのステータスは Active
になりますが、レルムの現在アクティブなキーペアとしては選択されません。署名に使用されるアクティブなペアは、優先順位に基づきソートされたアクティブキーペアを提供できるキープロバイダーのうち、最初のキープロバイダーが選択されます。
3.9.1. 鍵のローテーション
鍵を定期的にローテーションすることが推奨されます。既存のアクティブなキーよりも優先度の高い新しいキーを作成することから始めます。代わりに、同じ優先度で新しいキーを作成し、以前のキーをパッシブにすることができます。
新しいキーが使用可能になると、すべての新しいトークンと cookie はその新しいキーで署名されます。ユーザーがアプリケーションに対して認証されると、SSO Cookie が新しい署名で更新されます。OpenID Connect トークンを更新すると、新しいキーで新たなトークンが署名されます。最終的には、すべての Cookie とトークンは新しいキーを使用し、しばらくすると、古いキーを削除できます。
古いキーを削除する頻度は、セキュリティー間のトレードオフであり、すべてのクッキーとトークンが更新されるようにすることです。新しいキーの作成後に、3 カ月から 6 カ月までのすべてのキーを作成し、古いキーを 2 カ月に削除することを検討してください。新しいキーが追加され、古いキーが削除されるまでの期間にユーザーが非アクティブである場合、そのユーザーは再認証する必要があります。
鍵をローテーションすると、オフライントークンにも適用されます。これらのアプリケーションが古いキーが削除される前にトークンを更新する必要のあることを確認するには、アプリケーションを更新します。
3.9.2. 生成されたキーペアの追加
この手順を使用して、自己署名付き証明書を含むキーペアを生成できます。
手順
- 管理コンソールでレルムを選択します。
- メニューで Realm settings をクリックします。
- Keys タブをクリックします。
- Providers タブをクリックします。
- Add provider をクリックし、rsa-generated を選択します。
- Priority フィールドに番号を入力します。この数字は、新しいキーペアがアクティブなキーペアになるかどうかを決定します。最も大きい番号のキーペアがアクティブになります。
- AES Key size の値を選択します。
- Save をクリックします。
プロバイダーの優先度を変更すると、キーが再生成されますが、キーサイズを変更する場合はプロバイダーを編集し、新しいキーが生成されます。
3.9.3. 証明書の抽出によるキーのローテーション
RSA で生成されたキーペアから証明書を抽出し、その証明書を新しいキーストアで使用することにより、キーをローテーションできます。
前提条件
- 生成されたキーペア
手順
- 管理コンソールでレルムを選択します。
- Realm Settings をクリックします。
Keys タブをクリックします。
Active キーのリストが表示されます。
RSA キーのある行で、Public Keys の下の Certificate をクリックします。
証明書はテキスト形式で表示されます。
証明書をファイルに保存し、これらの行で囲みます。
----Begin Certificate---- <Output> ----End Certificate----
- keytool コマンドを使用して、キーファイルを PEM 形式に変換します。
キーストアから現在の RSA 公開鍵証明書を削除します。
keytool -delete -keystore <keystore>.jks -storepass <password> -alias <key>
新しい証明書をキーストアにインポートします。
keytool -importcert -file domain.crt -keystore <keystore>.jks -storepass <password> -alias <key>
アプリケーションをリビルドします。
mvn clean install wildfly:deploy
3.9.4. 既存のキーペアと証明書の追加
別のユーザーが取得したキーペアと証明書を追加するには、Providers
を選択し、ドロップダウンから rsa
を選択します。新たなキーペアがアクティブなキーペアになるように、優先度を変更できます。
前提条件
- プライベートキーファイル。ファイルは PEM 形式である必要があります。
手順
- 管理コンソールでレルムを選択します。
- Realm settings をクリックします。
- Keys タブをクリックします。
- Providers タブをクリックします。
- Add provider をクリックし、rsa を選択します。
- Priority フィールドに番号を入力します。この数字は、新しいキーペアがアクティブなキーペアになるかどうかを決定します。
- Private RSA Key の横にある Browse... をクリックして、秘密キーファイルをアップロードします。
- 秘密キーの署名付き証明書がある場合は、X509 Certificate の横にある Browse... をクリックして証明書ファイルをアップロードします。証明書をアップロードしない場合、Red Hat build of Keycloak は自己署名付き証明書を自動的に生成します。
- Save をクリックします。
3.9.5. Java キーストアからキーを読み込む
ホストの Java キーストアファイルに保存されているキーペアと証明書を追加するには、Provider
を選択し、ドロップダウンから java-keystore
を選択します。新たなキーペアがアクティブなキーペアになるように、優先度を変更できます。
関連する証明書チェーンをロードするには、キーペアのロードに使用したものと同じ Key Alias
を使用して Java キーストアファイルにインポートする必要があります。
手順
- 管理コンソールでレルムを選択します。
- メニューで Realm settings をクリックします。
- Keys タブをクリックします。
- Providers タブをクリックします。
- Add provider をクリックし、java-keystore を選択します。
- Priority フィールドに番号を入力します。この数字は、新しいキーペアがアクティブなキーペアになるかどうかを決定します。
-
希望の アルゴリズム を入力します。アルゴリズムは鍵タイプに一致する必要があることに注意してください(たとえば、
RS256
には RSA 秘密鍵、ES256
は EC 秘密鍵、またはAES
シークレットキーが必要です)。 - キーストア の値を入力します。キーストアファイルへのパス。
- キーストアパスワードを入力します。このオプションは、外部 vault からの値を参照できます。
-
Keystore Type (
JKS
、PKCS12
、またはBCFKS
)の値を入力します。 - キーストアからロードする Key Alias の値を入力します。
- Key Password を入力します。このオプションは、外部 vault からの値を参照できます。
-
キー使用 の値を入力します(署名の場合は
sig
、暗号化の場合はenc
)。アルゴリズムタイプと一致する必要があることに注意してください(たとえば、RS256
はsig
ですが、RSA-OAEP
はenc
です)。 - Save をクリックします。
すべてのキーストアタイプがすべてのタイプのキーをサポートしているわけではありません。たとえば、すべてのモードの JKS
および fips モード(BCFIPS
プロバイダー)の PKCS12
は秘密鍵エントリーを保存できません。
3.9.6. 鍵のパッシブの作成
手順
- 管理コンソールでレルムを選択します。
- メニューで Realm settings をクリックします。
- Keys タブをクリックします。
- Providers タブをクリックします。
- パッシブに設定するキーのプロバイダーをクリックします。
- Active を Off に切り替えます。
- Save をクリックします。
3.9.7. キーの無効化
手順
- 管理コンソールでレルムを選択します。
- メニューで Realm settings をクリックします。
- Keys タブをクリックします。
- Providers タブをクリックします。
- パッシブに設定するキーのプロバイダーをクリックします。
- Enabled を Off に切り替えます。
- Save をクリックします。
3.9.8. 侵害された鍵
Red Hat build of Keycloak は署名鍵をローカルにのみ保存し、それをクライアントアプリケーション、ユーザー、または他のエンティティーと共有することはありません。ただし、レルム署名鍵が侵害されたと思われる場合は、上記のとおり最初に新しいキーペアを生成し、侵害されたキーペアを即座に削除する必要があります。
または、プロバイダーを Providers
テーブルから削除できます。
手順
- メニューで Clients をクリックします。
- security-admin-console をクリックします。
- Access settings セクションまで下にスクロールします。
- Admin URL フィールドに入力します。
- Advanced タブをクリックします。
- Revocation セクションで Set to now をクリックします。
- Push をクリックします。
not-before ポリシーをプッシュすると、クライアントアプリケーションは、セキュリティー侵害を受けたキーで署名された既存のトークンを受け入れないようにします。クライアントアプリケーションは Red Hat build of Keycloak から新しいキーペアをダウンロードするように強制されるため、侵害されたキーで署名されたトークンは無効になります。
REST および機密クライアントは、プッシュされた not-before ポリシーリクエストを Red Hat build of Keycloak がクライアントに送信できるように、Admin URL を設定する必要があります。