finbourne/oidc-ingress

oidc-ingress

镜像概述

oidc-ingress是一个基于OIDC和cookies的webhook认证服务，旨在为Kubernetes环境中运行在Nginx Ingress控制器后的任何服务轻松添加OIDC认证。通过使用cookies实现认证机制，无需对客户端进行任何修改，即可使遗留系统或服务接入认证流程。

核心功能与特性

• OIDC认证集成：通过OIDC协议对接身份提供商，实现标准化认证
• 无客户端修改：基于cookies的认证机制，无需调整后端服务代码
• 遗留系统支持：兼容各类无法进行客户端改造的传统应用
• Kubernetes适配：专为Nginx Ingress控制器设计，无缝集成Kubernetes环境
• 灵活配置：支持多OIDC客户端配置，可自定义作用域、Cookie参数等

使用场景

适用于Kubernetes集群中需要为通过Nginx Ingress暴露的服务添加身份认证的场景，尤其适合：

• 需保护内部服务但无法修改服务代码的场景
• 遗留系统的认证接入需求
• 需统一身份认证策略的多服务环境

配置说明

环境变量与命令行参数

客户端配置（Clients）

Clients配置需通过环境变量或命令行参数提供，为YAML格式字符串。示例配置如下：

yaml
- profile: name-of-app          # 应用配置名称
  provider: https://oauth.provider.url/  # OIDC提供商URL
  clientid: client_id           # OIDC客户端ID
  clientsecret: client_secret   # OIDC客户端密钥
  noredirect: false             # 是否禁用重定向URL中的?rd参数（默认：false）
  scopes:                       # OIDC请求作用域（默认：- openid）
    - openid
    - email
    - profile
  cookieDomain: example.com     # Cookie域名
  cookieSecret: super-secret-stuff-used-to-encrypt-the-cookie  # Cookie加密密钥

注意：noredirect参数可抑制路径中的?rd={redirect url}，适用于Azure AD等会剥离查询字符串且要求重定向URL完全匹配的场景。

构建与测试

构建

console
$ make build
$ ./bin/oidc-ingress

测试

console
$ make test

当前测试用例较少，后续将补充完善。

TODO列表

• 添加全面的测试用例集
• 补充ETCD使用说明
• 补充ExternalUrl参数说明
• 将哈希功能扩展为完整加密
• 统一日志格式
• 集成OKTA JWT验证库（https://github.com/okta/okta-jwt-verifier-golang%EF%BC%89%E4%BB%A5%E6%94%AF%E6%8C%81JWT%E9%AA%8C%E8%AF%81