メインコンテンツへスキップ
このページの機能はプレビュー段階です。API は安定しておらず、これらの機能を宣言する拡張機能は、vsql_allow_preview_extensions = ON が設定されている場合にのみインストールできます。プレビュー層の有効化と機能の登録方法については、プレビュー機能を参照してください。 auth 機能(vsql::preview::auth)は、拡張機能がサーバーの認証方式を提供できるようにします。アカウントは CREATE USER ... IDENTIFIED WITH <method-name> でこれを選択します。接続時に、その名前がロード済みの MySQL 認証プラグインでない場合、サーバーは VEF 認証レジストリを参照し、ハンドシェイクを通じて拡張機能のハンドラを呼び出します。MySQL 認証プラグインを書かずに、サーバーが知らない認証情報ソース — ベアラートークン、外部 ID プロバイダー、カスタムチャレンジなど — に対してアカウントを認証する場合に使用します。 機能名 VEF_PREVIEW_AUTH_NAME は "vsql::preview::auth" です。 ハンドラは AuthContext を受け取る型付き関数です。サーバー所有のそのコンテキストを介してハンドシェイクパケットを読み書きすることでクライアントと通信し、MySQL の内部認証構造体を参照することはありません。
認証結果はフェイルクローズです。サーバーは AuthResult::kOk 以外のすべてを接続拒否として扱います — 「たぶん」やフェイルオープンの結果は意図的に存在しません。AuthResult::kReject を返すハンドラ、AuthResult::kError を返すハンドラ、または実効アカウントを設定しないハンドラは、ログインを拒否します。

機能の宣言

ヘッダーを含め、型付きハンドラを記述し、make_auth<> ビルダーのチェーン呼び出しで記述子を構築し、その記述子を .with() に渡す AuthCapability トークンに渡します。プレビュー機能のヘッダーは <villagesql/vsql.h> のアンブレラには含まれないため、<villagesql/preview/auth.h> を明示的に含めてください:
ビルダーは6つの要素で構成されます: AuthCapability g_auth{descriptor} は .with() が消費する自己登録トークンです。登録より長く存続するように static として宣言してください。 client_plugin はオプションです。make_auth は通知するプラグインを既定で "mysql_clear_password" — すべての MySQL クライアントが同梱する最も基本的なプラグイン — に設定します。そのため .client_plugin() を一度も呼び出さない方式でもインストールでき、単純なクライアントでも接続できます。別のプラグインを要求するには .client_plugin(name) を呼び出します。mysql_clear_password はパスワードスロットでベアラートークンをそのまま受け取ります。 方式が要求するものとは別のプラグインを提示するクライアントは、要求されたプラグインに切り替えられ、認証情報をそのまま再送します。これには1往復のコストがかかり、その切り替えに応じるクライアントが必要です。.accepts_client_plugin(&callback) を使うと、方式は提示されたプラグインをそのまま維持できます。サーバーは提示された各名前をコールバックに渡します。要求されたプラグインも渡されますが、これはコールバックの戻り値にかかわらず受け入れられます。コールバックを設定しない方式は他の提示を一切受け入れないため、他のすべての提示は要求されたプラグインに切り替わります。受け入れは最終的です — サーバーはその後で要求されたプラグインに切り替え直しません — したがって、ハンドラが実際にフレーミングを解析できるプラグインだけを受け入れてください。サーバーはハンドシェイクのネゴシエーション中、ハンドラの最初の読み取りより前にコールバックを呼び出すため、コールバックは純粋な述語でなければなりません:パケット I/O、ブロッキング、副作用のいずれも行わないでください。

ハンドラの契約

ハンドラは AuthHandler 型に一致します — AuthContext & を取り、AuthResult を返します:
ハンドラは、ハンドシェイク中に接続スレッド上で同期的に呼び出されます。AuthContext は、サーバー所有の試行ごとのコンテキストをラップします。呼び出しの実行中のみ保持し、保存しないでください。関数テーブルを通じてコンテキストポインタを引き回す代わりに、そのメソッドを呼び出してください。トークンベースのハンドラが使用するメソッド: ハンドラは3つの結果のいずれかを返します: AuthResult::kReject と AuthResult::kError はどちらも接続を拒否します。成功するのは AuthResult::kOk のみです。 ハンドラが接続アカウントを別の実効アカウントにマッピングする場合 — 以下の例が接続アカウントを vsql_auth_test_user にマッピングするように — それはプロキシであり、MySQL のプラグイン認証の経路とまったく同じように GRANT PROXY が必要です。

アクティブロールのステージング

c.set_active_roles(roles, n_roles) は、このログインにおいてアカウントのデフォルトロールの有効化に代えて、セッションでアクティブにすべきロールをステージングします。roles は n_roles 個の NUL 終端名の配列です。文字列はコピーされるため、呼び出し側が保持し続ける必要はありません。サーバーはアカウント解決の後に、SET ROLE と同じ付与チェック付きの有効化を使用してそれらを適用します。実際に認証済みアカウントに付与されているロールのみが有効になり、付与されていない名前は黙ってスキップされます — したがって、方式が .roles_mode() を設定しない限り、トークンが DBA の用意した範囲を超えて権限を付与したり昇格させたりすることはできません。n_roles == 0 を渡すとロールは有効になりません(SET ROLE NONE と同等)。

完全な例

サーバーソースツリーの villagesql/test-extensions/vsql-auth-test/ にある vsql_auth_test 拡張機能を凝縮した、最小限の認証機能です。この拡張機能はどのリリースにも含まれていません。固定のトークンを1つ受け入れ、接続を vsql_auth_test_user にマッピングし、トークンがパスワードスロットにそのまま届くように mysql_clear_password を要求します。(ツリー内の拡張機能は、テストスイートを動かすために追加のトークン経路、.accepts_client_plugin() コールバック、および以下で説明する2つのオプトインを備えています。)

アカウントのバインドと接続

プレビュー層を有効化した上で(プレビュー層の有効化を参照)、拡張機能をビルドし、その .veb ファイルを veb_dir にコピーしてインストールし、アカウントをこの方式にバインドします。ハンドラは2つ目のアカウントにマッピングするため、そのアカウントも作成し、接続アカウントがその ID を引き継げるようにする PROXY 権限を付与します:
vsql_auth_test は登録済みの VEF 認証方式であるため、CREATE USER ... IDENTIFIED WITH vsql_auth_test は受け入れられます — インストール済みのプラグイン名が受け入れられるのと同じ仕組みです。 受け入れられるのは IDENTIFIED WITH <method> の形式のみで、オプションで AS '...' を付けられます。BY '...' を追加すると、パスワードを保存用の認証情報に変換することを方式に要求することになります — MySQL のプラグインが generate_authentication_string() を通じて行う処理です — が、現在そのフックを宣言する VEF 認証方式はないため、サーバーはこれを拒否します:
バインドされた方式名は、テーブルのデフォルトではなくアカウントの plugin カラムに書き込まれます。これがアカウントの次回ログイン時に読み取られる値です:
この方式は mysql_clear_password を要求するため、クライアントはトークンを平文で送信するために --enable-cleartext-plugin を渡す必要があります。トークンが正しい場合、セッションはマッピングされたアカウントとして実行され、接続アカウントを @@external_user を通じて公開します:
拡張機能をアンインストールすると方式が削除されます。それにバインドされたアカウントは認証できなくなります:

アカウントの自動作成

方式は、まだ存在しないアカウントのログインを処理し、ログイン成功の一部としてサーバーにそのアカウントを作成させることもできます。これがない場合、未知のアカウントはどの方式が実行されるよりも前に拒否されます。 .auto_create(&callback) でオプトインします。コールバックは引数を取らず bool を返します。サーバーは登録時に一度読み取るのではなく、未知のアカウントによるログインのたびにこれを呼び出します。そのため方式は、拡張機能のロード時に選択を固定するのではなく、自身の実行時設定に従うことができます:
.auto_create() を付けない場合、またはコールバックが false を返す場合、標準の動作が維持されます:未知のアカウントは拒否されます。同時にオプトインできるインストール済みの方式は1つだけです — 2つが true を返した場合、サーバーは推測を行わず、エラーログに警告を記録し、どの方式もオプトインしていない場合と同じように未知のアカウントを拒否します。 ハンドラ内では、c.account_unknown() が2つのケースを区別します。まず認証情報を検証し、次に何を作成するかを指定して、そのアカウントとして認証します:
request_provision(account, roles, n_roles) は意図を記録するだけで、何も返しません。サーバーは、ハンドラが AuthResult::kOk を返した後に DDL を自身で実行します。実行するのは、未知のアカウントとしてルーティングされたログインの場合のみです — そのため、ハンドラがその後で拒否するログインは何も作成せず、すでに存在するアカウントを指定した要求では、そのアカウントのバインディングは保持され、指定されたロールは付与されます。サーバーが実行するのは CREATE USER IF NOT EXISTS <account>@'%' IDENTIFIED WITH <method> で、続いて指定されたロールごとに1つの GRANT を実行します。アカウントは常にホスト % に対して作成され、認証を行った方式にバインドされます。また account は接続ユーザー名である必要はありません。作成ができない場合 — 例えば super_read_only のサーバーでは — アカウントなしで処理を続行するのではなく、ログインが失敗します。 サーバーは、自動的な CREATE USER、その GRANT、およびロールを調整する GRANT と REVOKE をバイナリログに書き込みません。レプリケーショントポロジー内の各サーバーが、それぞれ自身でアカウントを作成し、ロールを調整します。 ロールの扱いはアクティブロールのステージングと同じです:ロールは DBA が管理します。各名前は付与可能なロールとしてすでに存在している必要があり、付与できないものはログインを失敗させるのではなくログに記録されてスキップされます。そのためトークンはロールを指定できますが、ロールを作成したり昇格させたりすることはできません。アカウント名はクライアントから渡されるため、サーバーはそれを識別子として引用符で囲みます — 細工された名前は奇妙な名前のアカウント1つになるだけで、2つ目の文になることはありません。 vsql_auth_test 拡張機能は、接続ユーザーにロール vsql_role_granted を付与してプロビジョニングし、オプトインを vsql_auth_test.auto_create で制御します。この変数の初期値は OFF です。まずこれをオンにしてロールを作成し、その後で存在しないアカウントとして接続します:
アカウントが作成され、方式にバインドされ、付与されたロールを保持しています:
誤ったトークンは引き続きフェイルクローズで失敗し、何もプロビジョニングしません:
オプトインすると、未知のアカウントと既存のアカウントの違いが観測可能になります。標準の未知アカウント拒否は、この違いを意図的に隠しています。未知のアカウントに対して拒否されたログインは (using password: NO) を報告し、通常のパスワードを持つアカウントに対して拒否されたログインは (using password: YES) を報告し、有効な認証情報はアカウントを作成します。これがこの機能のトレードオフです。認証情報が広く共有されている方式でオプトインを有効にする前に、この点を検討してください。

ロールの自動付与

既定では、トークンが指定したロールは、アカウントがすでにそれを保持している場合にのみ有効になります。保持していないものはスキップされ、サーバーはその理由をログに記録します(VEF auth: role '<role>'@'<host>' requested for account '<user>'@'<host>' is not granted; skipping)。.roles_mode(&callback) はこれを変更します:コールバックは vef_auth_roles_mode_t — VEF_AUTH_ROLES_ACTIVATE(既定)、VEF_AUTH_ROLES_GRANT、または VEF_AUTH_ROLES_SYNC — を返し、サーバーはログインのたびに、ステージングされたロールをアカウントに付与済みのロールとそれに応じて調整します。 コールバックの形は .auto_create() と同じです — 引数を取りません — が、bool の代わりにモードの enum を返し、サーバーはログインのたびにこれを呼び出し、その裏付けとなるものをライブで読み取ります:
2つのオプトインは、ログインの異なる時点で実行されます。.auto_create() は、まだ存在しないアカウントのログインにアカウントのプロビジョニングを許可するかどうかを決定します。.roles_mode() はその後に、ログインが解決したアカウント — 今プロビジョニングされたアカウント、またはすでに存在していたアカウント — に対して実行されるため、どちらの場合も同じ調整が適用されます。VEF_AUTH_ROLES_ACTIVATE、またはコールバックをまったく付けない場合、有効化のみを行う既定の動作が維持されます。 VEF_AUTH_ROLES_GRANT は加算的です:アカウントが持たないステージング済みロールを付与し、取り消しのステップをまったく実行しません。VEF_AUTH_ROLES_SYNC はそのステップを実行します:トークンが主張しなかった付与済みロールをすべて取り消すため、トークンから外されたロールは、次回のログイン時にアカウントからも外されます — ただし、オペレーターの ALTER USER によってアカウントの DEFAULT ROLE として設定されたロールは例外で、SYNC はこれを決して取り消しません。どちらのモードでも、DB ロールとして存在しないステージング済みロールは GRANT に失敗し、ログインを失敗させるのではなく、ログに記録されてスキップされます。 vsql_auth_test はこれを vsql_auth_test.auto_grant として公開します。これは OFF/ON/SYNC の enum で(初期値も OFF)、そのインデックス順は上記のモード順と一致します。この拡張機能の -token-roles トークンは vsql_role_granted と vsql_role_denied をステージングしますが、以下のアカウントはどちらも保持していません。設定がオフの場合、ログインはアカウントのロールをそのままにします:
上記と同じ方法で、パスワード vsql-auth-test-token-roles を使って auth_user として接続し、SELECT CURRENT_ROLE() で何が有効かを確認します:
設定をオンにして、同じログインを繰り返します:
両方のロールが有効になり、SHOW GRANTS はサーバーが追加した付与を表示します:
vsql_auth_test.auto_grant が ON または SYNC に設定されている場合、有効なトークンがあれば、それが指定するどのロールも取得できます。DB ロールとしてまだ存在しないロールは GRANT に失敗してスキップされるため、トークンが作成されたことのないロールを作り出すことは依然としてできませんが、存在するロールのうちアカウントがどれに到達できるかを決めるのは DBA ではなく認証方式になります。SYNC はさらに踏み込みます:DBA が帯域外で付与したがトークンが決して主張しないロールも、アカウントの次回ログイン時に取り消します — オペレーターは、そのロールをアカウントの DEFAULT ROLE として設定することで、1つのロールをそれから守ることができます。SYNC はこれに手を付けません。vsql_auth_test_user から取り消されたロールは、すでにそれを有効化したセッションからは消えません:取り消しの後に同じセッションで CURRENT_ROLE() を再度問い合わせても、そのロールは引き続き一覧に表示されます。