Pular para o conteúdo principal
As capabilities desta página estão em Preview: suas APIs não são estáveis, e uma extensão que declara uma delas requer 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.
O resultado da autenticação é fail-closed. O servidor trata qualquer coisa diferente de AuthResult::kOk como uma conexão negada — deliberadamente não há resultado “talvez” nem fail-open. Um handler que retorna AuthResult::kReject, retorna AuthResult::kError ou nunca define a conta efetiva nega o login.

Declarando a Capability

Inclua o cabeçalho, escreva um handler tipado, construa um descritor com o construtor fluente make_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:
O construtor tem seis peças: 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 tipo AuthHandler — ele recebe um AuthContext & e retorna um AuthResult:
Ele é invocado de forma síncrona na thread de conexão durante o handshake. O 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ão vsql_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:
O nome do método vinculado é gravado na coluna plugin da conta em vez do padrão da tabela, e é isso que o próximo login da conta lê:
O método pede 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:
Desinstalar a extensão remove o método; as contas vinculadas a ele não conseguem mais se autenticar:

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:
Deixar .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:
A conta agora existe, vinculada ao método, com o papel concedido:
Um token errado ainda falha de forma fechada, e não provisiona nada:
Aderir torna a diferença entre uma conta desconhecida e uma existente observável, algo que a rejeição padrão de contas desconhecidas esconde deliberadamente: um login rejeitado para uma conta desconhecida informa (using password: NO), enquanto um login rejeitado para uma conta com uma senha comum informa (using password: YES), e uma credencial válida cria a conta. Essa é a troca que este recurso faz; pondere-a antes de habilitar a adesão em um método cujas credenciais sejam amplamente distribuídas.

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:
As duas adesões são executadas em pontos diferentes de um login. .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:
Conecte-se como 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():
Ligue a configuração e repita o mesmo login:
Os dois papéis agora estão ativos, e o SHOW GRANTS mostra a concessão que o servidor adicionou:
Com vsql_auth_test.auto_grant definido como ON ou SYNC, um token válido basta para obter qualquer papel que ele nomeie. Um papel que ainda não existe como um papel do banco de dados falha no seu GRANT e é ignorado, então um token ainda não pode inventar um papel que nunca foi criado, mas o DBA deixa de decidir quais dos papéis que existem uma conta pode alcançar — quem decide é o método de autenticação. O SYNC vai além: ele também revoga um papel que um DBA concedeu por fora mas que o token nunca reivindica, quando a conta faz login novamente — um operador ainda pode fixar um papel além disso definindo-o como o DEFAULT ROLE da conta, que o SYNC deixa em paz. Um papel revogado de vsql_auth_test_user não desaparece de uma sessão que já o ativou: consultar CURRENT_ROLE() de novo nessa mesma sessão, depois da revogação, ainda lista o papel.