Authelia 与 openCloud 集成指南基于 OpenID Connect 1.0 的多端 SSO 配置详解【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia本篇技术指南面向需要在 Authelia 与 openCloud欧盟开源的云存储与协作平台之间搭建单点登录SSO的运维与开发者。文章以 Authelia 作为 OpenID Connect 1.0 提供方OP、openCloud 作为依赖方RP的官方集成文档为主体完整覆盖 Authelia 端四类客户端Web、Android、iOS、桌面端的注册配置、openCloud 端环境变量与 Docker Compose 部署配置、CSP 与角色映射等附加文件并结合仓库源码解析public、require_pkce、token_endpoint_auth_method等关键参数的底层行为帮助读者一次性掌握从配置到排障的完整链路。测试版本与适用前提该集成方案基于以下版本完成验证见 openCloud 集成文档Autheliav4.39.24openCloudv7.2.2集成文档假定以下前提环境项目默认值应用根 URLopenCloudhttps://opencloud.example.comAuthelia 根 URLhttps://auth.example.comWeb 客户端 IDopencloudAndroid 客户端 IDopencloud-androidiOS 客户端 IDopencloud-ios桌面客户端 IDopencloud-desktop上述example.com等值在官方文档中通过站点变量sitevar自动替换实际部署时应替换为你的真实域名。在动手前请先阅读 OpenID Connect 1.0 集成总览 与 OpenID Connect 1.0 客户端配置了解 Authelia 作为 OP 的端点、授权策略与注册客户端的基本概念。通用注意事项Before You Begin官方每个客户端集成文档都会嵌入一组通用前置须知见 oidc-common 短代码与 openCloud 集成相关的主要有三点client_id必须全局唯一每个客户端必须使用不同的 Client ID本文示例值仅用于演示生产环境建议使用 64 位随机字符且只能包含 RFC3986 非保留字符unreserved characters长度不得超过 100 字符。client_secret建议以哈希形式存储明文存储虽仍被支持但已被标记为弃用当以哈希存储时过高的哈希成本可能造成客户端请求超时需要参照 FAQ 调整 work factor。仅提供客户端注册片段示例只包含clients部分的配置你仍必须配置 OpenID Connect 1.0 Provider 配置 中的必需元素如issuer、密钥等。Authelia 端注册 openCloud 的四个 OIDC 客户端openCloud 的 Web 门户与各原生客户端需要分别注册为独立的 OIDC 客户端。以下是官方文档提供的完整配置写入 Authelia 的configuration.ymlidentity_providers: oidc: clients: - client_id: opencloud client_name: openCloud public: true authorization_policy: two_factor require_pkce: true pkce_challenge_method: S256 scopes: - openid - offline_access - groups - profile - email redirect_uris: - https://opencloud.example.com/ - https://opencloud.example.com/oidc-callback.html - https://opencloud.example.com/oidc-silent-redirect.html response_types: - code grant_types: - authorization_code - refresh_token access_token_signed_response_alg: RS256 userinfo_signed_response_alg: none token_endpoint_auth_method: none - client_id: opencloud-android client_name: openCloud public: true authorization_policy: two_factor require_pkce: true pkce_challenge_method: S256 redirect_uris: - oc://android.opencloud.eu scopes: - openid - offline_access - groups - profile - email response_types: - code grant_types: - authorization_code - refresh_token access_token_signed_response_alg: RS256 userinfo_signed_response_alg: none token_endpoint_auth_method: none - client_id: opencloud-desktop client_name: openCloud public: true authorization_policy: two_factor require_pkce: true pkce_challenge_method: S256 scopes: - openid - offline_access - groups - profile - email redirect_uris: - http://127.0.0.1 - http://localhost response_types: - code grant_types: - authorization_code - refresh_token access_token_signed_response_alg: RS256 userinfo_signed_response_alg: none token_endpoint_auth_method: none - client_id: opencloud-ios client_name: openCloud public: true authorization_policy: two_factor require_pkce: true pkce_challenge_method: S256 redirect_uris: - oc://ios.opencloud.eu - oc.ios://ios.opencloud.eu scopes: - openid - offline_access - groups - profile - email grant_types: - authorization_code - refresh_token access_token_signed_response_alg: RS256 userinfo_signed_response_alg: none token_endpoint_auth_method: none关键参数语义与源码依据public: true公开客户端类型openCloud 各客户端均为 SPA 或原生应用无法安全保管client_secret因此按 RFC6749 Section 2.1 中Public字段控制客户端类型公开客户端不允许配置client_secret否则校验失败。token_endpoint_auth_method: none与public: true配套表示在 Token 端点不做客户端认证。对应源码 oidc/client.go 中的GetTokenEndpointAuthMethod当TokenEndpointAuthMethod为空时公开客户端默认回退为none机密客户端默认回退为client_secret_basic。因此该行在实际效果上可以省略但显式写出更利于阅读。require_pkce: true与pkce_challenge_method: S256强制使用 PKCERFC 7636并限定为S256挑战方法。源码 oidc/client.go 中RequirePKCE由config.RequirePKCE || config.PKCEChallengeMethod ! 推导即单独配置pkce_challenge_method也会隐式启用require_pkce。校验器 validator/identity_providers.go 仅接受空值、plain与S256三种取值且推荐S256plain仅在依赖方无法支持S256时使用。authorization_policy: two_factor该客户端授权策略要求用户完成双因素认证可取值one_factor、two_factor或 Provider 级定义的authorization_policies命名策略参见 客户端配置文档。策略在源码 oidc/client_policy.go 中实现通过GetRequiredLevel依据用户 subject 计算所需认证级别。access_token_signed_response_alg: RS256将 Access Token 按 RFC 9068 编码为 JWT使 openCloud 代理层可以无状态地验证令牌对应 openCloud 端PROXY_OIDC_ACCESS_TOKEN_VERIFY_METHODjwt的设置。userinfo_signed_response_alg: noneUserInfo 端点以纯 JSON 返回application/json这是大多数客户端的默认形态。grant_types仅授权authorization_code授权码流程与refresh_token刷新流程offline_access作用域配合refresh_tokengrant 才能签发 Refresh Token。redirect_uris必须精确登记每个客户端实际使用的回调地址大小写敏感且 scheme 只能是http或https自定义 scheme 如oc://同样被接受。桌面客户端使用http://127.0.0.1与http://localhost作为本地回环回调。作用域Scopes与声明Claims所有 openCloud 客户端均请求openid、offline_access、groups、profile、email五个作用域。其语义在 OpenID Connect 1.0 Claims 文档 中有完整定义openid启用 OpenID Connect 语义返回 ID Tokeniss与sub组合是唯一且稳定的用户标识sub为 RFC 4122 UUID v4。offline_access允许获得 Refresh Token用于刷新令牌Authelia 采用单次使用 轮换的 Refresh Token 策略。profile提供name、preferred_username等个人资料声明。email提供email、email_verified、alt_emails声明。groups在 ID Token / UserInfo 中提供用户所属组列表数组openCloud 正是依赖该声明完成组到角色的映射。openCloud 端通过环境变量接入 AutheliaopenCloud 配置外部 IdP 的唯一方式是环境变量。文档给出了.envStandard与 Docker Compose 两种写法两者内容等价按部署方式二选一即可。标准环境变量.envOC_OIDC_ISSUERhttps://auth.example.com PROXY_OIDC_ACCESS_TOKEN_VERIFY_METHODjwt PROXY_OIDC_REWRITE_WELLKNOWNtrue PROXY_AUTOPROVISION_ACCOUNTStrue PROXY_AUTOPROVISION_CLAIM_USERNAMEpreferred_username PROXY_AUTOPROVISION_CLAIM_EMAILemail PROXY_AUTOPROVISION_CLAIM_DISPLAYNAMEname PROXY_AUTOPROVISION_CLAIM_GROUPSgroups PROXY_CSP_CONFIG_FILE_LOCATION/etc/opencloud/csp.yaml WEBFINGER_WEB_OIDC_CLIENT_IDopencloud WEBFINGER_WEB_OIDC_CLIENT_SCOPESopenid profile email groups offline_access WEBFINGER_ANDROID_OIDC_CLIENT_IDopencloud-android WEBFINGER_ANDROID_OIDC_CLIENT_SCOPESopenid profile email groups offline_access WEBFINGER_IOS_OIDC_CLIENT_IDopencloud-ios WEBFINGER_IOS_OIDC_CLIENT_SCOPESopenid profile email groups offline_access WEBFINGER_DESKTOP_OIDC_CLIENT_IDopencloud-desktop WEBFINGER_DESKTOP_OIDC_CLIENT_SCOPESopenid profile email groups offline_access OC_EXCLUDE_RUN_SERVICESidp PROXY_ROLE_ASSIGNMENT_DRIVERoidc GRAPH_ASSIGN_DEFAULT_USER_ROLEfalseDocker Compose 写法services: openCloud: environment: OC_OIDC_ISSUER: https://auth.example.com PROXY_OIDC_ACCESS_TOKEN_VERIFY_METHOD: jwt PROXY_OIDC_REWRITE_WELLKNOWN: true PROXY_AUTOPROVISION_ACCOUNTS: true PROXY_AUTOPROVISION_CLAIM_USERNAME: preferred_username PROXY_AUTOPROVISION_CLAIM_EMAIL: email PROXY_AUTOPROVISION_CLAIM_DISPLAYNAME: name PROXY_AUTOPROVISION_CLAIM_GROUPS: groups PROXY_CSP_CONFIG_FILE_LOCATION: /etc/opencloud/csp.yaml WEBFINGER_WEB_OIDC_CLIENT_ID: opencloud WEBFINGER_WEB_OIDC_CLIENT_SCOPES: openid profile email groups offline_access WEBFINGER_ANDROID_OIDC_CLIENT_ID: opencloud-android WEBFINGER_ANDROID_OIDC_CLIENT_SCOPES: openid profile email groups offline_access WEBFINGER_IOS_OIDC_CLIENT_ID: opencloud-ios WEBFINGER_IOS_OIDC_CLIENT_SCOPES: openid profile email groups offline_access WEBFINGER_DESKTOP_OIDC_CLIENT_ID: opencloud-desktop WEBFINGER_DESKTOP_OIDC_CLIENT_SCOPES: openid profile email groups offline_access OC_EXCLUDE_RUN_SERVICES: idp PROXY_ROLE_ASSIGNMENT_DRIVER: oidc GRAPH_ASSIGN_DEFAULT_USER_ROLE: false环境变量分组解读Issuer 与令牌验证OC_OIDC_ISSUER指向 Authelia 的根 URL同时也是 OIDC IssuerPROXY_OIDC_ACCESS_TOKEN_VERIFY_METHODjwt指示 openCloud 代理以 JWT 方式本地验证 Access Token这与 Authelia 端access_token_signed_response_alg: RS256一一对应PROXY_OIDC_REWRITE_WELLKNOWNtrue重写 OIDC Discovery 元数据。账户自动供给PROXY_AUTOPROVISION_ACCOUNTStrue开启首次登录时依据声明自动创建账户其用户名、邮箱、显示名、组分别取自preferred_username、email、name、groups四个声明。WebFinger 客户端绑定WEBFINGER_*_OIDC_CLIENT_ID与WEBFINGER_*_OIDC_CLIENT_SCOPES将 Web、Android、iOS、桌面四类端点分别绑定到 Authelia 端注册的四个客户端 ID注意其 scopes 顺序为openid profile email groups offline_access。禁用内置 IdP 与角色来源OC_EXCLUDE_RUN_SERVICESidp关闭 openCloud 内置 IdPPROXY_ROLE_ASSIGNMENT_DRIVERoidc声明角色来源于 OIDC 声明GRAPH_ASSIGN_DEFAULT_USER_ROLEfalse禁止为未映射用户分配默认角色强制走角色映射逻辑。桌面客户端的已知限制与手动修正官方文档明确指出两类限制均源于 openCloud 自身的开发生命周期与 Authelia 无关桌面客户端尚未达到生产就绪状态当前实现仅适用于一次性场景如迁移文件在 WebFinger 集成完成前相关 PR 尚在进行中不应作为长期稳定的桌面客户端方案。groups作用域需要手动加入授权链接设置桌面客户端时默认授权链接中的 scope 仅为scopeopenid%20offline_access%20email%20profile必须手工在开头追加groups%20scopegroups%20openid%20offline_access%20email%20profile完整的授权链接形如https://auth.example.com/api/oidc/authorization?response_typecodeclient_idclient_idredirect_uriredirect_uricode_challengecode_challengecode_challenge_methodS256scopescopepromptpromptstatestate该授权端点路径api/oidc/authorization与 Authelia 的 OIDC 端点实现一致详见 OpenID Connect 1.0 集成总览 中的端点表其中code_challenge/code_challenge_methodS256对应客户端配置中强制启用的 PKCE。附加文件CSP 与角色映射Content Security Policycsp.yaml外部 IdP 接入后openCloud 前端需要允许向 Authelia 发起跨域请求并嵌入 Authelia 页面因此必须配置 CSP。将以下文件保存到opencloud.yaml同级目录PROXY_CSP_CONFIG_FILE_LOCATION指向它directives: child-src: - self connect-src: - self - blob: - https://${COMPANION_DOMAIN|companion.opencloud.test}${TRAEFIK_PORT_HTTPS}/ - wss://${COMPANION_DOMAIN|companion.opencloud.test}${TRAEFIK_PORT_HTTPS}/ - https://auth.example.com - https://raw.githubusercontent.com/opencloud-eu/awesome-apps/ - https://update.opencloud.eu/ - https://tile.openstreetmap.org/ default-src: - none font-src: - self frame-ancestors: - self frame-src: - self - blob: - https://embed.diagrams.net/ - https://${COLLABORA_DOMAIN|collabora.opencloud.test}${TRAEFIK_PORT_HTTPS}/ - https://${EURO_OFFICE_DOMAIN|euro-office.opencloud.test}${TRAEFIK_PORT_HTTPS}/ - https://docs.opencloud.eu - https://auth.example.com img-src: - self - data: - blob: - https://raw.githubusercontent.com/opencloud-eu/awesome-apps/ - https://tile.openstreetmap.org/ - https://${COLLABORA_DOMAIN|collabora.opencloud.test}${TRAEFIK_PORT_HTTPS}/ - https://${EURO_OFFICE_DOMAIN|euro-office.opencloud.test}${TRAEFIK_PORT_HTTPS}/ manifest-src: - self media-src: - self object-src: - self - blob: script-src: - self - unsafe-inline - https://auth.example.com style-src: - self - unsafe-inline worker-src: - self - blob:要点说明connect-src、frame-src、script-src中均需显式加入 Authelia 根 URL如https://auth.example.com否则登录回调与静默刷新会被浏览器拦截。其余条目如tile.openstreetmap.org、embed.diagrams.net、Collabora / Euro Office 域来自 openCloud 官方 compose 仓库的参考实现实际部署应按需裁剪。default-src: none配合各指令的白名单是收紧 CSP 的正确姿势切勿为了省事整体放行。角色映射proxy.yaml当使用外部 IdP 时必须把 Authelia 中的组映射为 openCloud 角色。官方示例将 Authelia 的opencloud-admins组映射为 openCloud 的admin角色因为role_claim取值为groups并附带spaceadmin、user、user-light三个角色的示例。将文件保存到opencloud.yaml同级目录role_assignment: driver: oidc oidc_role_mapper: role_claim: groups role_mapping: - role_name: admin claim_value: opencloud-admins - role_name: spaceadmin claim_value: opencloud-space-admins - role_name: user claim_value: opencloud-users - role_name: user-light claim_value: opencloud-guestsrole_claim: groups与 Authelia 客户端配置中授予的groups作用域直接对应Authelia 会把用户所属组作为groups声明写入令牌openCloud 依据该声明的值与role_mapping匹配出角色。注意PROXY_ROLE_ASSIGNMENT_DRIVERoidc与GRAPH_ASSIGN_DEFAULT_USER_ROLEfalse两项环境变量必须与此文件配套即角色完全由 OIDC 声明决定、不设默认角色兜底。请根据你的实际组名调整claim_value。验证与常见问题完成上述配置后可按以下顺序验证确认 Discovery 端点可达浏览器访问https://auth.example.com/.well-known/openid-configuration确认issuer与OC_OIDC_ISSUER完全一致Authelia 对 issuer 的匹配是严格的。确认客户端注册生效使用authelia storage或直接检查配置文件确认四个客户端 ID 均已加载且无 schema 校验错误如 PKCE 方法拼写错误会在启动时被 validator/identity_providers.go 拒绝。从 Web 门户发起登录若跳转到 Authelia 登录页并完成双因素认证后能正常回到 openCloud且用户组正确映射为角色则主链路打通。桌面端专项检查确认授权链接中手动追加了groups%20前缀否则角色映射会因缺少groups声明而失败。如果登录后角色为空优先检查三处是否一致Authelia 端客户端scopes是否包含groups、PROXY_AUTOPROVISION_CLAIM_GROUPS是否为groups、proxy.yaml的role_claim与claim_value是否与实际组名匹配。若浏览器控制台报 CSP 错误则回到csp.yaml确认connect-src、frame-src、script-src中已包含 Authelia 根 URL。总结openCloud 与 Authelia 的集成是一条完整的注册客户端 → 环境变量对接 → 附加文件收尾链路Authelia 端为 Web / Android / iOS / 桌面四类端点各注册一个公开客户端统一采用授权码流程 PKCE(S256) RS256 签名 Access TokenopenCloud 端通过OC_OIDC_ISSUER、PROXY_*与WEBFINGER_*系列环境变量完成 Issuer 绑定、JWT 验证、账户自动供给与角色驱动最后用csp.yaml放行跨域资源、用proxy.yaml完成组到角色的映射。理解public、token_endpoint_auth_method: none、require_pkce等参数在源码层的行为有助于在遇到认证失败时快速定位是配置问题还是应用端限制如桌面客户端 WebFinger 未完成。更多客户端集成范例可参考 integration 目录 下的其他文档。【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考