如何用 Traefik 的 APIKey 中间件用密钥保护 API 接口

如何用 Traefik 的 APIKey 中间件用密钥保护 API 接口【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefik当你对外暴露一组 API 接口、又不想为它们单独搭建认证服务时可以让 Traefik 在网关层直接把关只有携带了指定密钥的请求才能到达后端其余请求被拦截。这是 Traefik 的 API Key authentication middleware 的用途——它要求客户端通过 HTTP header、cookie 或 query parameter 提供密钥base64 编码与否均可密钥以哈希形式存放在你的配置中网关负责比对。有一个前提必须先知根据 中间件参考文档这个中间件仅随 Traefik Hub 提供This middleware is available exclusively in Traefik HubTraefik OSS 不包含它。下文的操作路径以文档示例的 Kubernetes 环境为基础。配置字段先弄清有哪些旋钮在动手前参考文档 给出了完整字段表核心是两组字段作用默认值必填keySource.header客户端发送密钥的 header 名称。header、query、cookie三者必须至少设一个否keySource.headerAuthSchemeheader 为Authorization时使用的 scheme否keySource.query客户端发送密钥的 query 参数名称否keySource.cookie客户端发送密钥的 cookie 名称否secretNonBase64Encoded客户端发送的密钥是否为 base64 编码false否secretValuesAPI 密钥的哈希值列表支持 Bcrypt、SHA1、MD5哈希用htpasswd生成也可用 URN 格式urn:k8s:secret:[name]:[valueKey]引用 Kubernetes Secret[]是注意secretValues里放的不是明文密钥而是哈希——明文密钥只出现在客户端请求里。第一步生成密钥的哈希文档示例用htpasswd生成 Bcrypt 哈希-b批处理读参数、-n不写文件直接输出、-B指定 Bcrypt-nbB foo表示空用户名、密码为foohtpasswd -nbB foo | cut -c 2- # 输出示例文档示例你的环境会生成不同的哈希 # $2y$05$D4SPFxzfWKcx1OXfVhRbvOTH/QB0Lm6AXTk8.NOmU4rPLX2t6UUuWcut -c 2-是去掉htpasswd输出的:哈希前缀只保留哈希本身。第二个密钥同理htpasswd -nbB bar | cut -c 2- # 输出示例文档示例 # $2y$05$HbLL.g5dUqJippH0RuAGL.RaM9wNS2cT7hp6.vbv5okdCmVBSDzzK文档明确支持的哈希算法是 Bcrypt、SHA1 和 MD5。这里生成的哈希会写进 Secret对应的明文密钥foo、bar交给调用方之后请求时携带。第二步把哈希存入 Kubernetes Secret按 参考文档 的示例Secret 中每个 key 对应一个密钥的哈希apiVersion: v1 kind: Secret type: Opaque metadata: name: apikey namespace: whoami stringData: secret: $2y$05$D4SPFxzfWKcx1OXfVhRbvOTH/QB0Lm6AXTk8.NOmU4rPLX2t6UUuW # htpasswd -nbB foo | cut -c 2- othersecret: $2y$05$HbLL.g5dUqJippH0RuAGL.RaM9wNS2cT7hp6.vbv5okdCmVBSDzzK # htpasswd -nbB bar | cut -c 2-上面是文档原样示例两个哈希均为文档示例值实际请替换为你自己第一步生成的哈希。Secret 里的 key 名secret、othersecret可以自定它们将出现在下一步的 URN 引用中。第三步创建 Middleware 引用这些哈希Middleware 以 CRD 形式声明插件部分位于spec.plugin.apiKey下仍然是 参考文档 的原文示例apiVersion: traefik.io/v1alpha1 kind: Middleware metadata: name: test-apikey namespace: apps spec: plugin: apiKey: keySource: headerAuthScheme: Bearer header: Authorization secretNonBase64Encoded: true secretValues: - urn:k8s:secret:apikey:secret - urn:k8s:secret:apikey:othersecret这份配置的含义keySource.header: Authorization加上headerAuthScheme: Bearer客户端把密钥放在Authorization头、以Bearerscheme 前缀携带即Authorization: Bearer 密钥。secretNonBase64Encoded: true客户端发送的是明文密钥网关直接与其哈希比对不需要 base64 解码。secretValues用 URN 格式urn:k8s:secret:[name]:[valueKey]指向 Secret[name]是 Secret 名[valueKey]是其中的 key。两个条目对应第二步 Secret 里的两个密钥任意一个匹配即通过。如果你的客户端通过 URL 参数传密钥把keySource换成query: 参数名通过 cookie 则用cookie: 名称。三选一即可。用kubectl apply应用到集群应用方式与 Kubernetes 中间件使用文档 中的kubectl apply -f middlewares.yaml一致。如果你的实例尚未启用该插件扩展文档 说明给 Traefik 添加新插件必须修改该实例的 install静态配置每个插件的 Install 小节会提供静态配置示例具体moduleName、version等以插件自身的安装说明为准。静态配置中插件描述的字段结构可参考 静态配置参考 的experimental.plugins段落含moduleName、version、settings等字段。同时该文档提示插件属于实验性功能Plugins can change the behavior of Traefik in unforeseen ways在生产实例上启用新插件时需谨慎。第四步在路由上引用中间件中间件创建后需要挂到实际处理 API 流量的路由上。按 Kubernetes 中间件文档在 IngressRoute 的routers下通过middlewares引用entryPoints: - web middlewares: - name: test-apikey引用名即第三步 Middleware 的metadata.name。文档同时说明 Gateway API 场景可用HTTPRoute的ExtensionReffilter 引用 Traefik 中间件作为替代路径。验证带密钥与不带密钥各发一次请求验证依据的是文档对机制的描述中间件要求密钥经由所配置的载体本例为Authorization头提供没有密钥的请求过不了这道中间件。用第一步的明文密钥foo发请求api.example替换为你的 API 入口地址curl -H Authorization: Bearer foo http://api.example/api/health密钥匹配时请求应被放行并收到后端服务的响应换成不存在的密钥或不带Authorization头再发一次请求应被中间件拦截、到达不了后端。参考文档没有给出拦截响应的具体状态码或正文内容以你的实际网关返回为准判断标准是能否到达后端。bar对应 Secret 中othersecret的哈希同样有效可用来确认多个secretValues条目都生效。限制与注意仅限 Traefik Hub这是文档开头明确标注的OSS 用户看不到该中间件可用。存哈希不存明文secretValues接受 Bcrypt、SHA1、MD5 哈希且必须由htpasswd生成Secret 被泄露时明文密钥本身不外泄但仍应轮换密钥并重新生成 Secret。密钥更换即改 Secret新密钥重新走生成哈希 → 更新 Secret → 路由引用不变的流程即可Middleware 配置无需改动。插件为实验性功能在生产环境启用前参照 扩展文档 的风险提示评估。配置完成并验证通过后这套机制就固定下来了调用方凭Authorization: Bearer 密钥访问网关凭 Secret 中的哈希放行不需要在应用层重复实现鉴权。【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefik创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考