插件参数

Apache APISIX 插件参数详解

目录

• 1. OpenID Connect 插件
• 2. Authz-Keycloak 插件

---

1. OpenID Connect 插件

1.1 插件概述

插件名称: openid-connect
优先级: 2599
版本: 0.2

OpenID Connect 插件用于将 APISIX 作为 OpenID Connect (OIDC) 的依赖方（Relying Party），实现基于 OIDC 协议的身份验证和授权。

1.2 核心参数表

参数名称	类型	必需	默认值	说明
client_id	string	✅	-	OIDC 客户端 ID，在身份提供商（IdP）注册时获得
client_secret	string	✅	-	OIDC 客户端密钥，用于客户端认证（加密字段）
discovery	string	✅	-	OIDC 发现端点 URL，通常为 {issuer}/.well-known/openid-configuration
scope	string	❌	"openid"	OAuth 2.0 授权范围，多个范围用空格分隔
ssl_verify	boolean	❌	false	是否验证身份提供商的 SSL 证书
timeout	integer	❌	3	连接超时时间（秒），内部会转换为毫秒

1.3 端点配置参数

参数名称	类型	必需	默认值	说明
introspection_endpoint	string	❌	-	Token 内省端点 URL，用于验证访问令牌的有效性
introspection_endpoint_auth_method	string	❌	"client_secret_basic"	访问内省端点时的认证方法
token_endpoint_auth_method	string	❌	"client_secret_basic"	访问令牌端点时的认证方法
redirect_uri	string	❌	自动生成	授权回调 URI，未配置时自动添加 /.apisix/redirect 后缀
post_logout_redirect_uri	string	❌	-	登出后的重定向 URI
logout_path	string	❌	"/logout"	触发登出操作的路径

1.4 会话管理参数

参数名称	类型	必需	默认值	说明
session	object	❌	自动生成	会话配置对象，当 bearer_only=false 时建议配置
session.secret	string	✅(当配置session时)	自动生成	用于加密和 HMAC 计算的密钥，最小长度 16 字符
session.cookie.lifetime	integer	❌	-	Cookie 的生命周期（秒）

1.5 认证模式参数

参数名称	类型	必需	默认值	说明
bearer_only	boolean	❌	false	仅承载令牌模式，为 true 时要求请求必须包含有效的访问令牌
unauth_action	string	❌	"auth"	未认证时的操作：auth（重定向到 IdP）、deny（返回 401）、pass（放行）
realm	string	❌	"apisix"	HTTP 认证域，用于 WWW-Authenticate 响应头

1.6 令牌验证参数

参数名称	类型	必需	默认值	说明
public_key	string	❌	-	IdP 的公钥，用于本地验证 JWT 签名
token_signing_alg_values_expected	string	❌	-	期望的令牌签名算法
use_pkce	boolean	❌	false	是否使用 PKCE (Proof Key for Code Exchange) 增强安全性
use_nonce	boolean	❌	false	是否在授权请求中包含 nonce 参数
accept_none_alg	boolean	❌	false	是否接受不签名的 ID 令牌
accept_unsupported_alg	boolean	❌	true	是否忽略 ID 令牌签名以接受不支持的签名算法

1.7 令牌刷新与过期参数

参数名称	类型	必需	默认值	说明
renew_access_token_on_expiry	boolean	❌	true	访问令牌过期时是否尝试静默续订
access_token_expires_in	integer	❌	-	访问令牌生命周期（秒），当响应中没有 expires_in 时使用
access_token_expires_leeway	integer	❌	0	访问令牌续订的过期容忍时间（秒）
refresh_session_interval	integer	❌	-	刷新用户 ID 令牌的时间间隔（秒），无需重新认证
iat_slack	integer	❌	120	ID 令牌 iat 声明的时钟偏差容忍度（秒）
force_reauthorize	boolean	❌	false	即使令牌已缓存也执行授权流程
revoke_tokens_on_logout	boolean	❌	false	登出时通知授权服务器撤销令牌

1.8 请求头设置参数

参数名称	类型	必需	默认值	说明
set_access_token_header	boolean	❌	true	是否将访问令牌添加到下游请求头
access_token_in_authorization_header	boolean	❌	false	访问令牌是否放在 Authorization 头中（否则放在 X-Access-Token 中）
set_id_token_header	boolean	❌	true	是否将 ID 令牌添加到 X-ID-Token 请求头
set_userinfo_header	boolean	❌	true	是否将用户信息添加到 X-Userinfo 请求头
set_refresh_token_header	boolean	❌	false	是否将刷新令牌添加到 X-Refresh-Token 请求头

1.9 声明验证参数

参数名称	类型	必需	默认值	说明
claim_validator	object	❌	-	JWT 声明验证器配置
claim_validator.issuer.valid_issuers	array[string]	❌	discovery 返回的 issuer	白名单颁发者列表，用于验证 JWT 的 iss 声明
claim_validator.audience.claim	string	❌	"aud"	自定义受众声明名称
claim_validator.audience.required	boolean	❌	false	受众声明是否必需
claim_validator.audience.match_with_client_id	boolean	❌	false	受众是否必须等于或包含 client_id

1.10 代理配置参数

参数名称	类型	必需	默认值	说明
proxy_opts	object	❌	-	HTTP 代理配置对象
proxy_opts.http_proxy	string	❌	-	HTTP 代理地址，如 http://proxy-server:80
proxy_opts.https_proxy	string	❌	-	HTTPS 代理地址，如 http://proxy-server:80
proxy_opts.http_proxy_authorization	string	❌	-	HTTP 代理认证，格式：Basic [base64 username:password]
proxy_opts.https_proxy_authorization	string	❌	-	HTTPS 代理认证，格式：Basic [base64 username:password]
proxy_opts.no_proxy	string	❌	-	不需要代理的主机列表，逗号分隔

1.11 高级配置参数

参数名称	类型	必需	默认值	说明
authorization_params	object	❌	-	传递给授权端点的额外参数
client_rsa_private_key	string	❌	-	客户端 RSA 私钥，用于签名 JWT（加密字段）
client_rsa_private_key_id	string	❌	-	客户端 RSA 私钥 ID，用于计算签名 JWT
client_jwt_assertion_expires_in	integer	❌	60	签名 JWT 的生命周期（秒）
jwk_expires_in	integer	❌	86400	JWK 缓存过期时间（秒），默认 24 小时
jwt_verification_cache_ignore	boolean	❌	false	是否忽略缓存的验证并重新验证
cache_segment	string	❌	-	缓存段名称，用于区分不同的缓存

1.12 内省相关参数

参数名称	类型	必需	默认值	说明
introspection_interval	integer	❌	0	缓存的内省访问令牌的 TTL（秒），0 表示不缓存
introspection_expiry_claim	string	❌	-	控制缓存访问令牌 TTL 的过期声明名称
introspection_addon_headers	array[string]	❌	-	内省请求中附加的 HTTP 头列表

1.13 作用域验证参数

参数名称	类型	必需	默认值	说明
required_scopes	array[string]	❌	-	访问令牌必须包含的作用域列表

---

2. Authz-Keycloak 插件

2.1 插件概述

插件名称: authz-keycloak
优先级: 2000
版本: 0.1

Authz-Keycloak 插件用于与 Keycloak 身份和访问管理系统集成，实现基于 UMA (User-Managed Access) 的细粒度授权控制。

2.2 核心参数表

参数名称	类型	必需	默认值	说明
client_id	string	✅	-	Keycloak 客户端 ID
client_secret	string	❌	-	Keycloak 客户端密钥（加密字段）
discovery	string	❌*	-	Keycloak 发现端点 URL，格式：{realm_url}/.well-known/uma2-configuration
token_endpoint	string	❌*	-	Keycloak 令牌端点 URL，可替代 discovery
resource_registration_endpoint	string	❌*	-	资源注册端点 URL，启用 lazy_load_paths 时需要

注意: discovery 和 token_endpoint 至少需要配置一个

2.3 授权配置参数

参数名称	类型	必需	默认值	说明
grant_type	string	❌	"urn:ietf:params:oauth:grant-type:uma-ticket"	OAuth 2.0 授权类型，目前仅支持 UMA ticket
policy_enforcement_mode	string	❌	"ENFORCING"	策略执行模式：ENFORCING（强制）或 PERMISSIVE（宽容）
permissions	array[string]	❌	[]	静态配置的权限列表，格式：resource_name#scope
lazy_load_paths	boolean	❌	false	是否从 Keycloak 动态加载资源路径
http_method_as_scope	boolean	❌	false	是否将 HTTP 方法作为权限作用域

2.4 连接配置参数

参数名称	类型	必需	默认值	说明
timeout	integer	❌	3000	请求超时时间（毫秒）
ssl_verify	boolean	❌	true	是否验证 Keycloak 服务器的 SSL 证书
keepalive	boolean	❌	true	是否启用 HTTP 连接保持
keepalive_timeout	integer	❌	60000	连接保持超时时间（毫秒）
keepalive_pool	integer	❌	5	连接池大小

2.5 缓存配置参数

参数名称	类型	必需	默认值	说明
cache_ttl_seconds	integer	❌	86400	缓存 TTL（秒），默认 24 小时

2.6 访问控制参数

参数名称	类型	必需	默认值	说明
access_denied_redirect_uri	string	❌	-	访问被拒绝时的重定向 URI，配置后返回 307 而非 403

2.7 令牌过期配置参数

参数名称	类型	必需	默认值	说明
access_token_expires_in	integer	❌	300	访问令牌默认生命周期（秒）
access_token_expires_leeway	integer	❌	0	访问令牌过期容忍时间（秒）
refresh_token_expires_in	integer	❌	3600	刷新令牌默认生命周期（秒）
refresh_token_expires_leeway	integer	❌	0	刷新令牌过期容忍时间（秒）

2.8 密码授权模式参数

参数名称	类型	必需	默认值	说明
password_grant_token_generation_incoming_uri	string	❌	-	使用密码授权模式生成令牌的请求 URI

---

3. 两个插件的对比

3.1 功能定位差异

特性	OpenID Connect	Authz-Keycloak
主要用途	身份认证（Authentication）	授权控制（Authorization）
协议基础	OpenID Connect / OAuth 2.0	UMA (User-Managed Access)
典型场景	用户登录、SSO 单点登录	细粒度权限控制、资源访问授权
优先级	2599（较高）	2000（较低）

3.2 使用场景建议

OpenID Connect 插件适用于：

• 需要用户身份认证的场景
• 实现单点登录（SSO）
• 需要获取用户基本信息
• 基于 OAuth 2.0 的授权码流程
• 移动应用或 Web 应用的用户认证

Authz-Keycloak 插件适用于：

• 已有用户令牌，需要验证资源访问权限
• 基于角色或策略的细粒度授权
• 与 Keycloak 深度集成的场景
• 动态权限管理
• 需要 UMA 协议支持的场景

3.3 组合使用建议

在实际应用中，这两个插件可以配合使用：

1. OpenID Connect 负责用户认证，颁发访问令牌
2. Authz-Keycloak 负责权限验证，检查用户是否有权访问特定资源

配置示例：

# 路由级别配置顺序
1. openid-connect 插件（优先级 2599）- 先执行认证
2. authz-keycloak 插件（优先级 2000）- 后执行授权

---

4. 常见配置示例

4.1 OpenID Connect 基础配置

{
  "client_id": "apisix",
  "client_secret": "your-client-secret",
  "discovery": "https://idp.example.com/.well-known/openid-configuration",
  "scope": "openid profile email",
  "bearer_only": false,
  "realm": "apisix",
  "redirect_uri": "https://api.example.com/.apisix/redirect",
  "logout_path": "/logout",
  "session": {
    "secret": "your-secret-key-min-16-chars"
  }
}

4.2 OpenID Connect Bearer Only 模式

{
  "client_id": "apisix-api",
  "client_secret": "your-client-secret",
  "discovery": "https://idp.example.com/.well-known/openid-configuration",
  "bearer_only": true,
  "introspection_endpoint": "https://idp.example.com/token/introspect",
  "introspection_endpoint_auth_method": "client_secret_post"
}

4.3 Authz-Keycloak 静态权限配置

{
  "client_id": "apisix-client",
  "client_secret": "your-client-secret",
  "discovery": "https://keycloak.example.com/realms/master/.well-known/uma2-configuration",
  "policy_enforcement_mode": "ENFORCING",
  "permissions": [
    "resource1#read",
    "resource2#write"
  ],
  "http_method_as_scope": true
}

4.4 Authz-Keycloak 动态权限配置

{
  "client_id": "apisix-client",
  "client_secret": "your-client-secret",
  "discovery": "https://keycloak.example.com/realms/master/.well-known/uma2-configuration",
  "lazy_load_paths": true,
  "http_method_as_scope": true,
  "policy_enforcement_mode": "ENFORCING"
}

---

5. 安全注意事项

5.1 加密字段

以下字段在存储时会被加密：

OpenID Connect:

• client_secret
• client_rsa_private_key

Authz-Keycloak:

• client_secret

5.2 生产环境建议

1. 启用 SSL 验证：

   • 生产环境中将 ssl_verify 设置为 true

2. 使用 HTTPS：

   • 所有端点 URL 应使用 HTTPS 协议
   • discovery、token_endpoint、introspection_endpoint 等

3. 会话密钥管理：

   • session.secret 应使用强随机密钥
   • 最小长度 16 字符，建议 32 字符以上

4. 令牌安全：

   • 合理设置令牌过期时间
   • 启用 renew_access_token_on_expiry 自动续订
   • 考虑使用 revoke_tokens_on_logout 登出时撤销令牌

5. 使用 PKCE：

   • 公共客户端应启用 use_pkce: true

---

6. 故障排查指南

6.1 常见错误

错误 1: 401 Unauthorized

• 检查令牌是否有效
• 验证 client_id 和 client_secret 是否正确
• 确认 discovery URL 可访问

错误 2: 403 Forbidden

• 检查用户是否有相应权限
• 验证 permissions 配置是否正确（Authz-Keycloak）
• 确认 policy_enforcement_mode 设置

错误 3: 503 Service Unavailable

• 检查 Keycloak/IdP 服务是否正常
• 验证网络连接和超时设置
• 查看 timeout 配置是否合理

6.2 调试技巧

1. 启用详细日志：

   • 查看 APISIX error.log
   • 检查插件的 debug 日志输出

2. 验证配置：

   # 测试 discovery 端点
   curl https://idp.example.com/.well-known/openid-configuration
   
   # 测试 token 端点
   curl -X POST https://idp.example.com/token \
     -d "grant_type=client_credentials" \
     -d "client_id=xxx" \
     -d "client_secret=xxx"
   

3. 检查缓存：

   • 清理缓存后重试
   • 验证 cache_ttl_seconds 设置

---

7. 参考资源

• APISIX 官方文档
• OpenID Connect 规范
• OAuth 2.0 规范
• Keycloak 文档
• UMA 2.0 规范

---

文档生成时间: 2025-11-04
基于 APISIX 插件源码分析