itzg/saml-auth-proxy

saml-auth-proxy 镜像文档

镜像概述

saml-auth-proxy是一个轻量级SAML Service Provider (SP)认证代理，通过反向代理模式为后端Web服务提供SAML 2.0认证能力。该镜像能够无缝集成SAML单点登录(SSO)流程，无需修改后端服务代码，即可实现与企业身份提供商(IdP)的认证集成。

核心功能与特性

• SAML 2.0合规：完整支持SAML 2.0协议标准，兼容主流身份提供商(IdP)如Okta、Azure AD、Keycloak、ADFS等
• 透明反向代理：认证通过后自动转发请求至后端服务，并维护用户会话
• 会话管理：支持基于加密Cookie的会话维持，可配置会话超时策略
• 灵活配置：通过环境变量或配置文件实现SAML参数、代理规则和安全策略的自定义
• 证书管理：支持自动生成或导入SP证书，简化部署流程

适用场景

• 为不原生支持SAML的遗留Web服务添加SSO认证
• 企业内部系统统一身份认证改造
• 多服务环境下的单点登录集成部署
• 快速为开发测试环境添加临时认证层

使用方法

基础部署（Docker Run）

bash
docker run --name saml-auth-proxy \
  -p  proxy_port>: proxy_port> \
  -e PROXY_TARGET_URL="<backend_service_url>" \
  -e SAML_IDP_METADATA_URL="<idp_metadata_url>" \
itzg/saml-auth-proxy

Docker Compose部署示例

yaml
version: '3.8'

services:saml-auth-proxy:
    imageitzg/saml-auth-proxy
    ports
proxy_port>: proxy_port>\environment
PROXY_TARGET_URL=http://backend-service:8080
SAML_IDP_METADATA_URL=https://idp.example.com/metadata
SAML_SP_ENTITY_ID=https://proxy.example.com/sp
SAML_SP_ASSERTION_CONSUMER_SERVICE_URL=https://proxy.example.com/login/callbackSAML_SP_PRIVATE_KEY_PATH=/certs/sp-key.pem
SAML_SP_CERTIFICATE_PATH=/certs/sp-cert.pem
SESSION_COOKIE_SECURE=true
SESSION_DURATION=PT8Hvolumes
./sp-certs:/certsdepends_on
backend-servicebackend-service:
    image: your-backend-service:latest
    # 后端服务配置...

关键配置参数

核心代理配置

| 环境变量 | 描述 | 示例值 sp_port> | |---------------------------|"[]> | PROXY_TARGET_URL # 后端服务完整URL []"

SAML SP配置

| 参数 | 描述 sp_entity_id> | |-------------------------------|"urn:example:proxy:sp" SAML_SP_ENTITY_ID # SP实体唯一标识符 "[]" SAML_SP_ASSERTION_CONSUMER_SERVICE_URL | SAML断言消费端点URL "/certs/sp-cert.pem" SAML_SP_CERTIFICATE_PATH # SP公钥证书路径 "/certs/sp-key.pem" SAML_SP_PRIVATE_KEY_PATH # SP私钥路径 "[]"SAML_SP_SINGLE_LOGOUT_SERVICE_URL | 单点登出端点URL

SAML IdP配置

| 参数 # IdP Metadata XML文档URL "[***]" SAML_IDP_METADATA_URL | IdP签名验证证书路径（可选） "/certs/idp-cert.pem" SAML_IDP_CERTIFICATE_PATH | IdP唯一标识符（可选，如果metadata不可用） | "urn:saml:idp:example.com"SAML_IDP_ENTITY_ID

会话配置

| 参数 # 是否启用Secure Cookie标志 true SESSION_COOKIE_SECURE=true | 会话有效期（ISO 8601格式） PT "SESSION_DURATION PT8H
SESSION_COOKIE_NAME # 用户会话Cookie名称 "_saml_session"

完整文档参考Official Documentation](https://github.comitzg/saml-auth-proxy)%E8%8E%B7%E5%8F%96%E5%AE%8C%E6%95%B4%E9%85%8D%E7%BD%AE%E8%AF%B4%E6%98%8E%E9%AB%98%E7%BA%A7%E7%94%A8%E6%B3%95%E7%A4%BA%E4%BE%8B%E5%92%8C%E6%95%85%E9%9A%9C%E6%8E%92%E9%99%A4%E6%8C%87%E5%8D%97