Caddy Security 多租户OIDC认证配置实践指南

背景概述

在Caddy Security项目中，用户经常需要实现基于不同身份提供者(Identity Provider)的多租户认证场景。本文将以Pocket-ID作为OIDC提供者为例，详细介绍如何配置Caddy Security实现精细化访问控制。

核心配置方案

方案一：多OIDC客户端模式

该方案适用于需要完全隔离的认证体系场景，通过创建多个独立的OIDC客户端实现权限分离：

security {
    # 管理员专用OIDC配置
    oauth identity provider admin {
        realm admin
        driver generic
        client_id ADMIN_CLIENT_ID
        client_secret ADMIN_SECRET
        scopes openid email profile
        base_auth_url https://login.example.net/authorize
        metadata_url https://login.example.net/.well-known/openid-configuration
    }

    # 普通用户OIDC配置
    oauth identity provider user {
        realm user
        driver generic
        client_id USER_CLIENT_ID
        client_secret USER_SECRET
        scopes openid email profile
        base_auth_url https://login.example.net/authorize
        metadata_url https://login.example.net/.well-known/openid-configuration
    }

    authentication portal myportal {
        enable identity provider admin
        enable identity provider user
        
        transform user {
            match realm admin
            action add role admin
        }
        
        transform user {
            match realm user
            action add role user
        }
    }
}

方案二：单OIDC客户端+角色分组模式

更简洁的配置方案，利用单个OIDC客户端配合声明中的groups字段实现角色分配：

security {
    oauth identity provider pocket-id {
        scopes openid email profile groups  # 关键：包含groups声明
        ...
    }

    authorization policy admin_policy {
        allow roles admin
        inject headers with claims
    }

    authorization policy user_policy {
        allow roles user
        inject headers with claims
    }
}

最佳实践建议

1. 会话管理：合理设置token生命周期（如86400秒），平衡安全性与用户体验

2. 防御配置：每个授权策略末尾应添加deny指令，防止权限绕过：

authorization policy strict_policy {
    allow roles admin
    deny  # 显式拒绝其他所有请求
}

3. 地理围栏：可结合MaxMind数据库实现地域访问控制：

@geo_filter {
    maxmind_geolocation {
        db_path "/path/to/GeoLite2-Country.mmdb"
        allow_countries US
    }
}

典型问题解决

角色冲突问题：当用户需要同时具备多种角色时，建议：

1. 在Pocket-ID中配置用户多组隶属关系
2. 使用声明转换器合并角色：

transform user {
    match claim groups admin
    action add role superuser
}

部署架构建议

对于生产环境，推荐采用以下结构：

全局配置
├── 公共OIDC参数
├── 共享认证门户
└── 站点特定配置
    ├── 管理后台（admin角色）
    └── 用户门户（user角色）

通过模块化设计，可以使用Caddy的import指令实现配置复用，大幅提升维护效率。

总结