vsql_allow_preview_extensions = ON para instalar. Consulte Capabilities Preview para saber como habilitar o nível Preview e registrar uma capability.
A capability auth (vsql::preview::auth) permite que uma extensão forneça um
método de autenticação do servidor. Uma conta opta por ele com
CREATE USER ... IDENTIFIED WITH <method-name>; no momento da conexão, quando
esse nome não é um plugin de autenticação do MySQL carregado, o servidor consulta
o registro de autenticação do VEF e invoca o handler da extensão sobre o
handshake. Use-o para autenticar contas contra uma fonte de credenciais que o
servidor não conhece — um token de portador, um provedor de identidade externo ou
um desafio personalizado — sem escrever um plugin de autenticação do MySQL.
O nome da capability VEF_PREVIEW_AUTH_NAME é "vsql::preview::auth".
O handler é uma função tipada que recebe um AuthContext: ele conversa com o
cliente lendo e escrevendo pacotes do handshake através desse contexto de
propriedade do servidor, e nunca vê as estruturas internas de autenticação do
MySQL.
Declarando a Capability
Inclua o cabeçalho, escreva um handler tipado, construa um descritor com o construtor fluentemake_auth<> e entregue o descritor a um token
AuthCapability que você passa para .with(). Os cabeçalhos das capabilities
Preview não fazem parte do guarda-chuva <villagesql/vsql.h>, então inclua
<villagesql/preview/auth.h> explicitamente:
AuthCapability g_auth{descriptor} é o token autorregistrável consumido por
.with(). Declare-o static para que ele sobreviva ao registro.
client_plugin é opcional. make_auth define o plugin anunciado por padrão como
"mysql_clear_password" — o menor denominador comum que todo cliente MySQL traz
— então um método que nunca chama .client_plugin() ainda instala e um cliente
ingênuo ainda se conecta. Chame .client_plugin(name) para pedir um plugin
diferente; o mysql_clear_password recebe um token de portador literalmente no
campo da senha.
Um cliente que oferece um plugin diferente daquele que o método pede é trocado
para o plugin pedido e reenvia sua credencial literalmente, o que custa um
round trip e exige um cliente disposto a fazer essa troca.
.accepts_client_plugin(&callback) permite que o método mantenha o plugin
oferecido: o servidor passa cada nome oferecido ao callback, incluindo o plugin
pedido, que é aceito independentemente do que o callback retornar. Um método que
não define nenhum callback não aceita nenhuma outra oferta, então toda outra
oferta é trocada pelo plugin pedido. Aceitar é definitivo — o servidor não volta
depois para o plugin pedido — então aceite apenas um plugin cujo formato o
handler realmente entenda. O servidor consulta o callback durante a negociação do
handshake, antes da primeira leitura do handler, então ele deve ser um predicado
puro: sem E/S de pacotes, sem bloqueio, sem efeitos colaterais.
O Contrato do Handler
O handler corresponde ao tipoAuthHandler — ele recebe um AuthContext & e
retorna um AuthResult:
AuthContext envolve o contexto por tentativa de propriedade do servidor;
mantenha-o apenas durante a chamada e não o retenha. Chame seus métodos em vez de
encadear um pointer de contexto por uma tabela de funções. Os métodos que um
handler baseado em token usa:
O handler retorna um de três resultados:
Tanto
AuthResult::kReject quanto AuthResult::kError negam a conexão. Somente
AuthResult::kOk tem sucesso.
Quando o handler mapeia a conta que está se conectando para uma conta efetiva
diferente — como o exemplo abaixo mapeia a conta que se conecta para
vsql_auth_test_user — isso é proxying, e requer um GRANT PROXY, exatamente
como no caminho de autenticação por plugin do MySQL.
Preparando Papéis Ativos
c.set_active_roles(roles, n_roles) prepara os papéis que devem estar ativos na
sessão, substituindo a ativação de papéis padrão da conta neste login. roles é
um array de n_roles nomes terminados em NUL; as strings são copiadas, então
quem chama não precisa mantê-las. O servidor as aplica depois da resolução da
conta, usando a mesma ativação com verificação de concessão do SET ROLE: apenas
papéis realmente concedidos à conta autenticada são ativados, e nomes que não
foram concedidos são ignorados silenciosamente — de modo que, a menos que o
método defina .roles_mode(), um token não pode conceder ou escalar privilégios
além do que o DBA provisionou. Passar n_roles == 0 não ativa nenhum papel
(equivalente a SET ROLE NONE).
Exemplo Completo
Um autenticador mínimo, condensado a partir da extensãovsql_auth_test na
árvore de código-fonte do servidor em
villagesql/test-extensions/vsql-auth-test/, que nenhum release inclui. Ele
aceita um token fixo, mapeia a conexão para vsql_auth_test_user e pede
mysql_clear_password para que o token chegue literalmente no campo da senha. (A
extensão interna à árvore adiciona caminhos de token extras, um callback
.accepts_client_plugin() e as duas adesões descritas abaixo para conduzir a sua
suíte de testes.)
Vinculando uma Conta e Conectando
Com o nível Preview habilitado (consulte Habilitando o Nível Preview), compile a extensão, copie o seu arquivo.veb para o veb_dir,
instale-a e vincule uma conta ao método. Como o handler mapeia para uma segunda conta, crie
essa conta também e conceda a ela o privilégio PROXY que permite à conta que se
conecta assumir a sua identidade:
CREATE USER ... IDENTIFIED WITH vsql_auth_test é aceito porque
vsql_auth_test é um método de autenticação VEF registrado — da mesma forma que
o nome de um plugin instalado é aceito.
Somente a forma IDENTIFIED WITH <method> é aceita, opcionalmente com
AS '...'. Adicionar BY '...' pede ao método que transforme uma senha em uma
credencial armazenada — o trabalho que um plugin do MySQL faz através de
generate_authentication_string() — e nenhum método de autenticação VEF declara
esse hook hoje, então o servidor o rejeita:
plugin da conta em vez do padrão
da tabela, e é isso que o próximo login da conta lê:
mysql_clear_password, então o cliente precisa passar
--enable-cleartext-plugin para enviar o token em texto claro. Com um token
correto, a sessão é executada como a conta mapeada e expõe a conta que se conecta
através de @@external_user:
Criando Contas Automaticamente
Um método também pode tratar logins de contas que ainda não existem e fazer o servidor criar a conta como parte do login bem-sucedido. Sem isso, uma conta desconhecida é rejeitada antes que qualquer método seja executado. Adira com.auto_create(&callback). O callback não recebe argumentos e retorna
bool; o servidor o chama a cada login de conta desconhecida em vez de lê-lo uma
única vez no registro, então o método pode seguir uma configuração de tempo de
execução própria em vez de congelar a escolha quando a extensão carrega:
.auto_create() de fora, ou retornar false do callback, mantém o
comportamento padrão: uma conta desconhecida é negada. Apenas um método instalado
pode aderir por vez — se dois retornarem true, o servidor se recusa a adivinhar,
registra um aviso no log de erros e rejeita contas desconhecidas como se nenhum
tivesse aderido.
No handler, c.account_unknown() distingue os dois casos. Valide a credencial
primeiro, depois descreva o que criar e autentique-se como ela:
request_provision(account, roles, n_roles) registra a intenção e não retorna
nada. O servidor executa o DDL ele mesmo, depois que o handler retorna
AuthResult::kOk, e apenas para um login que foi roteado como uma conta
desconhecida — então um login que o handler acaba negando não cria nada, e um
pedido que nomeia uma conta que já existe deixa a vinculação dela como está, e a conta ainda recebe os papéis nomeados. O que o servidor executa é
CREATE USER IF NOT EXISTS <account>@'%' IDENTIFIED WITH <method>, seguido de um
GRANT por papel nomeado: a conta é sempre criada para o host % e vinculada ao
método que a autenticou, e account não precisa ser o nome do usuário que se
conecta. Se a criação não puder ser feita — em um servidor super_read_only, por
exemplo — o login falha em vez de prosseguir sem uma conta.
O servidor não grava no log binário o CREATE USER automático, os seus GRANTs, nem os GRANTs e REVOKEs da reconciliação de papéis. Cada servidor em uma topologia de replicação cria e reconcilia a conta para si mesmo.
Os papéis se comportam como em Preparando Papéis Ativos:
o DBA é dono deles. Cada nome já deve existir como um papel concedível, e um que
não puder ser concedido é registrado no log e ignorado em vez de fazer o login
falhar, de modo que um token pode nomear um papel mas nunca criar ou escalar um.
O nome da conta vem do cliente, então o servidor o delimita com aspas como um identificador —
um nome forjado vira uma conta com nome estranho, nunca uma segunda instrução.
A extensão vsql_auth_test provisiona o usuário que se conecta com o papel
vsql_role_granted e coloca a adesão atrás de vsql_auth_test.auto_create, que
começa em OFF. Ative-a e crie o papel primeiro, depois conecte-se como uma conta
que não existe:
Concedendo Papéis Automaticamente
Por padrão, um papel que um token nomeia só tem efeito se a conta já o possui; um que ela não possui é ignorado, e o servidor registra o motivo no log (VEF auth: role '<role>'@'<host>' requested for account '<user>'@'<host>' is not granted; skipping). .roles_mode(&callback) muda isso: o callback retorna um
vef_auth_roles_mode_t — VEF_AUTH_ROLES_ACTIVATE (o padrão),
VEF_AUTH_ROLES_GRANT ou VEF_AUTH_ROLES_SYNC — e o servidor reconcilia os
papéis preparados com os papéis concedidos à conta de acordo com ele, a cada
login.
O callback tem o mesmo formato que o de .auto_create() — sem argumentos — mas
retorna o enum de modo em vez de um bool, e o servidor o chama a cada login,
lendo ao vivo o que quer que o sustente:
.auto_create() decide se um login para uma conta que ainda não existe pode
provisionar uma; .roles_mode() é executado depois, contra qualquer conta para
a qual o login se resolveu — a que acabou de ser provisionada ou uma que já
existia — de modo que a mesma reconciliação se aplica em ambos os casos.
VEF_AUTH_ROLES_ACTIVATE, ou nenhum callback, mantém o padrão de apenas ativar.
VEF_AUTH_ROLES_GRANT é aditivo: ele concede um papel preparado que a conta não
tem, e nunca executa a etapa de revogação. VEF_AUTH_ROLES_SYNC executa essa
etapa: ele revoga todo papel concedido que o token não reivindicou, então um
papel removido do token também é removido da conta no próximo login — exceto um
papel definido como DEFAULT ROLE da conta por um ALTER USER de um operador,
que o SYNC nunca revoga. Em qualquer um dos modos, um papel preparado que não
existe como um papel do banco de dados falha no seu GRANT e é registrado no
log e ignorado, em vez de fazer o login falhar.
vsql_auth_test expõe isso como vsql_auth_test.auto_grant, um enum
OFF/ON/SYNC (que também começa em OFF) cuja ordem de índices corresponde
à ordem dos modos acima. O seu token -token-roles prepara vsql_role_granted
e vsql_role_denied, e a conta abaixo não possui nenhum dos dois. Com a
configuração desligada, o login deixa os papéis da conta em paz:
auth_user com a senha vsql-auth-test-token-roles, da mesma
forma que acima, e pergunte o que está ativo com SELECT CURRENT_ROLE():
SHOW GRANTS mostra a concessão que o
servidor adicionou: