JWT で MySQL ユーザーを認証する方法

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →

このガイドはプレビュー機能を使用します。サーバーを --vsql_allow_preview_extensions=ON で起動してください。そうしないと INSTALL EXTENSION は拒否されます。

ID プロバイダーがすでに存在すると、データベースのパスワードは管理しにくくなります。パスワードは別々に発行され、別々にローテーションされ、与えられた人がいなくなった後も残ります。VillageSQL の vsql_oauth2 拡張機能を使うと、アカウントは代わりに JSON Web Token でサインインできます。プロバイダーがトークンを発行し、サーバーが署名と有効期限を検証し、トークン内のクレームがアカウントを指定します。

署名鍵の設定

この拡張機能は、JWKS エンドポイントから取得した鍵（実際のプロバイダーで使う方法）か、貼り付けた 1 つの公開鍵のどちらかで署名を検証します。静的な鍵は、経路全体が動くことを確認する最も手早い方法なので、このガイドはそこから始めます。

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out jwt_private.pem
openssl rsa -pubout -in jwt_private.pem -out jwt_public.pem

INSTALL EXTENSION vsql_oauth2;

SET GLOBAL vsql_oauth2.public_key = '-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----';
SET GLOBAL vsql_oauth2.username_claim = 'sub';

username_claim は、アカウント名を運ぶクレームを指定します。デフォルトは sub で、以下の例のトークンもこれを使います。実際のプロバイダーでは、代わりに jwks_url を設定します。拡張機能は鍵を取得し、jwks_refresh_interval の間隔で再取得し、キャッシュにない鍵 ID をトークンが指定したときには直ちに再取得します。issuer と audience も設定してください。そうすれば、別のシステム向けに発行されたトークンはここでは受け入れられません。

アカウントの作成

アカウントは通常の MySQL アカウントで、作成時にこの拡張機能で認証するものとして指定します。アカウントは自身の権限を持ちます。

CREATE USER 'analyst'@'%' IDENTIFIED WITH vsql_oauth2;
GRANT SELECT ON shop.* TO 'analyst'@'%';

設定するパスワードはなく、ローテーションするパスワードもありません。セッションは、接続したアカウントではなく、トークンが指定するアカウントとして実行されます。その名前は username_claim のクレーム（デフォルトでは sub）から取られます。そのクレームが analyst と言っている限り、上のステートメントで十分です。プロバイダーがそこに別のもの、たとえばメールアドレスを入れる場合は、そのアカウントも作成し、接続するアカウントをそこへプロキシさせます。

CREATE USER 'oidc_user'@'%' IDENTIFIED WITH vsql_oauth2;
CREATE USER 'alice@example.com';
GRANT SELECT ON shop.* TO 'alice@example.com';
GRANT PROXY ON 'alice@example.com' TO 'oidc_user'@'%';

誰も alice@example.com として直接サインインしないため、このアカウントに独自のパスワードは不要です。validate_password を実行しているサーバーは、パスワードのないアカウントの作成を ERROR 1819 (HY000): Your password does not satisfy the current policy requirements で拒否します。それが当てはまる場合は、誰も保持しないパスワードを与えるか、ログインをまったく許可しない認証プラグインを与えてください。プロキシの付与がないと、ログインは ERROR 6126 (HY000): Access denied for user 'oidc_user'@'localhost', missing proxy privilege. で拒否されます。

トークンを --password= で渡すとプロセス一覧に載るため、トークンは代わりに環境変数に入れます。セッション内では、CURRENT_USER() がデータベースのアカウントで、@@external_user はトークンが運んだ ID を保持します。これは監査証跡で求められるものです。

SELECT CURRENT_USER() AS logged_in_as, @@external_user AS token_identity;

+--------------+----------------+
| logged_in_as | token_identity |
+--------------+----------------+
| analyst@%    | analyst        |
+--------------+----------------+

mysql_clear_password はプロトコルレベルでトークンを平文で送信します。この方法で認証するすべての接続で TLS を使ってください。そうしないと、経路上のあらゆるものがトークンを読め、有効期限が切れるまで再利用できます。

トークンからのロールのマッピング

アカウントは、トークンから権限を受け取ることもできます。ロールを運ぶクレームを拡張機能に指定し、付与を有効にします。

SET GLOBAL vsql_oauth2.roles_claim = 'roles';
SET GLOBAL vsql_oauth2.auto_grant = ON;

ロールと、独自の権限を持たないアカウントを作成します。

CREATE ROLE 'shop_reader';
GRANT SELECT ON shop.* TO 'shop_reader';

CREATE USER 'dana'@'%' IDENTIFIED WITH vsql_oauth2;

"roles": ["shop_reader"] を運ぶトークンは、そのロールが有効な状態でログインします。

SELECT CURRENT_USER() AS account, CURRENT_ROLE() AS roles_now;

+---------+-------------------+
| account | roles_now         |
+---------+-------------------+
| dana@%  | `shop_reader`@`%` |
+---------+-------------------+

roles_filter は考慮されるロール名を絞り込み、roles_transform_pattern と roles_transform_replacement は、グループ名がロール名のように見えないプロバイダーのために、プロバイダー側の名前をデータベースのロール名に書き換えます。

auto_grant は実際の付与を書き込み、それはログインの後も残ります。上のログインの後、付与はサーバー内にあります。

SELECT FROM_USER AS role_granted, TO_USER AS to_account
FROM mysql.role_edges WHERE TO_USER = 'dana';

+--------------+------------+
| role_granted | to_account |
+--------------+------------+
| shop_reader  | dana       |
+--------------+------------+

後で auto_grant をオフにしても、付与は取り消されません。一度見た 1 つのトークンが、誰かがロールを取り消すまでそのアカウントの権限を広げます。有効にする前に roles_filter の範囲を絞り、このクレームは、プロバイダーが正しく設定すると信頼するほかないものとして扱ってください。

auto_grant がオフの場合、同じトークンでログインはできますが、ロールは付与されずにスキップされ、CURRENT_ROLE() は NONE になります。スキップされた各ロールはエラーログに書き込まれます: VEF auth: role 'shop_reader'@'%' requested for account 'dana'@'%' is not granted; skipping。auto_create はアカウントについて同じように動作し、サーバーが見たことのないサブジェクトの初回ログイン時にアカウントを作成します。どちらもデフォルトではオフで、どちらもこのサーバーに対する権限をプロバイダーに委ねます。

拒否されたトークンはパスワード間違いのように見える

すべての失敗は 1 つのエラーを生み、それは通常のエラーです。

ERROR 1045 (28000): Access denied for user 'analyst'@'localhost' (using password: NO)

期限切れのトークン、誤った鍵で署名されたトークン、間違って入力された通常のパスワードは、すべてまったく同じこのエラーを生みます。using password: NO も含めてです。トークンは送られているので、これは誤解を招きます。サーバーのエラーログにも、log_error_verbosity=3 であっても、区別できるものは何も出ません。そのため、エラーではなくトークンからデバッグしてください。トークンをデコードし、次の 4 点をこの順に確認します。

exp が未来である。プロバイダーとサーバーの間のクロックのずれがここで影響します。
署名鍵が一致する。 トークンの kid が、JWKS ドキュメントがまだ公開しているものであることを確認します。ドキュメントがもう持っていない鍵は、偽造トークンとまったく同じに見えます。
iss と aud が、設定した場合はその設定値と一致する。
username_claim のクレームが存在するアカウントを指定している。アカウントの綴りどおりに。

ペイロードのデコードには、シェル以外のツールは不要です。

echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null

トラブルシューティング

症状	修正
インストール時に `ERROR 3219 ... requires preview capabilities`	サーバーを `--vsql_allow_preview_extensions=ON` で起動します
すべての試行で `Access denied`	上の 4 つの確認を順に行います。メッセージはどの原因でも同じです
クライアントがトークンを送らない	`--enable-cleartext-plugin` を渡します。他のクライアントには、`mysql_clear_password` 用の独自の有効化手段があります
ログインが動いていたのに、まとめて止まった	プロバイダーが鍵をローテーションしました。`jwks_url` に到達でき、トークンの `kid` が返されるドキュメントに含まれることを確認します
誰も付与していない権限をアカウントが持っている	`auto_grant` がトークンのクレームから付与しました。`mysql.role_edges` を確認し、取り消します
拡張機能の再インストール後に設定が消えた	`UNINSTALL EXTENSION` は永続化された設定を削除します。再適用します

MySQL Tutorial

ガイド

データの保存

クエリの作成

データの保護

パフォーマンスの最適化

AI で構築する

MySQL の運用

アプリケーションの接続

拡張機能の作成

VillageSQL is a drop-in replacement for MySQL with extensions.

署名鍵の設定

アカウントの作成

ログイン

トークンからのロールのマッピング

拒否されたトークンはパスワード間違いのように見える

トラブルシューティング

関連項目