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 会被拒绝。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 保留着令牌携带的身份,这正是审计记录中需要的:
从令牌映射角色
账户也可以从令牌获取权限。把扩展指向携带角色的声明,并打开授予:"roles": ["shop_reader"] 的令牌登录后,该角色处于激活状态:
roles_filter 缩小被考虑的角色名范围,而 roles_transform_pattern 与 roles_transform_replacement 把提供方给出的名称改写为数据库角色名,适用于组名看起来不像角色名的提供方。
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 下也是如此。
所以请从令牌而不是从错误入手调试。解码令牌,并按以下顺序检查四件事:
exp在未来。提供方与服务器之间的时钟偏差也算在内。- 签名密钥匹配。 检查令牌的
kid是 JWKS 文档仍在发布的密钥。文档中不再包含的密钥看起来与伪造的令牌一模一样。 iss和aud与您配置的值匹配(如果您配置了它们)。username_claim中的声明指向一个存在的账户,拼写与账户的拼写一致。
故障排除
另请参阅
- vsql_oauth2 — 该扩展的参考页面,列出它添加的每一项设置
- MySQL 用户管理 — 以令牌认证的账户仍然需要的授权
- MySQL 安全加固 — TLS 以及连接层面的其他内容
- 使用 HMAC 为数据签名 — 在 SQL 内部而不是在登录时验证签名