8gears/keycloak-auth-proxy

Keycloak Auth Proxy

镜像概述

该镜像提供反向OpenID Connect/OAuth认证与授权服务，适用于无法或不愿自行实现认证功能的HTTP服务。基于https://github.com/gambol99/keycloak-proxy%EF%BC%88Java/Undertow%E8%A7%A3%E5%86%B3%E6%96%B9%E6%A1%88%EF%BC%89%EF%BC%8C%E6%94%AF%E6%8C%81Keycloak%E5%8F%8A%E5%85%B6%E4%BB%96OpenID Connect提供者，可通过环境变量配置，轻松部署到Docker、Kubernetes或OpenShift环境。

核心功能

1. 反向代理与认证：拦截外部流量，根据配置判断是否需要认证，引导用户到IAM（如Keycloak）完成登录。
2. 灵活配置：支持三种配置方式——环境变量、自定义模板+环境变量、自定义proxy.json文件。
3. 多环境支持：适配Docker、Kubernetes、OpenShift等主流部署环境。
4. 权限校验：登录成功后，根据配置检查用户是否有权访问目标路径。

使用场景

1. 保护静态网站：限制未认证用户访问静态内容（如静态文档、生成的网站）。
2. 外包认证流程：将认证/授权步骤委托给代理，上游应用仅需依赖转发的HTTP头（含用户名/权限信息）。

配置说明

1. 使用默认模板运行

仅需设置必填环境变量，启动时自动合并到默认配置：

sh
docker run -ti \
-e TARGET_URL=http://your-upstream-service:port \
-e REALM=your-realm \
-e REALM_PUBLIC_KEY=your-public-key \
-e AUTH_SERVER_URL=http://keycloak-server:8080/auth \
-e RESOURCE=your-client-id \
-e SECRET=your-client-secret \
8gears/keycloak-auth-proxy

Docker Compose示例：

sh
# 下载默认docker-compose.yml
wget https://raw.githubusercontent.com/8gears/keycloak-auth-proxy/master/docker-compose.yml
# 修改必填变量后启动
docker-compose up

2. 使用自定义模板运行

自定义proxy.tmpl模板，压缩后通过PROXY_TMPL变量传入：

sh
docker run -ti \
-e PROXY_TMPL='{"target-url":"http://upstream:port","bind-address":"0.0.0.0",...}' \
-e TARGET_URL=http://upstream:port \
-e REALM=your-realm \
... \
8gears/keycloak-auth-proxy

3. 使用自定义配置文件运行

将proxy.json挂载到/app/proxy.json：

sh
docker run -v ./proxy.json:/app/proxy.json 8gears/keycloak-auth-proxy

或通过PROXY_JSON变量传入配置内容。

环境变量说明

必填变量：

• TARGET_URL：上游服务URL
• REALM：Keycloak领域名称
• REALM_PUBLIC_KEY：领域公钥
• AUTH_SERVER_URL：Keycloak服务器地址
• RESOURCE：客户端ID
• SECRET：客户端密钥

可选变量：

• HTTP_PORT：代理绑定端口（默认8080）
• BASE_PATH：基础路径（默认/）
• CONSTRAINT_PATH：受保护路径（默认/*，多路径用;分隔）
• PROXY_TMPL：自定义配置模板

OpenShift部署

从模板创建服务

通过CLI导入模板并部署：

sh
# 查看参数列表
oc process --parameter -f https://raw.githubusercontent.com/8gears/keycloak-auth-proxy/master/openshift_template.yml
# 部署服务
oc process -f https://raw.githubusercontent.com/8gears/keycloak-auth-proxy/master/openshift_template.yml \
-p TARGET_URL=http://service-name:port \
-p REALM=your-realm \
| oc create -f -

导入到服务目录

导入到当前命名空间：

sh
oc create -f https://raw.githubusercontent.com/8gears/keycloak-auth-proxy/master/openshift_template.yml

导入到全局目录（所有用户可见）：

sh
oc create -f https://raw.githubusercontent.com/8gears/keycloak-auth-proxy/master/openshift_template.yml -n openshift

替代方案

• https://github.com/gambol99/keycloak-proxy%EF%BC%9AGolang%E5%AE%9E%E7%8E%B0%E7%9A%84Keycloak%E4%BB%A3%E7%90%86
• https://github.com/bitly/oauth2_proxy%EF%BC%9A%E9%80%9A%E7%94%A8OAuth2%E4%BB%A3%E7%90%86
• https://github.com/pingidentity/lua-resty-openidc%EF%BC%9ANginx/OpenResty%E7%9A%84OIDC%E5%BA%93