认证鉴权
3 分钟阅读
简要概述
认证、鉴权。
配置示例
security:
enable: true
authentication:
insecure_rpcs:
- SearchHosts
oidc_provider:
issuer: https://accounts.example.com
config:
client_id: example
supported_signing_algs:
- RS256
skip_client_id_check: true
skip_expiry_check: false
skip_issuer_check: true
insecure_skip_verify: true
http_users:
- username: user1
password: pass1
roles:
- sysadmin
authorization:
allowed_roles:
- sysadmin
配置参数
Security
| 名称 | 类型 | 说明 |
|---|---|---|
| enable | bool | 是否开启认证、鉴权 |
| authentication | Authentication | 用户认证，也就是当前是谁在登录 |
| authorization | Authorization | 用户鉴权，也就是当前登录用户是否有权限操作对应资源 |
Authentication
| 名称 | 类型 | 说明 |
|---|---|---|
| insecure_rpcs | []string | 对应 gRPC 的方法，可以跳过认证 |
| oidc_provider | OIDCProvider | OIDC 相关配置 |
| http_users | []BasicAuth | 用户密码列表 |
OIDCProvider
| 名称 | 类型 | 说明 |
|---|---|---|
| issuer | string | oidc 提供者 |
| config | OIDCConfig | oidc 配置 |
OIDCConfig
| 名称 | 类型 | 说明 |
|---|---|---|
| client_id | string | 用于验证 token.aud 是否与 client_id 相等 |
| client_secret | string | OIDC 客户端密钥（启用内置 admin 服务时用于对接 OIDC） |
| supported_signing_algs | []string | 服务端允许 token 的签名算法类型 |
| skip_client_id_check | bool | 忽略 token.aud 与client_id 的验证 |
| skip_expiry_check | bool | 忽略 token 是否过期的验证 |
| skip_issuer_check | bool | 忽略 token issuer 的验证 |
| insecure_skip_verify | bool | 忽略 issuer 的ca验证 |
BasicAuth
| 名称 | 类型 | 说明 |
|---|---|---|
| user_id | int64 | 用户 ID |
| username | string | 用户名 |
| password | string | 明文口令（Deprecated：生产环境优先使用 password_hash） |
| password_hash | string | 口令哈希，优先于 password；可为 sha256 十六进制或 bcrypt 串 |
| roles | []string | 用户角色编码列表，当前授权白名单比对的实际来源 |
| groups | []string | （遗留）用户归属组，不再参与授权判断 |
| tenant | string | 租户，默认 default |
Authorization
| 名称 | 类型 | 说明 |
|---|---|---|
| allowed_roles | []string | 非空角色编码白名单：请求用户必须命中其中至少一个角色 |
| allowed_groups | []string | （遗留兼容）当前按角色编码解释的旧字段；与 allowed_roles 同时配置时两者必须为同一集合 |
| opa_native | OPANative | 内置鉴权功能 |
| opa_external | OPAExternal | 获取外部 opa bundle 鉴权策略 |
| opa_envoy_plugin | OPAEnvoyPlugin | 连接外部 opa-envoy-plugin 服务鉴权 |
白名单语义：
allowed_roles与allowed_groups描述的必须是同一个集合， 仅命名不同（组 → 角色的迁移期兼容）；两者同时配置且集合不一致时视为配置 错误，请求将被拒绝。
OPANative
| 名称 | 类型 | 说明 |
|---|---|---|
| enabled | bool | 是否开启该鉴权服务 |
| policy | Policy | 本地策略文件 “auth.rego” 与 “data.yaml” 路径 |
- Policy
| 名称 | 类型 | 说明 |
|---|---|---|
| auth_file | string | 为空，则默认使用内嵌 “internal/security/auth.rego” 源代码 |
| data_file | string | 为空，则默认使用内嵌 “internal/security/data.yaml” 源代码 |
OPAExternal
| 名称 | 类型 | 说明 |
|---|---|---|
| enabled | bool | 是否开启该鉴权服务 |
| config | string | 对应 open policy agent 配置文件内容 |
OPAEnvoyPlugin
| 名称 | 类型 | 说明 |
|---|---|---|
| enabled | bool | 是否开启该鉴权服务 |
| service | Service | 插件配置内容 |
- Service
| 名称 | 类型 | 说明 |
|---|---|---|
| grpc_address | string | 对应 opa-envoy-plugin 服务地址 |
使用场景
允许所有请求
security:
enable: false
服务端允许所有接口请求，均以匿名用户，也就是关闭认证鉴权。
HTTP Basic 用户
security:
enable: true
authentication:
http_users:
- username: user1
password: pass1
- username: user2
password: pass2
开启服务端接口验证，通过 HTTP Basic Auth 方式，允许用户 “user1:pass1” 或 “user2:pass2” 发起请求通过认证。
忽略特定 RPC 验证
security:
enable: true
authentication:
insecure_rpcs:
- Demo
- HealthCheck
http_users:
- username: user1
password: pass1
开启服务端接口认证，但是忽略 “Demo” 与 “HealthCheck” 两个 gRPC 方法的检查。命中 insecure_rpcs 的方法认证与鉴权均被跳过，以匿名方式放行。
开启 Token 支持 HS256 签名
security:
enable: true
authentication:
oidc_provider:
issuer: https://accounts.example.com
config:
supported_signing_algs:
- HS256
skip_issuer_check: true
insecure_skip_verify: true
http_users:
- username: user1
password: pass1
支持客户端 Token 是以 HS256 签名算法，其中 “token.sub” 为 “user1”。
签名密钥取该用户的有效口令哈希：password_hash（trim 后）非空则原样使用；
否则使用 SHA256(明文口令) 的十六进制。上例即 SHA256(“pass1”)。
注意：这种签名的 token 不会传递给所配置的 oidc 服务提供验证，而是替换使用本地配置的 http basic 用户所对应的有效口令哈希作为 token 的签名密钥
仅允许特定角色访问
security:
enable: true
authentication:
oidc_provider:
issuer: https://accounts.example.com
config:
skip_issuer_check: true
insecure_skip_verify: true
http_users:
- username: user1
password: pass1
roles:
- sysadmin
- username: user2
password: pass2
roles:
- guest
authorization:
allowed_roles:
- sysadmin
则该服务仅可被拥有 “sysadmin” 角色的用户访问，使用 “http basic” 既仅 “user1”。
如果使用 “oidc”，则要求 “jwt” 中的角色声明命中 “sysadmin”（角色取自 token 的角色属性，不再回退用户组 groups）。
使用应用本地鉴权策略
# 认证鉴权配置
security:
enable: true
# 认证：谁在登录
authentication:
http_users:
- username: user1
password: pass1
roles:
- sysadmin
# 鉴权：能做什么
authorization:
# 内置权限规则，通过本地配置文件管理
opa_native:
enabled: true
#policy:
# 未配置则为 internal/security/auth.rego 内嵌文件
#auth_file: "./config/auth.rego"
# 未配置则为 internal/security/data.yaml 内嵌文件
#data_file: "./config/data.yaml"
如果未配置 “security.authorization.opa_native.policy.auth_file” 参数，则服务在编译时会使用源代码路径下 “internal/security/auth.rego” 内容，并在编译时嵌入至应用二进制内。如果配置则需保证文件存在，同时策略文件独立于应用程序。
同理，如果未配置 “security.authorization.opa_native.policy.data_file” 参数，则服务在编译时会使用源代码路径下 “internal/security/data.yaml” 内容，并在编译时嵌入至应用二进制内。如果配置则需保证文件存在，同时策略文件独立于应用程序。
使用外部鉴权策略文件
# 认证鉴权配置
security:
enable: true
# 认证：谁在登录
authentication:
http_users:
- username: user1
password: pass1
roles:
- sysadmin
# 鉴权：能做什么
authorization:
# 权限规则由外部管理，如更改权限本地实时生效，无需重启服务
opa_external:
enabled: true
# 配置内容见：https://www.openpolicyagent.org/docs/latest/configuration/
config: |
services:
test:
url: http://192.168.0.2:8080
bundles:
test:
resource: /bundle.tar.gz
decision_logs:
console: false
以上配置说明在服务启动时，会从 “http://192.168.0.2:8080/bundle.tar.gz” 下载权限规则并加载至应用内。
使用外部 opa-envoy-plugin 服务
# 认证鉴权配置
security:
enable: true
# 认证：谁在登录
authentication:
http_users:
- username: user1
password: pass1
roles:
- sysadmin
# 鉴权：能做什么
authorization:
# 通过把数据提交至 opa-envoy-plugin 服务，由它进行判断功能
opa_envoy_plugin:
enabled: true
service:
grpc_address: 192.168.0.1:9191
这个同 envoy ext_authz 插件。
每次鉴权时，均需连接 “grpc_address” 地址做个判断，如果服务故障则会拒绝连接请求。
多个鉴权服务同时使用
security:
enable: true
authentication:
oidc_provider:
issuer: https://accounts.example.com
config:
skip_issuer_check: true
insecure_skip_verify: true
http_users:
- username: user1
password: pass1
roles:
- sysadmin
- username: user2
password: pass2
roles:
- guest
authorization:
allowed_roles:
- sysadmin
opa_native:
enabled: true
......
opa_external:
enabled: true
......
opa_envoy_plugin:
enabled: true
......
如果同时启用了 “allowed_roles”、“opa_native”、“opa_external”、“opa_envoy_plugin” 鉴权功能，则一个请求必须同时满足以上才可被允许访问。
当前授权语义补充
allowed_roles 非空时要求角色交集；空或未配置时不额外施加白名单限制，仍执行配置的 OPA 策略。常规 KnownAdmin 方法要求非空有效角色，自服务和 bootstrap 等方法有例外。allowed_groups 保留兼容语义，当前表示角色编码；两字段同时配置必须为同一集合，否则拒绝访问。
原生 HTTP/MCP 扩展不自动等价于 RPC 权限路径。认证成功后仍须检查业务对象归属和操作权限，参见MCP 接入实践与Admin 启用。