8.6. X.509 クライアント証明書ユーザー認証
相互 SSL 認証を使用するようにサーバーを設定した場合、Red Hat build of Keycloak は、X.509 クライアント証明書を使用したログインをサポートします。
通常のワークフロー:
- クライアントは SSL/TLS チャンネルで認証リクエストを送信します。
- SSL/TLS ハンドシェイクの間、サーバーとクライアントは x.509/v3 証明書を交換します。
- コンテナー (JBoss EAP) は、証明書 PKIX パスと証明書の有効期限を検証します。
X.509 クライアント証明書オーセンティケーターは、以下の方法を使用してクライアント証明書を検証します。
- CRL または CRL Distribution Points を使用して、証明書失効ステータスを確認します。
- OCSP (Online Certificate Status Protocol) を使用して、証明書失効ステータスを確認します。
- 証明書の鍵が予想される鍵と一致するかどうかを確認します。
- 証明書の拡張鍵が、想定された拡張鍵と一致するかどうかを検証します。
- これらのチェックのいずれかが失敗すると、x.509 認証は失敗します。それ以外の場合は、オーセンティケーターは証明書のアイデンティティーを抽出し、これを既存ユーザーにマッピングします。
証明書が既存のユーザーにマッピングされると、認証フローに応じてさまざまな動作が行われます。
- Browser Flow では、サーバーはユーザーに対してアイデンティティーを確認するか、ユーザー名とパスワードを使用してサインインするよう要求します。
- Direct Grant Flow では、サーバーはユーザーにサインインします。
証明書 PKIX パスを検証するのは Web コンテナーのロールであることに注意してください。Red Hat build of Keycloak 側の X.509 オーセンティケーターは、証明書の有効期限、証明書失効ステータス、およびキーの使用を確認する追加のサポートのみを提供します。リバースプロキシーの背後にデプロイされた Red Hat build of Keycloak を使用している場合は、リバースプロキシーが PKIX パスを検証するように設定されていることを確認します。リバースプロキシーを使用せず、ユーザーが JBoss EAP に直接アクセスする場合は、以下のように PKIX パスが設定されている限り、JBoss EAP が PKIX パスが検証された状態を維持するので問題ありません。
8.6.1. 機能
サポートされる証明書アイデンティティーソース:
- 正規表現を使用した SubjectDN の一致
- X500 サブジェクトの email 属性
- Subject Alternative Name Extension からの X500 サブジェクトの email (RFC822Name General Name)
- サブジェクトの別名エクステンションの X500 サブジェクトの他の名前。通常、この他の名前は User Principal Name (UPN) です。
- X500 サブジェクトのコモンネーム属性
- 正規表現を使用した IssuerDN の一致
- 証明書のシリアル番号
- Certificate Serial Number および IssuerDN
- SHA-256 証明書サムプリント
- PEM 形式の完全な証明書
8.6.1.1. 正規表現
Red Hat build of Keycloak は、正規表現をフィルターとして使用して、サブジェクト DN または発行者 DN から証明書のアイデンティティーを抽出します。たとえば、以下の正規表現は email 属性とマッチします。
emailAddress=(.*?)(?:,|$)
正規表現のフィルターは、Identity Source が、Match SubjectDN using regular expression または Match IssuerDN using regular expression のいずれかに設定されている場合にのみ適用されます。
8.6.1.1.1. 既存のユーザーへの証明書 ID のマッピング
証明書アイデンティティーマッピングは、抽出したユーザー ID を、既存のユーザーのユーザー名、メール、または値が証明書 ID とマッチするカスタム属性にマッピングできます。たとえば、Identity source を Subject's email に設定するか、User mapping method を Username or email に設定すると、X.509 クライアント証明書オーセンティケーターは、ユーザー名または電子メールで既存のユーザーを検索するときに、証明書の Subject DN の email 属性を検索条件として使用します。
- レルム設定で Login with email を無効にすると、同じルールが証明書認証に適用されます。ユーザーは email 属性を使用してログインできません。
-
Certificate Serial Number and IssuerDNを ID ソースとして使用するには、シリアル番号と IssuerDN に 2 つのカスタム属性が必要です。 -
SHA-256 Certificate thumbprintは、SHA-256 証明書のサムプリントの小文字の 16 進数表記です。 -
ID ソースとしての
Full certificate in PEM formatの使用は、LDAP などの外部フェデレーションソースにマッピングされたカスタム属性に限定されます。Red Hat build of Keycloak は、長さの制限によりデータベースに証明書を保存できません。そのため、LDAP の場合は、Always Read Value From LDAPを有効にする必要があります。
8.6.1.1.2. 拡張証明書の検証
- CRL を使用した失効ステータスの確認。
- CRL/分散ポイントを使用した失効ステータスの確認。
- OCSP/Responder URI を使用した失効ステータスの確認。
- 証明書 KeyUsage の検証。
- 証明書 ExtendedKeyUsage の検証。
8.6.2. ブラウザーフローへの X.509 クライアント証明書認証の追加
- メニューで Authentication をクリックします。
- Browser フローをクリックします。
- Action リストから Duplicate を選択します。
- コピーの名前を入力します。
- 複製 をクリックします。
- Add step をクリックします。
- "X509/Validate Username Form" をクリックします。
Add をクリックします。
X509 実行
- "X509/Validate Username Form" をクリックし、"Browser Forms" 実行の上にドラッグします。
要件を "ALTERNATIVE" に設定します。
X509 ブラウザーフロー
- Action メニューをクリックします。
- Bind flow をクリックします。
- ドロップダウンリストから Browser flow をクリックします。
Save をクリックします。
X509 ブラウザーフローバインディング
8.6.3. X.509 クライアント証明書認証の設定
X509 設定
- User Identity Source
- クライアント証明書からユーザーアイデンティティーを抽出する方法を定義します。
- Canonical DN representation enabled
- 正規の形式を使用して識別名を判断するかどうかを定義します。公式の Java API ドキュメント で形式が説明されています。このオプションは、2 つのユーザーアイデンティティーソース Match SubjectDN using regular expression および Match IssuerDN using regular expression にのみ影響します。新しい Red Hat build of Keycloak インスタンスを設定するときにこのオプションを有効にします。既存の Red Hat build of Keycloak インスタンスとの後方互換性を維持するには、このオプションを無効にします。
- Enable Serial Number hexadecimal representation
- シリアル番号 を 16 進数で表します。符号ビットに 1 が設定されているシリアル番号は、00 オクテットを左に追加する必要があります。たとえば、10 進値が161のシリアル番号、または 16 進表現のa1は、RFC5280 に従って00a1としてエンコードされます。詳細は、RFC5280, appendix-B を参照してください。
- A regular expression
- 証明書 ID を抽出するフィルターとして使用する正規表現。表現には 1 つのグループを含める必要があります。
- User Mapping Method
- 証明書 ID を既存ユーザーに一致させる方法を定義します。Username or email は、ユーザー名またはメールアドレスで既存のユーザーを検索します。Custom Attribute Mapperは、証明書 ID と一致するカスタム属性を持つ既存のユーザーを検索します。カスタム属性の名前は設定可能です。
- A name of user attribute
- 値が証明書アイデンティティーと照合されるカスタム属性。属性マッピングが複数の値に関連する場合は、複数のカスタム属性を使用します (例: 'Certificate Serial Number and IssuerDN')。
- CRL Checking Enabled
- Certificate Revocation List を使用して、証明書の失効ステータスを確認します。リストの場所は、CRL file path 属性で定義されます。
- Enable CRL Distribution Point to check certificate revocation status
- CDP を使用して、証明書失効ステータスを確認します。ほとんどの PKI 認証局には、証明書に CDP が含まれます。
- CRL file path
- CRL リストが含まれるファイルへのパス。CRL Checking Enabled オプションが有効になっている場合、値は有効なファイルへのパスである必要があります。
- OCSP Checking Enabled
- Online Certificate Status Protocol を使用して、証明書失効ステータスを確認します。
- OCSP Fail-Open Behavior
- デフォルトでは、認証を成功させるために、OCSP チェックは肯定応答を返す必要があります。ただし、このチェックが決定的でない場合があります。たとえば、OCSP サーバーに到達できない、過負荷になっている、またはクライアント証明書に OCSP レスポンダー URI が含まれていない可能性があります。この設定をオンにすると、OCSP レスポンダーが明示的な否定応答を受信し、証明書が確実に取り消された場合にのみ、認証が拒否されます。有効な OCSP 応答がない場合は、認証試行が許可されます。
- OCSP Responder URI
- 証明書の OCSP レスポンダー URI の値を上書きします。
- Validate Key Usage
- 証明書の KeyUsage 拡張ビットが設定されていることを検証します。たとえば、"digitalSignature,KeyEncipherment" は、KeyUsage 拡張のビット 0 と 2 が設定されているかどうかを検証します。Key Usage の検証を無効にするには、このパラメーターを空欄のままにします。詳細は、RFC5280, Section-4.2.1.3 を参照してください。Red Hat build of Keycloak では、キーの使用が一致しないとエラーが発生します。
- Validate Extended Key Usage
- Extended Key Usage 拡張で定義された 1 つまたは複数の目的を検証します。詳細は、RFC5280, Section-4.2.1.12 を参照してください。Extended Key Usage の検証を無効にするには、このパラメーターを空欄のままにします。Red Hat build of Keycloak では、発行元 CA が重要としてフラグを付け、キーの使用の拡張が一致しない場合、エラーが発生します。
- 証明書ポリシーの検証
- 証明書ポリシー拡張で定義されている 1 つ以上のポリシー OID を確認します。RFC5280 のセクション -4.2.1.4 を参照してください。証明書要求の検証を無効にするには、パラメーターを空のままにします。複数のポリシーはコンマで区切る必要があります。
- 証明書ポリシーの検証モード
-
Validate Certificate Policy設定で複数のポリシーが指定されている場合、要求されたすべてのポリシーが存在するかどうかを照合で確認するか、認証を成功させるには 1 つの照合で十分かを判断します。デフォルト値はAllです。つまり、要求されたポリシーすべてがクライアント証明書に存在する必要があることを意味します。 - Bypass identity confirmation
- 有効にすると、X.509 クライアント証明書認証は、証明書 ID を確認するようにユーザーに要求しません。Red Hat build of Keycloak は、認証が成功するとユーザーをサインインします。
- Revalidate client certificate
- 設定された場合、クライアント証明書のトラストチェーンは、設定されたトラストストアにある証明書を使用して、アプリケーションレベルで常に検証されます。これは、基礎となる Web サーバーがクライアント証明書チェーンの検証を強制しない場合に便利です (非検証のロードバランサーやリバースプロキシーの背後にある場合や、相互 SSL ネゴシエーションについて許可される CA の数が大きすぎる場合など (ほとんどのブラウザーは最大の SSL ネゴシエーションパケットのサイズを 32767 バイトに制限します。これは、約 200 の広告済み CA に対応します)。デフォルトでは、このオプションは無効です。
8.6.4. X.509 クライアント証明書認証の Direct Grant Flow への追加
- メニューで Authentication をクリックします。
- "アクションリスト" から Duplicate を選択して、組み込みの "直接付与" フローのコピーを作成します。
- コピーの名前を入力します。
- 複製 をクリックします。
- 作成したフローをクリックします。
- "ユーザー名の検証" のゴミ箱アイコン 🗑️ をクリックし、Delete をクリックします。
- "パスワード" のゴミ箱アイコン 🗑️ をクリックし、Delete をクリックします。
- Add step をクリックします。
- "X509/Validate Username" をクリックします。
Add をクリックします。
X509 直接付与実行
- x509 ブラウザーフロー セクションで説明されている手順に従って、x509 認証設定をセットアップします。
- Bindings タブをクリックします。
- Direct Grant Flow ドロップダウンリストをクリックします。
- 新規作成された "x509 Direct Grant" フローをクリックします。
Save をクリックします。
X509 直接付与フローバインディング
