Envoy Gateway 中的 JWT 声明授权配置指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01149/article/details/148940423

Envoy Gateway 中的 JWT 声明授权配置指南

gateway Manages Envoy Proxy as a Standalone or Kubernetes-based Application Gateway 项目地址: https://gitcode.com/gh_mirrors/gate/gateway

前言

在现代微服务架构中，安全认证和授权是至关重要的环节。JSON Web Token (JWT) 作为一种轻量级的认证机制，因其自包含性和易于传输的特点，被广泛应用于分布式系统的身份验证。Envoy Gateway 作为云原生 API 网关解决方案，提供了强大的 JWT 声明授权功能，本文将详细介绍如何配置和使用这一功能。

JWT 声明授权概述

JWT 声明授权是一种基于令牌中声明(claims)的细粒度访问控制机制。它允许系统管理员定义特定的声明要求，只有满足这些要求的 JWT 令牌才能访问受保护的资源。

Envoy Gateway 通过 SecurityPolicy 自定义资源(CRD)来实现这一功能，该资源可以关联到 Gateway、HTTPRoute 或 GRPCRoute 资源上，为不同的路由路径提供灵活的安全策略。

准备工作

在开始配置前，请确保：

已安装 Kubernetes 集群
已部署 Envoy Gateway
具备 kubectl 命令行工具
了解基本的 JWT 概念和工作原理

配置详解

创建 SecurityPolicy

以下是一个完整的 SecurityPolicy 配置示例，它实现了 JWT 声明授权：

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: authorization-jwt-claim
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: backend
  jwt:
    providers:
    - name: example
      issuer: https://foo.bar.com
      remoteJWKS:
        uri: https://example.com/jwks.json
  authorization:
    defaultAction: Deny  # 默认拒绝所有请求
    rules:
    - name: "allow"     # 定义允许规则
      action: Allow
      principal:
        jwt:
          provider: example  # 使用上面定义的JWT提供者
          scopes: ["read", "add", "modify"]  # 必需的scope声明
          claims:           # 必需的claims声明
          - name: user.name
            values: ["John Doe"]
          - name: user.roles
            valueType: StringArray  # 声明值类型为字符串数组
            values: ["admin"]

关键配置说明

JWT 提供者配置:
- issuer: JWT 签发者标识，必须与令牌中的 iss 声明匹配
- remoteJWKS: 指定远程 JWKS (JSON Web Key Set) 端点，用于验证令牌签名
授权规则:
- defaultAction: 默认动作，建议设置为 Deny 以实现白名单模式
- rules: 定义具体的授权规则
  - scopes: 要求令牌中包含的 scope 声明
  - claims: 要求令牌中包含的其他声明及其值
声明匹配:
- 支持简单值匹配和数组值匹配
- 可以通过 valueType 指定声明值的类型

测试验证

准备测试令牌

有效令牌:
- 包含所有必需的声明
- 用户名为 "John Doe"
- 角色包含 "admin"
- scope 包含 "read", "add" 和 "modify"
无效令牌:
- 缺少某些必需声明
- 或声明值不符合要求

发送测试请求

# 使用有效令牌测试
curl -H "Host: www.example.com" -H "Authorization: Bearer ${VALID_TOKEN}" "http://${GATEWAY_HOST}/"

# 使用无效令牌测试
curl -v -H "Host: www.example.com" -H "Authorization: Bearer ${INVALID_TOKEN}" "http://${GATEWAY_HOST}/"

预期结果:

有效令牌应返回后端服务响应
无效令牌应返回 403 Forbidden 错误

最佳实践

最小权限原则:
- 只授予必要的权限
- 使用最严格的默认策略(Deny)
声明设计:
- 使用有意义的声明名称
- 避免在声明中存储敏感信息
性能考虑:
- 对于高频访问路径，考虑缓存JWT验证结果
- 合理设置JWKS缓存时间
错误处理:
- 为不同的错误情况(如令牌过期、签名无效等)提供清晰的错误信息
- 记录详细的授权日志用于审计

常见问题排查

403 Forbidden 错误:
- 检查令牌是否包含所有必需声明
- 验证声明值是否完全匹配(包括大小写)
- 确认令牌未过期
JWT 验证失败:
- 检查 JWKS 端点是否可访问
- 验证令牌签名算法是否支持
- 确认令牌中的 issuer 与配置匹配
配置不生效:
- 检查 SecurityPolicy 是否关联到正确的路由
- 确认 Envoy Gateway 版本支持该功能
- 查看 Envoy 日志获取详细错误信息