Technitium DNS Server 集成 Authelia OpenID Connect 1.0 实现单点登录与组映射配置指南【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia导读本指南介绍如何将 Technitium DNS Server 的 Web 控制台接入 Authelia 提供的 OpenID Connect 1.0 Provider实现统一身份认证SSO并通过组映射把 Authelia 中的用户组同步为 Technitium 的本地角色如Administrators。读完本文你将掌握在 Authelia 中注册 Technitium 客户端的完整 YAML 配置含自定义 scope 与 claims policy、Technitium 控制台的 SSO 配置步骤以及最易踩坑的回通道域名解析问题的排查与修复方法。本文对应仓库文档位于 docs/content/integration/openid-connect/clients/technitium/index.md属于 Authelia 官方 OpenID Connect 1.0 第三方 Relying Party客户端应用集成系列之一。在动手之前建议先通读 OpenID Connect 1.0 集成总览了解 Authelia 作为 OpenID Connect 1.0 Provider 的基础行为。测试版本本指南依据以下版本组合验证适用于对应的兼容环境组件版本Autheliav4.39.xTechnitium DNS Serverv15.2需要说明的是Authelia 的 OpenID Connect 1.0 Provider 目前以 open beta 形式提供具体状态可参考 OpenID Connect 1.0 Provider 配置文档 中的说明。若你的 Authelia 版本与上述版本差异较大建议以该版本对应的文档与行为为准。开始之前Before You Begin本指南使用 Authelia 的 OpenID Connect 1.0 流程。所有客户端集成都需要遵循一些通用注意事项其中与本集成最相关的是client secret 的生成方式见下文。通用注意事项Common Notes根据集成文档的公共说明见 docs/layouts/_shortcodes/oidc-common.html在配置任何 OpenID Connect 1.0 客户端前应注意client_id 必须全局唯一且只能包含 RFC3986 无保留字符长度不超过 100 个字符。指南中使用的technitium仅为演示可读性而设计生产环境建议使用随机生成的长字符串。client_secret 不应明文存储。Authelia 强烈建议在配置中存储 PBKDF2 等哈希格式的 secret明文存储虽然技术上仍被支持但已正式废弃详见 FAQClient Secret 生成。指南中的客户端配置示例只覆盖了客户端注册相关的部分必须同时配置OpenID Connect 1.0 Provider 配置 中要求的全局元素如hmac_secret、jwks等。生成 Client Secret生产环境中请按如下方式生成 client secret同时得到明文与 PBKDF2 哈希明文交给 Technitium 配置哈希写入 Authelia 配置# Docker 方式 docker run --rm authelia/authelia:latest authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986 # 裸机方式 authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986命令细节参见 FAQ如何生成客户端标识符或客户端密钥。提示如果客户端操作出现超时可能是 PBKDF2 工作因子过高所致。可以用time authelia crypto hash generate pbkdf2 --variant sha512 --iterations 310000 --password insecure_password实测耗时并参考 密码哈希调优指南 调整--iterations。假设前提Assumptions本示例基于以下环境假设应用根 URLhttps://dns.example.com/Technitium DNS Server Web 控制台Authelia 根 URLhttps://auth.example.com/OpenID Connect 1.0 IssuerClient IDtechnitiumClient Secretinsecure_secret演示值生产环境务必替换为随机生成值请将示例中的example.com等占位符替换为你实际使用的域名。Authelia 侧配置以下 YAML 是用于 Technitium 的Authelia OpenID Connect 1.0 客户端配置示例。它演示了如何让 Technitium 获得标准 OIDC 流程之外的额外 claims用户组并将登录策略绑定到自定义授权策略identity_providers: oidc: ## OpenID Connect 1.0 其余必填配置在此处填写hmac_secret、jwks 等。 ## 参见: docs/content/configuration/identity-providers/openid-connect/provider.md claims_policies: technitium: custom_claims: roles: attribute: groups scopes: technitium_roles: claims: - roles clients: - client_id: technitium client_name: Technitium DNS Server client_secret: $pbkdf2-sha512$310000$... # authelia crypto hash generate pbkdf2 --variant sha512 public: false authorization_policy: technitium claims_policy: technitium require_pkce: false redirect_uris: - https://dns.example.com/sso/callback scopes: - openid - profile - email - groups - technitium_roles grant_types: - authorization_code response_types: - code access_token_signed_response_alg: none userinfo_signed_response_alg: none token_endpoint_auth_method: client_secret_post配置逐项解析下面逐项说明该配置中关键字段的作用与限制字段语义依据 OpenID Connect 1.0 客户端配置client_id/client_nameclient_id必须与 Technitium 中配置的 Client ID 完全一致client_name是展示在 Authelia 用户界面上的友好名称默认与 ID 相同。client_secret使用 PBKDF2 哈希后的 secret前缀为$pbkdf2-sha512$。明文 secret 仅配置在 Technitium 侧。若哈希工作因子过高导致登录超时可适当降低--iterations。public: false声明为机密confidential客户端配合token_endpoint_auth_method: client_secret_post在 Token 端点通过 POST 表单提交凭据完成客户端认证。相关客户端认证方式的完整列表见 集成总览Client Authentication Method。authorization_policy: technitium指定该客户端使用的授权策略名称。该策略定义在 Provider 的authorization_policies下取值为one_factor、two_factor或自定义策略名。此处引用的technitium策略需在客户端配置之外另行定义参见 provider.md 的 authorization_policies 说明 与 clients.md 的 authorization_policy 说明。claims_policy: technitium引用上文定义的 claims policy。该 policy 通过custom_claims.roles.attribute: groups把用户的一级认证后端first factor backend中的groups属性映射为一个名为roles的自定义 claim。关于custom_claims与attribute的语义见 provider.md 的 claims_policies 章节custom_claims的键为自定义 claim 名attribute指定该 claim 返回的属性名属性既可以来自一级认证后端也可以来自 用户属性定义。scopes.technitium_roles定义一个名为technitium_roles的自定义 scope其claims列表包含roles。根据 provider.md 的 scopes 章节scope 定义中列出的每个 claim 必须是标准 claim或必须能被该客户端引用的claims_policy满足——这正是把roles挂到technitium_rolesscope 下的原因。require_pkce: falseTechnitium DNS Server 目前不支持 PKCEProof Key for Code Exchange因此需要显式关闭该要求。注意全局选项enforce_pkce默认为public_clients_only若你将其改为always则需要同时为 Technitium 这类不支持 PKCE 的客户端单独豁免见 provider.md 的 enforce_pkce 说明。redirect_uris必须与 Technitium 实际使用的回调地址完全一致大小写敏感、scheme 必须为http或https。Technitium 的 SSO 设置页会显示其使用的回调地址https://你的控制台主机/sso/callback请确保它出现在此列表中否则授权请求会被 Authelia 拒绝。scopes客户端被允许消费的 scope 列表默认值为openid,groups,profile,email。此处额外加入了自定义的technitium_roles。grant_types: [authorization_code]仅允许授权码流程Authorization Code Flow这是 集成总览 中推荐的默认且最安全的流程。response_types: [code]仅允许code响应类型。文档明确建议只使用code其他响应类型安全性较差见 clients.md 的 response_types 说明。access_token_signed_response_alg: none/userinfo_signed_response_alg: noneAccess Token 与 UserInfo 响应均不签名默认值即none此时 Access Token 为不透明令牌。若改为 JWT 签名如 RS256则必须确保 jwks 中存在匹配的签名密钥详见 clients.md 的 access_token_signed_response_alg 说明。token_endpoint_auth_method: client_secret_post客户端在 Token 端点以 POST body 方式提交client_id与client_secret完成认证对应 集成总览 中的 Secret via HTTP POST Body。配置逃生舱Configuration Escape HatchTechnitium DNS Server 对 OpenID Connect 1.0 的支持存在一个已知缺陷它不通过标准流程如调用 UserInfo 端点获取它需要的 claims尤其是用户组而是期望直接把这些 claims 注入到令牌中。为此本指南采用了claims hydration变通方案即通过自定义scopesclaims_policies把groups属性映射为rolesclaim 并放入technitium_rolesscope。这正是上文 YAML 中claims_policies、scopes与客户端claims_policy、scopes配置的作用。类似的逃生舱机制在 provider.md 的 id_token 配置项 中有明确说明它允许在授予了相关 scope 的前提下把额外 claims 自动复制进 ID Token。官方文档对此给出安全警告这类行为仅为不真正支持 OpenID Connect 1.0 的客户端提供属于 best-effort 支持且客户端用iss/sub之外的其他 claims 来关联用户可能带来安全风险强烈建议客户端开发者修复这一缺陷。请知悉该限制后再决定是否采用此方案。Technitium DNS Server 侧配置在 Technitium 侧配置使用 Authelia 作为 OpenID Connect 1.0 Provider按以下步骤操作使用本地管理员账号登录 Technitium Web 控制台建议保留一个本地管理员账号用于 break-glass 应急场景避免 SSO 故障时被锁死。进入Administration→Sessions→Single Sign-On (SSO)启用 SSO。配置以下参数Metadata Address元数据地址https://auth.example.com/.well-known/openid-configurationClient IDtechnitiumClient Secret你生成的明文 secret与 Authelia 配置中哈希对应的原文一致Scopesopenid、profile、email、groups、technitium_rolesGroup Map组映射添加一条映射——Remote Groupdns-admins→ Local GroupAdministrators。这样 Authelia 中属于dns-admins组的用户登录后会被映射为 Technitium 的Administrators本地组。启用Allow New User Sign Up与Allow Sign Up Only For Mapped Users仅允许已映射组内的成员自动开通账号避免任意用户自动注册。点击Save Config保存Technitium 会自动重启其 Web 服务使配置生效。Technitium 使用的回调 URI 为https://你的控制台主机/sso/callback——该地址显示在 SSO 设置页面上请确认它与 Authelia 客户端配置中的redirect_uris完全一致。说明Metadata Address 指向的/.well-known/openid-configuration是 Authelia 的 OpenID Connect Discovery 端点Technitium 通过它自动发现授权端点、Token 端点、JWKS 等其余端点。常见陷阱回通道域名解析Back-channel Name Resolution这是本集成中最常见、也最隐蔽的坑Technitium DNS Server 解析它自身的出站请求OIDC discovery、token、JWKS 等回通道请求时使用的是它自己的 DNS 引擎而不是操作系统的/etc/hosts或 stub resolver。因此如果你的 Authelia 地址如auth.example.com是仅内网可达的split-horizon DNS、没有公网记录那么即使在同一台主机上用curl能正常访问 AutheliaTechnitium 依然会报Failed to reach SSO provider。修复方法让 Authelia 主机名能被Technitium 自身解析。例如在 Technitium 服务器上为auth.example.com添加一条内部权威记录或通过其配置的 forwarder / conditional forwarder 路径转发到正确的内部 DNS。在 Technitium 主机上执行以下命令验证解析结果确认返回的是正确的内网 IPdig short 127.0.0.1 auth.example.com同时确保 Technitium 主机到 Authelia 端点的TCP 443端口网络可达若使用非标准端口请相应调整。验证与故障排查要点配置完成后建议按以下顺序验证集成是否生效在 Authelia 侧确认客户端注册成功、日志无 scope/claim 相关告警若配置了未定义 scope日志会出现警告见 clients.md 的 scopes 说明。访问 Technitium 控制台确认其能成功加载 SSO 元数据即回通道可达对应上文常见陷阱。用一个属于dns-admins组的测试账号执行完整登录流程确认① 跳转到 Authelia 完成认证② 授权同意页正常展示③ 回跳后用户被自动开通并被赋予Administrators本地组。测试一个不属于任何映射组的账号确认其无法自助注册对应第 5 步 Allow Sign Up Only For Mapped Users 的预期行为。延伸阅读Authelia OpenID Connect 1.0 Provider 配置Authelia OpenID Connect 1.0 客户端配置OpenID Connect 1.0 集成总览OpenID Connect 1.0 常见问题含 Client ID/Secret 生成【免费下载链接】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），仅供参考