JWT 認証の設定

ClickHouse Cloud では、独自の JSON Web Key Set (JWKS) エンドポイントに対して検証された JSON Web Token (JWT) を使用して、サービスへの接続を認証できます。データベース認証情報を管理する代わりに、アイデンティティプロバイダが短期間有効なトークンを発行し、ClickHouse は設定した JWKS URL で公開されている公開鍵を使用してそのトークンを検証します。

ClickHouse Cloud Console の Settings → Security から、サービスごとにこれらの JWKS プロバイダを設定できます。

サービスの JWT プロバイダを設定するには、次の要件を満たす必要があります。

• Enterprise プランの組織。
• ClickHouse バージョン 26.4 以降を実行しているサービス。
• サービスに対する control-plane:service:manage 権限を持つロール (例: Admin または Service admin) 。この権限を持たないメンバーには、このセクションは閲覧専用として表示されます。
• 少なくとも 1 つの RSA 鍵 (RS256) 、またはバージョン 26.8 以降のサービスでは EC 鍵 (ES256、ES384、ES512) をパブリッシュする、パブリックから到達可能な HTTPS JWKS URL。

クライアント (アイデンティティプロバイダまたはアプリケーション) は JWT を生成し、秘密鍵で署名します。トークンは、想定されるトークン形式に従う必要があります。ClickHouse は、JWKS URL で公開されている公開鍵を使用してトークンを検証します。

1. ClickHouse はトークンの kid (鍵 ID) ヘッダーを読み取り、JWKS ドキュメントから一致する鍵を選択します。
2. その公開鍵を使用してトークンの署名を検証し、iss (発行者) および aud (オーディエンス) クレーム をプロバイダー設定と照合します。
3. 検証に成功すると、接続は一時ユーザーとして実行されます。アクセス権はトークンの clickhouse:grants および clickhouse:roles クレーム から取得され、権限上限 (default ユーザー) によって制限されます。詳細はアクセス権を参照してください。

ClickHouse はプロバイダーの追加または更新時に JWKS URL を検証して取得するため、設定が不適切な URL や到達できない URL は事前に拒否されます。

サービスのセキュリティ設定を開く

サービスに移動し、Settings を開いて Security セクションまでスクロールします。JWT 認証 カードを見つけます。

プロバイダのフライアウトを開く

Set up JWT providers を選択します (既存のプロバイダがある場合は Manage JWT providers) 。フライアウトが開き、新しいプロバイダのフォームが表示されます。

プロバイダの詳細を入力する

プロバイダのフォームに入力し、Save を選択します。

フィールド	説明
Name	このサービス上で一意となるプロバイダ名です。作成後は変更できません。
Issuer	受信トークンに期待される iss クレーム。
Audience	受信トークンに期待される aud クレーム。
JWKS URL	トークン署名の検証に使用する公開鍵を公開する HTTPS 公開 URL。
Roles claim (任意)	ClickHouse ロールの取得元となるトークン クレーム。デフォルトの クレーム 名 clickhouse:roles を使用する場合は空欄のままにします。トークンで指定するロールは、あらかじめサービス上に存在している必要があります。

必要に応じてプロバイダを追加する

追加のプロバイダを設定するには、Add another provider を使用します。1 つのサービスには、最大 5 つの JWT プロバイダを設定できます。

• 1サービスあたり最大5つのJWTプロバイダを設定できます。
• JWKSプロバイダでは、RSA 鍵 (RS256) に加え、バージョン26.8以降は EC 鍵 (ES256、ES384、ES512) も使用できます。
• JWKS URLはPublic HTTPSエンドポイントである必要があります。Private、内部、またはリンクローカルアドレスは拒否されます。

• JWT Authentication — トークンのクレーム、一時ユーザー、クライアントの使用方法。