跳转到主要内容

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 会被拒绝。
一旦已经有了身份提供方,数据库密码就变得难以管理。它们单独签发、单独轮换,并且在拿到密码的人离开之后依然存在。VillageSQL 的 vsql_oauth2 扩展让账户改用 JSON Web Token 登录:提供方签发令牌,服务器验证签名和过期时间,令牌中的一个声明指明账户。

设置签名密钥

该扩展验证签名的方式有两种:对照从 JWKS 端点获取的密钥(与真实提供方配合时使用的方式),或者对照您粘贴进去的一个公钥。静态密钥是查看整个流程运转的最快方式,所以本指南从它开始。
username_claim 指明携带账户名的声明。它默认为 sub,下面的示例令牌使用的就是它。 与真实提供方配合时,您改为设置 jwks_url。扩展会获取密钥,按 jwks_refresh_interval 中的间隔重新获取,并在令牌指明了缓存中没有的密钥 id 时立即重新获取。还请设置 issuer 和 audience,这样为其他系统签发的令牌不会在这里被接受。

创建账户

该账户是一个普通的 MySQL 账户,在创建时指定为使用该扩展进行认证。它带有自己的授权:
没有密码需要设置,也没有密码需要轮换。 会话以令牌指明的账户运行,而不是以发起连接的账户运行。这个名称来自 username_claim 中的声明,默认为 sub。只要该声明的值是 analyst,上面的语句就足够了。当您的提供方在那里放的是别的东西,比如一个电子邮件地址时,请同时创建那个账户,并让发起连接的账户代理到它:
没有人直接以 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.

登录

令牌放在通常放密码的位置传输,经由内置的 mysql_clear_password 插件,客户端必须显式启用它:
用 --password= 传递令牌会让它出现在进程列表中,这就是令牌改放在环境变量中的原因。 在会话内部,CURRENT_USER() 是数据库账户,而 @@external_user 保留着令牌携带的身份,这正是审计记录中需要的:
mysql_clear_password 在协议层以明文发送令牌。请在每一个 以这种方式认证的连接上使用 TLS,否则路径上的任何东西都能读取令牌, 并在它过期之前重放。

从令牌映射角色

账户也可以从令牌获取权限。把扩展指向携带角色的声明,并打开授予:
创建一个角色,以及一个自身没有任何权限的账户:
携带 "roles": ["shop_reader"] 的令牌登录后,该角色处于激活状态:
roles_filter 缩小被考虑的角色名范围,而 roles_transform_pattern 与 roles_transform_replacement 把提供方给出的名称改写为数据库角色名,适用于组名看起来不像角色名的提供方。
auto_grant 会写入一条真实的授权,并且它在登录结束后依然存在。上面的登录之后, 这条授权就在服务器中了:
之后关闭 auto_grant 并不会把它收回。一个令牌,只出现一次, 就会扩大该账户的权限,直到有人撤销该角色。请在启用之前先限定 roles_filter,并把这个声明视为您的提供方必须被信任才能设置的东西。
auto_grant 关闭时,同一个令牌仍能登录,角色会被跳过而不是授予,CURRENT_ROLE() 为 NONE。每个被跳过的角色都会写入错误日志:VEF auth: role 'shop_reader'@'%' requested for account 'dana'@'%' is not granted; skipping。auto_create 对账户的行为与之相同,它会在服务器从未见过的主体第一次登录时创建一个账户。两者默认都是关闭的,而且两者都把这台服务器的控制权交给了您的提供方。

被拒绝的令牌看起来像密码错误

每一种失败都产生同一个错误,而且是那个普通的错误:
过期的令牌、用错误密钥签名的令牌,以及误输入的普通密码,都会产生完全相同的输出,包括 using password: NO——这有误导性,因为确实发送了令牌。服务器错误日志中也不会出现任何有区分度的信息,即使在 log_error_verbosity=3 下也是如此。 所以请从令牌而不是从错误入手调试。解码令牌,并按以下顺序检查四件事:
  1. exp 在未来。提供方与服务器之间的时钟偏差也算在内。
  2. 签名密钥匹配。 检查令牌的 kid 是 JWKS 文档仍在发布的密钥。文档中不再包含的密钥看起来与伪造的令牌一模一样。
  3. iss 和 aud 与您配置的值匹配(如果您配置了它们)。
  4. username_claim 中的声明指向一个存在的账户,拼写与账户的拼写一致。
解码载荷只需要一个 shell,不需要其他工具:

故障排除

另请参阅