vsql_allow_preview_extensions = ON to install. See Preview Capabilities for how to enable the preview tier and register a capability.
The auth capability (vsql::preview::auth) lets an extension provide a server
authentication method. An account opts in with CREATE USER ... IDENTIFIED WITH <method-name>; at connection time, when that name is not a loaded MySQL auth
plugin, the server consults the VEF auth registry and invokes the extension’s
handler over the handshake. Use it to authenticate accounts against a credential
source the server does not know about — a bearer token, an external identity
provider, or a custom challenge — without writing a MySQL authentication plugin.
The capability name VEF_PREVIEW_AUTH_NAME is "vsql::preview::auth".
The handler is a typed function that receives an AuthContext: it talks to the
client by reading and writing handshake packets through that server-owned
context, and it never sees MySQL’s internal auth structures.
Declaring the Capability
Include the header, write a typed handler, build a descriptor with the fluentmake_auth<> builder, and hand the descriptor to an AuthCapability token that
you pass to .with(). Preview capability headers are not part of the
<villagesql/vsql.h> umbrella, so include <villagesql/preview/auth.h>
explicitly:
AuthCapability g_auth{descriptor} is the self-registering token consumed by
.with(). Declare it static so it outlives registration.
client_plugin is optional. make_auth defaults the advertised plugin to
"mysql_clear_password" — the lowest common denominator every MySQL client
ships — so a method that never calls .client_plugin() still installs and a
naive client still connects. Call .client_plugin(name) to request a different
plugin; mysql_clear_password receives a bearer token verbatim in the password
slot.
A client that offers a plugin other than the one the method requests is switched
to the requested plugin and resends its credential verbatim, which costs a round
trip and needs a client willing to make that switch.
.accepts_client_plugin(&callback) lets the method keep the offered plugin
instead: the server passes each offered name to the callback, including the
requested plugin, which is accepted whatever the callback returns. A method that
sets no callback accepts no other offer, so every other offer switches to the
requested plugin. Accepting is final — the server does not switch back to the
requested plugin afterwards — so accept only a plugin whose framing the handler
really parses. The server queries the callback during handshake negotiation,
before the handler’s first read, so it must be a pure predicate: no packet I/O,
no blocking, no side effects.
The Handler Contract
The handler matches theAuthHandler type — it takes an AuthContext & and
returns an AuthResult:
AuthContext wraps the server-owned per-attempt context; hold it only for the
duration of the call and do not retain it. Call its methods instead of threading
a context pointer through a function table. The methods a token-based handler
uses:
The handler returns one of three results:
Both
AuthResult::kReject and AuthResult::kError deny the connection. Only
AuthResult::kOk succeeds.
When the handler maps the connecting account to a different effective account —
as the example below maps the connecting account to vsql_auth_test_user — that
is proxying, and it requires a GRANT PROXY, exactly as on the MySQL plugin auth
path.
Staging Active Roles
c.set_active_roles(roles, n_roles) stages the roles that should be active on
the session, replacing the account’s default-role activation for this login.
roles is an array of n_roles NUL-terminated names; the strings are copied,
so the caller need not keep them. The server applies them after account
resolution, using the same grant-checked activation as SET ROLE: only roles
actually granted to the authenticated account activate, and names that are not
granted are silently skipped — so, unless the method sets .roles_mode(), a token
cannot grant or escalate privileges beyond what the DBA provisioned. Passing n_roles == 0 activates no roles
(equivalent to SET ROLE NONE).
Complete Example
A minimal authenticator, condensed from thevsql_auth_test extension in the
server source tree at villagesql/test-extensions/vsql-auth-test/, which no
release includes. It accepts one fixed token, maps the connection to
vsql_auth_test_user, and requests mysql_clear_password so the token arrives
verbatim in the password slot. (The in-tree extension adds extra token paths, an
.accepts_client_plugin() callback, and both opt-ins described below to drive
its test suite.)
Binding an Account and Connecting
With the preview tier enabled (see Enabling the Preview Tier), build the extension, copy its.veb file into veb_dir, install it, and bind an
account to the method. Because the handler maps to a second account,
create that account too and grant it the PROXY privilege that lets the
connecting account assume its identity:
CREATE USER ... IDENTIFIED WITH vsql_auth_test is accepted because
vsql_auth_test is a registered VEF auth method — the same way an installed
plugin name is accepted.
Only the IDENTIFIED WITH <method> form is accepted, optionally with
AS '...'. Adding BY '...' asks the method to turn a password into a stored
credential — the job a MySQL plugin does through
generate_authentication_string() — and no VEF auth method declares that hook
today, so the server rejects it:
plugin column rather than
the table default, which is what the account’s next login reads:
mysql_clear_password, so the client must pass
--enable-cleartext-plugin to send the token in cleartext. On a correct token,
the session runs as the mapped account and exposes the connecting account
through @@external_user:
Auto-Creating Accounts
A method can also handle logins for accounts that do not exist yet, and have the server create the account as part of the successful login. Without this, an unknown account is rejected before any method runs. Opt in with.auto_create(&callback). The callback takes no arguments and
returns bool; the server calls it on each unknown-account login rather than
reading it once at registration, so the method can follow a runtime setting of
its own instead of freezing the choice when the extension loads:
.auto_create() off, or returning false from the callback, keeps the
standard behavior: an unknown account is denied. Only one installed method may
opt in at a time — if two return true, the server declines to guess, logs a
warning to the error log, and rejects unknown accounts as if none had opted in.
In the handler, c.account_unknown() distinguishes the two cases. Validate the
credential first, then describe what to create and authenticate as it:
request_provision(account, roles, n_roles) records intent and returns nothing.
The server runs the DDL itself, after the handler returns AuthResult::kOk, and
only for a login that was routed in as an unknown account — so a login the
handler goes on to deny creates nothing, and when a request names an account that
already exists, the account keeps its binding and still receives the named roles. What the server runs is
CREATE USER IF NOT EXISTS <account>@'%' IDENTIFIED WITH <method>, followed by
one GRANT per named role: the account is always created for host % and bound
to the method that authenticated it, and account need not be the connecting
user name. If the creation cannot be done — on a super_read_only server, for
example — the login fails rather than proceeding without an account.
The server does not write the automatic CREATE USER, its GRANTs, or the role reconciliation GRANTs and REVOKEs to the binary log. Each server in a replication topology creates and reconciles the account for itself.
Roles behave as they do for Staging Active Roles: the
DBA owns them. Each name must already exist as a grantable role, and one that
cannot be granted is logged and skipped rather than failing the login, so a
token can name a role but never create or escalate one. The account name comes
from the client, so the server quotes it as an identifier — a crafted name
becomes one oddly-named account, never a second statement.
The vsql_auth_test extension provisions the connecting user with the role
vsql_role_granted, and gates the opt-in behind vsql_auth_test.auto_create,
which starts OFF. Turn it on and create the role first, then connect as an
account that does not exist:
Auto-Granting Roles
By default a role a token names takes effect only if the account already holds it; one it does not hold is skipped, and the server logs why (VEF auth: role '<role>'@'<host>' requested for account '<user>'@'<host>' is not granted; skipping). .roles_mode(&callback) changes that: the callback returns a
vef_auth_roles_mode_t — VEF_AUTH_ROLES_ACTIVATE (the default),
VEF_AUTH_ROLES_GRANT, or VEF_AUTH_ROLES_SYNC — and the server reconciles
the staged roles with the account’s granted roles accordingly on each login.
The callback matches .auto_create() in shape — no arguments — but returns the
mode enum instead of a bool, and the server calls it on each login, reading
whatever backs it live:
.auto_create() decides
whether a login for an account that does not yet exist is allowed to provision
one; .roles_mode() runs afterward, against whatever account the login
resolved to — the one just provisioned or one that already existed — so the
same reconciliation applies either way. VEF_AUTH_ROLES_ACTIVATE, or no
callback at all, keeps the activate-only default.
VEF_AUTH_ROLES_GRANT is additive: it grants a staged role the account lacks,
and never runs the revoke step at all. VEF_AUTH_ROLES_SYNC runs that step:
it revokes every granted role the token did not claim, so a role dropped from
the token is dropped from the account too on the next login — except a role
set as the account’s DEFAULT ROLE by an operator’s ALTER USER, which SYNC
never revokes. Under either mode, a staged role that does not exist as a DB
role fails its GRANT and is logged and skipped rather than failing the
login.
vsql_auth_test exposes this as vsql_auth_test.auto_grant, an OFF/ON/SYNC
enum (also OFF to start) whose index order matches the mode order above. Its
-token-roles token stages vsql_role_granted and vsql_role_denied, and the
account below holds neither. With the setting off, the login leaves the
account’s roles alone:
auth_user with the password vsql-auth-test-token-roles, in the same way as above, and
ask what is active with SELECT CURRENT_ROLE():
SHOW GRANTS shows the grant the server added: