用途
该技能提供将 Keycloak 作为身份提供者（Identity Provider）与 FastAPI 应用集成的模式，基于 OIDC/OAuth2 协议。当用户需要添加 Keycloak 认证、实现 OIDC、配置 SSO、校验 JWT 令牌或添加基于角色的访问控制时，可使用本技能。
主要能力
配置管理
通过 KeycloakSettings（基于 pydantic_settings 的 BaseSettings）集中管理 Keycloak 连接参数，包括 keycloak_url、keycloak_realm、keycloak_client_id、keycloak_client_secret，并派生以下端点：
openid_config_url：{keycloak_url}/realms/{keycloak_realm}/.well-known/openid-configurationjwks_url：{keycloak_url}/realms/{keycloak_realm}/protocol/openid-connect/certstoken_url：{keycloak_url}/realms/{keycloak_realm}/protocol/openid-connect/token
配置支持从 .env 文件读取。
JWT 令牌校验
KeycloakTokenValidator 类负责获取 JWKS 并校验令牌：
- 通过
get_jwks异步获取并缓存 JWKS。 validate_token从令牌头部读取kid，在 JWKS 中查找匹配密钥，使用 RS256 算法解码，并校验 audience（client_id）与 issuer。- 校验失败抛出
ValueError。
FastAPI 依赖
get_current_user：从 Bearer 凭证中提取并校验令牌，返回TokenUser；未认证时返回 401。get_current_user_optional：可选认证，无凭证或校验失败时返回 None。TokenUser封装sub、email、name、preferred_username、roles及原始 payload；角色从 realm_access 与 resource_access 中提取并合并去重。
基于角色的访问控制
require_roles(*required_roles)：用户拥有任一所需角色即可通过，否则返回 403。require_all_roles(*required_roles)：用户必须拥有全部所需角色，否则返回 403 并列出缺失角色。
受保护路由
提供路由示例，包括需要认证的 /profile、公开的 /public、以及根据认证状态返回不同数据的 /optional-auth。
令牌刷新流程
KeycloakAuthService 提供：
refresh_token：使用 refresh_token 换取新的 access_token 与 refresh_token。exchange_code：使用授权码换取令牌。
令牌刷新中间件
TokenRefreshMiddleware 检查请求状态中的 token_exp，若令牌将在 5 分钟内过期，则在响应头添加 X-Token-Expiring: true 以提示前端刷新。
使用方式
该技能以代码模式与示例形式提供，包含配置类、令牌校验器、FastAPI 依赖、角色检查依赖、受保护路由、令牌刷新服务与中间件。开发者可将这些模式直接应用于 FastAPI 项目。
适用场景
- 为 FastAPI 接口添加 Keycloak 认证。
- 实现 OIDC 与 SSO。
- 校验 JWT 令牌。
- 添加基于角色的访问控制。
- 实现令牌刷新与授权码交换。
限制
资料未提供具体的安装命令、依赖版本要求、Keycloak 服务端配置步骤的完整细节、多租户与测试的详细内容（仅提及参考文件 references/keycloak-setup.md、references/multi-tenant.md、references/testing.md 以及示例文件 examples/auth_dependencies.py、examples/protected_router.py、examples/keycloak_service.py）。收费、价格、平台支持与效果等信息暂未提供。