Caddy-Security项目：OAuth认证后代理转发配置指南

背景介绍

在企业级应用中，经常需要将身份认证与后端服务代理结合使用。Caddy-Security作为Caddy服务器的安全插件，提供了强大的OAuth集成能力。本文将以ADFS（Active Directory Federation Services）为例，讲解如何配置Caddy-Security实现OAuth认证后的代理转发。

核心配置解析

1. OAuth身份提供者配置

配置ADFS作为OAuth提供者时，需要设置以下关键参数：

• client_id和client_secret：OAuth客户端凭证
• scopes：请求的权限范围（openid/email/profile）
• base_auth_url和metadata_url：ADFS服务端点

oauth identity provider generic {
    realm generic
    driver generic
    client_id oauth-client-id
    client_secret oauth-client-secret
    scopes openid email profile
    base_auth_url https://my.company.org/adfs
    metadata_url https://my.company.org/adfs/.well-known/openid-configuration
}

2. 认证门户配置

认证门户负责处理用户登录流程，关键配置包括：

• 令牌生命周期设置（3600秒）
• Cookie域配置
• 用户角色转换规则
• 自定义UI链接

authentication portal myportal {
    crypto default token lifetime 3600
    enable identity provider generic
    cookie domain subdomain.my.company.org
    ui {
        links {
            "应用入口" "/app/" icon "las la-user"
        }
    }
    transform user {
        match realm generic
        action add role authp/user
    }
}

3. 授权策略配置

授权策略定义了访问控制规则：

• 设置认证URL
• 注入声明头信息
• 允许的角色列表

authorization policy mypolicy {
    set auth url /auth
    inject headers with claims
    allow roles authp/admin authp/user
}

路由配置要点

1. 认证路由

专门处理认证请求的路由应独立配置：

route /auth* {
    authenticate with myportal
}

2. 代理路由

主路由配置需注意：

• 先进行全局认证
• 然后应用授权策略
• 最后代理到后端服务

route /* {
    authorize with mypolicy
    reverse_proxy localhost:8080 {
        header_up Host localhost:8080
        header_up X-Real-IP {http.request.header.x-forwarded-for}
    }
}

常见问题解决方案

1. 认证后空白页面问题： 确保在认证门户中配置了UI链接，为用户提供明确的导航入口。

2. 代理不生效问题： 检查路由顺序是否正确，确保authorize指令在reverse_proxy之前。

3. 头信息传递问题： 使用header_up确保必要的头信息（如Host和真实IP）正确传递给后端服务。

最佳实践建议

1. 模块化配置：将不同功能的路由分开配置，提高可维护性。

2. 安全加固：

   • 设置合理的令牌有效期
   • 限制Cookie的作用域
   • 使用HTTPS协议

3. 用户体验优化：

   • 添加有意义的UI链接
   • 考虑实现条件登录逻辑
   • 提供清晰的错误提示

通过以上配置，可以实现一个安全、可靠的企业级认证代理方案，既保障了安全性，又提供了良好的用户体验。