4.4.6.2. Kafka ブローカーの OAuth 2.0 サポートの設定

手順

1. エディターで、Kafka リソースの Kafka ブローカー設定 (Kafka.spec.kafka) を更新します。

   oc edit kafka my-cluster

2. Kafka ブローカーの listeners 設定を行います。

   各タイプのリスナーは独立しているため、同じ設定にする必要はありません。

   以下は、外部リスナーに設定された設定オプションの例になります。

   例 1: 高速なローカル JWT トークン検証の設定

   #...
   - name: external
     port: 9094
     type: loadbalancer
     tls: true
     authentication:
       type: oauth 1
       validIssuerUri: <https://<auth-server-address>/auth/realms/external> 2
       jwksEndpointUri: <https://<auth-server-address>/auth/realms/external/protocol/openid-connect/certs> 3
       userNameClaim: preferred_username 4
       maxSecondsWithoutReauthentication: 3600 5
       tlsTrustedCertificates: 6
       - secretName: oauth-server-cert
         certificate: ca.crt
       disableTlsHostnameVerification: true 7
       jwksExpirySeconds: 360 8
       jwksRefreshSeconds: 300 9
       jwksMinRefreshPauseSeconds: 1 10

   1

   oauth に設定されたリスナータイプ。

   2

   認証に使用されるトークン発行者の URI。

   3

   ローカルの JWT 検証に使用される JWKS 証明書エンドポイントの URI。

   4

   トークンの実際のユーザー名が含まれるトークン要求 (またはキー)。ユーザー名は、ユーザーの識別に使用される principal です。userNameClaim の値は、使用される認証フローと承認サーバーによって異なります。

   5

   (任意設定): セッションの有効期限がアクセストークンと同じ期間になるよう強制する Kafka の再認証メカニズムを有効にします。指定された値がアクセストークンの有効期限が切れるまでの残り時間未満の場合、クライアントは実際にトークンの有効期限が切れる前に再認証する必要があります。デフォルトでは、アクセストークンの期限が切れてもセッションは期限切れにならず、クライアントは再認証を試行しません。

   6

   (任意設定): 承認サーバーへの TLS 接続用の信用できる証明書。

   7

   (任意設定): TLS ホスト名の検証を無効にします。デフォルトは false です。

   8

   JWKS 証明書が期限切れになる前に有効であるとみなされる期間。デフォルトは 360 秒です。デフォルトよりも長い時間を指定する場合は、無効になった証明書へのアクセスが許可されるリスクを考慮してください。

   9

   JWKS 証明書を更新する間隔。この間隔は、有効期間よりも 60 秒以上短くする必要があります。デフォルトは 300 秒です。

   10

   JWKS 公開鍵の更新が連続して試行される間隔の最小一時停止時間 (秒単位)。不明な署名キーが検出されると、JWKS キーの更新は、最後に更新を試みてから少なくとも指定された期間は一時停止し、通常の定期スケジュール以外でスケジュールされます。キーの更新は指数バックオフ（指数バックオフ）のルールに従い、jwksRefreshSeconds に到達するまで、一時停止を増やして失敗した更新を再試行します。デフォルト値は 1 です。

   例 2: イントロスペクションエンドポイントを使用したトークンの検証の設定

   - name: external
     port: 9094
     type: loadbalancer
     tls: true
     authentication:
       type: oauth
       validIssuerUri: <https://<auth-server-address>/auth/realms/external>
       introspectionEndpointUri: <https://<auth-server-address>/auth/realms/external/protocol/openid-connect/token/introspect> 1
       clientId: kafka-broker 2
       clientSecret: 3
         secretName: my-cluster-oauth
         key: clientSecret
       userNameClaim: preferred_username 4
       maxSecondsWithoutReauthentication: 3600 5

   1

   トークンイントロスペクションエンドポイントの URI。

   2

   クライアントを識別するためのクライアント ID。

   3

   認証にはクライアントシークレットとクライアント ID が使用されます。

   4

   トークンの実際のユーザー名が含まれるトークン要求 (またはキー)。ユーザー名は、ユーザーの識別に使用される principal です。userNameClaim の値は、使用される承認サーバーによって異なります。

   5

   (任意設定): セッションの有効期限がアクセストークンと同じ期間になるよう強制する Kafka の再認証メカニズムを有効にします。指定された値がアクセストークンの有効期限が切れるまでの残り時間未満の場合、クライアントは実際にトークンの有効期限が切れる前に再認証する必要があります。デフォルトでは、アクセストークンの期限が切れてもセッションは期限切れにならず、クライアントは再認証を試行しません。

   OAuth 2.0 認証の適用方法や、承認サーバーのタイプによっては、追加 (任意) の設定を使用できます。

     # ...
     authentication:
       type: oauth
       # ...
       checkIssuer: false 1
       checkAudience: true 2
       fallbackUserNameClaim: client_id 3
       fallbackUserNamePrefix: client-account- 4
       validTokenType: bearer 5
       userInfoEndpointUri: https://OAUTH-SERVER-ADDRESS/auth/realms/external/protocol/openid-connect/userinfo 6
       enableOauthBearer: false 7
       enablePlain: true 8
       tokenEndpointUri: https://OAUTH-SERVER-ADDRESS/auth/realms/external/protocol/openid-connect/token 9
       customClaimCheck: "@.custom == 'custom-value'" 10
       clientAudience: AUDIENCE 11
       clientScope: SCOPE 12

   1

   承認サーバーが iss クレームを提供しない場合は、発行者チェックを行うことができません。このような場合、checkIssuer を false に設定し、validIssuerUri を指定しないようにします。デフォルトは true です。

   2

   オーソリゼーションサーバーが aud（オーディエンス）クレームを提供していて、オーディエンスチェックを実施したい場合は、checkAudience を true に設定します。オーディエンスチェックによって、トークンの目的の受信者が特定されます。これにより、Kafka ブローカーは aud 要求に clientId を持たないトークンを拒否します。デフォルトは false です。

   3

   承認サーバーは、通常ユーザーとクライアントの両方を識別する単一の属性を提供しない場合があります。クライアントが独自の名前で認証される場合、サーバーによって クライアント ID が提供されることがあります。更新トークンまたはアクセストークンを取得するために、ユーザー名およびパスワードを使用してユーザーが認証される場合、サーバーによってクライアント ID の他に ユーザー名 が提供されることがあります。プライマリーユーザー ID 属性が使用できない場合は、このフォールバックオプションで、使用するユーザー名クレーム (属性) を指定します。

   4

   fallbackUserNameClaim が適用される場合、ユーザー名クレームの値とフォールバックユーザー名クレームの値が競合しないようにする必要もあることがあります。producer というクライアントが存在し、producer という通常ユーザーも存在する場合について考えてみましょう。この 2 つを区別するには、このプロパティーを使用してクライアントのユーザー ID に接頭辞を追加します。

   5

   (introspectionEndpointUri を使用する場合のみ該当): 使用している認証サーバーによっては、イントロスペクションエンドポイントによってトークンタイプ属性が返されるかどうかは分からず、異なる値が含まれることがあります。イントロスペクションエンドポイントからの応答に含まれなければならない有効なトークンタイプ値を指定できます。

   6

   (introspectionEndpointUri を使用する場合のみ該当): イントロスペクションエンドポイントの応答に識別可能な情報が含まれないように、承認サーバーが設定または実装されることがあります。ユーザー ID を取得するには、userinfo エンドポイントの URI をフォールバックとして設定します。userNameClaim、fallbackUserNameClaim、および fallbackUserNamePrefix の設定が userinfo エンドポイントの応答に適用されます。

   7

   これを false に設定してリスナーで OAUTHBEARER メカニズムを無効にします。PLAIN または OAUTHBEARER のいずれかを有効にする必要があります。デフォルトは true です。

   8

   リスナーで PLAIN 認証を有効にするには、true に設定します。これは、すべてのプラットフォームのすべてのクライアントでサポートされています。Kafkaクライアントは、PLAINメカニズムを有効にし、username と password を設定する必要があります。PLAINは、OAuth アクセストークン、または OAuth のclientId と secret（クライアントの認証情報）を使って認証することができます。動作は、tokenEndpointUri が指定されているかどうかによってさらに制御されます。デフォルトは false です。tokenEndpointUri が指定され、クライアントが password を文字列$accessToken:で始まるように設定した場合、サーバーはパスワードをアクセストークンと解釈し、username をアカウントのユーザー名と解釈します。それ以外の場合は、username が clientId、password が client secret と解釈され、ブローカはこれを使ってクライアント名のアクセストークンを取得します。tokenEndpointUri が指定されていない場合、password は常にアクセストークンとして解釈され、ユーザー名は常にアカウント username として解釈されます。これは、トークンから抽出されるプリンシパル ID と一致する必要があります。これは no-client-credentials モードと呼ばれます。クライアントはアクセストークンを常に単独で取得する必要があり、clientId および secret を使用できません。

   9

   前述のように clientId と secret を username と password として渡してクライアントを認証できるようにするためのPLAIN機構の追加設定です。指定のない場合、クライアントはアクセストークンを password パラメーターとして渡すことで PLAIN で認証できます。

   10

   これを JsonPath フィルタークエリーに設定すると、検証中に追加のカスタムルールを JWT アクセストークンに適用できます。アクセストークンに必要なデータが含まれていないと拒否されます。introspectionEndpointUri を使用する場合、カスタムチェックはイントロスペクションエンドポイントの応答 JSON に適用されます。

   11

   （オプション）トークンエンドポイントに渡される audience パラメーター。オーディエンスは、ブローカー間認証用にアクセストークンを取得する場合に使用されます。また、clientId と secret を使った PLAIN クライアント認証の上にある OAuth 2.0 のクライアント名にも使われています。これは、承認サーバーに応じて、トークンの取得機能とトークンの内容のみに影響します。リスナーによるトークン検証ルールには影響しません。

   12

   （オプション） scope パラメーターがトークンエンドポイントに渡されます。スコープは、ブローカー間認証用にアクセストークンを取得する場合に使用されます。また、clientId と secret を使った PLAIN クライアント認証の上にある OAuth 2.0 のクライアント名にも使われています。これは、承認サーバーに応じて、トークンの取得機能とトークンの内容のみに影響します。リスナーによるトークン検証ルールには影響しません。

3. エディターを保存して終了し、ローリングアップデートの完了を待ちます。

4. 更新をログで確認するか、または Pod 状態の遷移を監視して確認します。

   oc logs -f ${POD_NAME} -c ${CONTAINER_NAME}
   oc get pod -w

   ローリングアップデートによって、ブローカーが OAuth 2.0 認証を使用するように設定されます。