Ceph cephadm OAuth2 Proxy 服务部署实战：基于 OIDC 的统一认证网关与 SSO 接入指南

Ceph cephadm OAuth2 Proxy 服务部署实战基于 OIDC 的统一认证网关与 SSO 接入指南【免费下载链接】cephCeph is a distributed object, block, and file storage platform项目地址: https://gitcode.com/gh_mirrors/ce/ceph导读本文围绕 Ceph 官方文档 oauth2-proxy.rst 展开系统讲解自 Tentacle 版本起引入的oauth2-proxy服务它作为认证网关与外部身份提供商IDP通过 OIDCOpenID Connect协议对接为 Ceph Dashboard、监控栈等 Ceph 应用提供统一的登录认证与单点登录SSO能力。读完本文你将掌握oauth2-proxy服务的部署命令、完整的 YAML 服务规范Service Specification、各字段的含义与校验规则以及它与mgmt-gateway协同实现高可用和自动化的底层原理。oauth2-proxy 服务概述从 Ceph Tentacle 版本开始cephadm 引入了oauth2-proxy服务为 Ceph 应用提供一种更高级的认证与访问控制方式。该服务基于开源的oauth2-proxy项目与外部身份提供商Identity Providers, IDPs集成通过 OIDC 协议提供安全、灵活的认证能力。在整体架构中oauth2-proxy扮演认证网关authentication gateway的角色它拦截对 Ceph 应用的访问请求将未认证用户重定向到 IDP 完成登录登录成功后管理会话令牌再将用户带回目标应用。这样一来包括Ceph Dashboard 与监控栈Prometheus、Alertmanager、Grafana在内的所有 Ceph 应用的访问都受到严格管控。部署命令非常简单ceph orch apply oauth2-proxy [--placement ...] ...一旦应用该服务cephadm 会自动重新配置相关组件使其改用oauth2-proxy进行认证从而保护所有 Ceph 应用的访问。服务会处理登录流程、将用户重定向到合适的 IDP 进行认证并管理会话令牌以提供流畅的用户访问体验。核心价值安全、SSO 与集中式认证原文档总结了该服务的三大收益增强的安全性Enhanced Security通过与外部 IDP 集成、基于 OIDC 协议提供健壮的认证能力无缝 SSOSeamless SSO在全部 Ceph 应用间实现单点登录改善用户访问控制体验集中式认证Centralized Authentication将认证管理集中化降低复杂度、提升访问管控力。从安全增强角度看oauth2-proxy服务确保所有对 Ceph 应用的访问都经过认证阻止未授权用户接触敏感信息。由于复用了oauth2-proxy开源项目的能力该服务可以轻松对接多种外部 IDPOIDC/OAuth2 提供商提供安全而灵活的认证机制。在实现上服务内部将 IDP 配置为provider oidc并通过oidc_issuer_url指向发行方Issuer端点由 IDP 负责签发和校验 JWT 令牌详见下文源码剖析。高可用架构与 mgmt-gateway 协同oauth2-proxy通常与mgmt-gateway服务配合使用oauth2-proxy可以部署为多个无状态实例stateless instancesmgmt-gateway基于 NGINX 的反向代理负责在这些实例之间以round-robin轮询策略做负载均衡由于oauth2-proxy对接的是外部 IDP登录环节的高可用由外部 IDP 保障不属于该服务的职责范围。这一设计在源码中有清晰印证mgmt-gateway 的 nginx.conf.j2 模板会根据oauth2_proxy_endpoints动态生成upstream oauth2_proxy_servers服务器组external_server.conf.j2 则把/oauth2/路径代理到该 upstream并对受保护资源执行auth_request /oauth2/auth、error_page 401 /oauth2/sign_in即把未认证请求转交给 oauth2-proxy 触发登录流程。部署后的访问流程完成oauth2-proxy部署后对 Ceph 应用的访问都将要求通过已配置的 IDP 完成认证用户访问受保护的 Ceph 应用如 Dashboard请求被重定向至 IDP 登录页用户登录成功后被引导返回最初请求的应用oauth2-proxy校验令牌、建立会话后续请求通过会话 Cookie 放行。这套流程与 Ceph 管理栈无缝集成既保证了安全访问也统一了登录体验。Service Specification完整服务规范前置条件先启用带认证的 mgmt-gateway部署oauth2-proxy之前请务必先部署mgmt-gateway服务并打开--enable_auth标志ceph orch apply mgmt-gateway --enable_authtruemgmt-gateway是 Ceph 应用Dashboard 与监控栈的单一前端入口其完整部署细节可参考 mgmt-gateway.rst。只有先启用认证的网关oauth2-proxy才能作为其后端认证组件被正确代理与编排。YAML 规范示例oauth2-proxy服务可以通过一份 YAML 规范specification来定义完整示例继承自原文档service_type: oauth2-proxy service_id: auth-proxy placement: label: mgmt spec: https_address: 0.0.0.0:4180 provider_display_name: My OIDC Provider client_id: your-client-id oidc_issuer_url: http://192.168.100.1:5556/dex client_secret: your-client-secret cookie_secret: your-cookie-secret ssl_certificate: | -----BEGIN CERTIFICATE----- MIIDtTCCAp2gAwIBAgIYMC4xNzc1NDQxNjEzMzc2MjMyXzxvQ7EcMA0GCSqGSIb3 DQEBCwUAMG0xCzAJBgNVBAYTAlVTMQ0wCwYDVQQIDARVdGFoMRcwFQYDVQQHDA5T [...] -----END CERTIFICATE----- ssl_certificate_key: | -----BEGIN PRIVATE KEY----- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC5jdYbjtNTAKW4 /CwQr/7wOiLGzVxChn3mmCIF3DwbL/qvTFTX2d8bDf6LjGwLYloXHscRfxszX/4h [...] -----END PRIVATE KEY-----通过如下命令应用该规范ceph orch apply -i oauth2-proxy.yaml规范一旦可用cephadm 会自动重新部署mgmt-gateway服务并调整其配置把认证请求重定向到新部署的oauth2-proxy服务上。spec 字段详解OAuth2ProxySpecoauth2-proxy服务规范的类型定义位于源码 service_spec.py 中的OAuth2ProxySpec。各字段含义、默认值及校验规则如下字段必填含义与默认值https_address否HTTPS 监听地址格式为host:port默认0.0.0.0:4180。校验要求包含合法主机名/IP 与 0~65535 端口provider_display_name是在 UI 中展示的身份提供商名称client_id是与 IDP 认证使用的客户端 IDclient_secret是与 IDP 认证使用的客户端密钥oidc_issuer_url是OIDC Issuer 的 URL必须是含 scheme 与 netloc 的合法 URLredirect_url否登录成功后的重定向地址未配置时 cephadm 自动计算为mgmt-gateway 外部端点/oauth2/callbackscope否OAuth scope 列表未配置时使用默认 scopecookie_secret否用于签名/加密 Cookie 的密钥长度必须是16、24 或 32 字节用于创建 AES 密码未配置时自动生成 32 字节随机 base64 密钥email_domains否允许访问的邮箱域名白名单列表allowlist_domains否登录/登出后允许安全重定向的域名白名单防止未授权重定向未配置时 cephadm 会自动把mgmt-gateway的 IP 与主机名追加进去ssl_insecure_skip_verify否跳过对 OIDC 提供方的 TLS 校验默认false仅限非生产环境ssl/ssl_cert/ssl_key/certificate_source/custom_sans否TLS 证书相关配置由基类ServiceSpec提供支持自定义 SAN 与证书来源extra_container_args/extra_entrypoint_args/custom_configs否追加容器/入口参数与自定义配置文件校验逻辑在OAuth2ProxySpec.validate()中实现要点如下必填字段为provider_display_name、oidc_issuer_url、client_id、client_secret缺失任一字段都会抛出SpecValidationError错误信息形如Missing required fields for oauth2-proxy: ...cookie_secret先尝试按 base64 解码后计算字节长度若解码失败则按 UTF-8 明文计算长度长度不在 {16, 24, 32} 中即报错oidc_issuer_url、redirect_url必须是合法 URL含 scheme 与 netlochttps_address必须是[IP|hostname]:port格式且端口在 0~65535 范围内。这些校验行为被单元测试覆盖见 test_service_spec.py 中的test_oauth2_proxy_missing_required_fields参数化用例逐一验证缺字段时的报错信息。源码级原理剖析配置模板生成cephadm 的 mgr 模块通过 services/oauth2_proxy.py 中的OAuth2ProxyService生成守护进程配置渲染模板为 oauth2-proxy.conf.j2最终产出三个必需文件oauth2-proxy.conf主配置oauth2-proxy.crt/oauth2-proxy.keyTLS 证书与私钥由 cephadm 的证书管理模块get_certificates()提供。从模板内容可以看到实际下发给 oauth2-proxy 的关键运行参数https_address默认0.0.0.0:4180与provider oidcskip_provider_button、skip_jwt_bearer_tokensCookie 相关cookie_samesite none兼容 Chrome 等对第三方 Cookie 管控更严格的浏览器、cookie_secure true、cookie_expire 5h、cookie_refresh 2h透传与头信息pass_access_token、pass_authorization_header、pass_basic_auth、pass_user_headers、set_xauthrequest true这正是 mgmt-gateway 中auth_request机制所依赖的 X-Auth-Request 头访问控制email_domains默认*表示不限制、whitelist_domains即 spec 中的allowlist_domainscephadm 会自动并入 mgmt-gateway 的地址见generate_config()。redirect_url的自动计算逻辑在get_redirect_url()中若 spec 未显式配置则取 mgmt-gateway 外部端点拼上/oauth2/callback。同时OAuth2ProxyService.get_dependencies()将mgmt-gateway的守护进程声明为依赖确保在网关就绪后才计算回调地址。守护进程部署细节守护进程侧由 src/cephadm/cephadmlib/daemons/oauth2_proxy.py 中的OAuth2Proxy类负责容器化编排daemon_type oauth2-proxy启动参数固定为--config/etc/oauth2-proxy.conf --tls-cert-file/etc/oauth2-proxy.crt --tls-key-file/etc/oauth2-proxy.key容器内以nobody用户UID_NOBODY/GID_NOGROUP运行三个配置文件通过卷挂载注入容器支持在容器内执行oauth2-proxy --version探测版本号容器镜像默认值为quay.io/oauth2-proxy/oauth2-proxy:v7.6.0定义于 images.py。Dashboard SSO 联动mgr 模块在 module.py 中通过apply_oauth2_proxy()受理编排请求。当最后一个oauth2-proxy守护进程被移除时post_remove()会自动调用 Dashboard 模块的disable_oauth2_sso关闭 Dashboard 的 OAuth2 SSO前提是 Dashboard 模块已加载且sso_oauth2选项开启避免留下不可用的认证配置。监控栈的 Grafana 配置也会根据oauth2_enabled决定是否启用enable_basic_auth见 services/monitoring.py从而在 OAuth2 生效时自动关闭基础认证。限制与注意事项原文档明确列出了一系列重要限制非穷尽清单oauth2-proxy自身不支持高可用配置——其 HA 依赖 mgmt-gateway 的负载均衡与外部 IDP 的可用性IDP 与 OAuth2 参数必须正确配置错误配置会直接导致认证失败、访问异常IDP 必须在签发的 JWT 令牌中包含jti声明claim因为 Ceph Dashboard 依赖该值校验令牌有效性若oauth2-proxy服务宕机cephadm 会自动禁用 Dashboard 的 OAuth2 SSO。容器镜像管理oauth2-proxy服务使用的容器镜像可通过以下命令查询ceph config get mgr mgr/cephadm/container_image_oauth2_proxy管理员可以通过修改 cephadm 模块选项container_image_oauth2_proxy指定自定义镜像。如果已有守护进程在运行修改镜像后必须重新部署守护进程使其生效ceph config set mgr mgr/cephadm/container_image_oauth2_proxy new-oauth2-proxy-image ceph orch redeploy oauth2-proxy小结oauth2-proxy服务把外部 OIDC 身份提供商的能力引入 Ceph 管理栈配合mgmt-gateway构成了网关统一入口 认证网关的现代安全架构无状态多实例部署、NGINX 轮询负载均衡、JWT 令牌校验、Cookie 会话管理以及 Dashboard SSO 的自动启停均由 cephadm 编排完成。实际操作时只需记住三条主线先以--enable_authtrue部署mgmt-gateway再通过 YAML 规范务必填齐四个必填字段并保证cookie_secret为 16/24/32 字节应用oauth2-proxy最后按需通过模块选项管理镜像与重部署。【免费下载链接】cephCeph is a distributed object, block, and file storage platform项目地址: https://gitcode.com/gh_mirrors/ce/ceph创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考