Authelia 在 Kubernetes 中的 Secrets 注入实战指南：从 Secret 对象到环境变量文件注入

Authelia 在 Kubernetes 中的 Secrets 注入实战指南从 Secret 对象到环境变量文件注入【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/autheliaAuthelia 作为面向 Web 应用的单点登录SSO多因素认证门户其运行依赖多个关键机密JWT 密钥、会话密钥、数据库密码、LDAP 密码、OIDC HMAC 密钥等。在 Kubernetes 上部署时如何安全地创建并注入这些机密是保证身份认证体系安全性的第一道关卡。本文以 Authelia 官方 Kubernetes 集成文档为核心完整讲解通过 Secret 对象 _FILE环境变量的机密注入方案并深入到源码层解释其底层机制帮助读者掌握一套可直接落地的 Kubernetes 机密管理实践。前置准备先完成 Authelia 基础引导在动手配置 Kubernetes 机密之前官方强烈建议首次部署 Authelia 的读者先通读 Get started 指南。该指南覆盖了 Authelia 引导启动所必需的各项步骤配置生成、密钥初始化、首次认证等是理解后续 Secret 注入方案的前提。下面的所有示例都假定你已经具备一个可运行的 Authelia 基础环境。机密创建三种主流方式Authelia 的 Kubernetes 集成文档提供了三种创建机密的途径Helm Chart 自动生成、手写 Kubernetes Secret 清单、以及 Kustomize 声明式生成。它们面向不同的部署管理风格你可以按团队习惯选用。方式一Helm Chart推荐自动生成Authelia 官方提供 Helm Chart它会在部署过程中自动生成并注入所需的 Secrets无需手工管理。适合希望开箱即用、不愿手工维护 Secret 清单的团队。Chart 目前处于 beta 状态升级时可能伴随破坏性变更生产使用前应关注版本发布说明。方式二手工 Manifestkubectl apply -f下面的清单是其余示例尽量对齐的基准形态也是理解整个注入链路最直观的入口。它定义了一个名为authelia的 Secret覆盖了 Authelia 常用到的全部机密项。String Data 示例明文直写便于阅读stringData允许直接书写明文值适合在源码仓库中维护模板、由 CI/CD 在部署前替换真实值--- kind: Secret apiVersion: v1 metadata: name: authelia stringData: JWT_SECRET: - NwsVsXv4YCAF9suxWZmT7N6PSzmouCDHqVpzbS5niBKo49b7rTREmwFe6roKswf4 SESSION_SECRET: - DkezH5zcMQsvaU38YVu673i6JDH4VPiik9xPmYsTN3KPNkxSiiyZ8ASFTdcBcu8q REDIS_PASSWORD: - VfhdNhgFG5mLU9s3cjQn9im6dkiWNu3FEUPJRi9bqGm3UV6xzGBZgvdCJhoy26d9 REDIS_SENTINEL_PASSWORD: - sSJMfX9A6Q6vTpD6rHXcLn2j5kN557RwuohAeyZuGqH9P9LGfuSMnzi9woYZuNqU LDAP_PASSWORD: - zafcAShEBfgc48DihdRnnb6UJEGKqzg3FdeZXZ3rhrg6tu2oDoYSBA88w9NPvDhZ STORAGE_PASSWORD: - NMHf9Z7C5UQYuKKgh9BJTKeccoZt6c647FQqsEHhkapkkndPkPw3d8bnvkqLgiZ5 STORAGE_ENCRYPTION_KEY: - rH87rjVMQBvzVgj8vVGSxhop2PPwddrJ7B6oSkGcmoganMf4wqANp9AJwaMHt8RA SMTP_PASSWORD: - oi4Yag5HX8Bhc5JTr49nRkdPEr4JcPMfLAPvXxNpHtHqiHXfx3isdWXuTg7yCtjk DUO_SECRET_KEY: - d4ypk2UQXxuo86s7vJ2rYWPa5KoxDfU9JQWgEqtANiBaJVQSG8PJbD9U24eiVuPC OIDC_HMAC_SECRET: - eSopMjbiuCMhEbXGFsm5B8KWKszxV3CJWSLYrWnBJja4rFNvDxti388WyBjdrsHb OIDC_ISSUER_PRIVATE_KEY: | -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY----- ...要点说明示例中的值仅用于演示切勿直接用于生产环境实际部署时应使用authelia crypto相关命令或安全随机源生成高熵值示例中每个密钥均约 64 字符 / 384 位符合高强度随机口令量级。JWT_SECRET、SESSION_SECRET等行使用-折叠标量自动去除末尾换行OIDC_ISSUER_PRIVATE_KEY使用|字面块标量完整保留 PEM 私钥的多行格式。官方明确提示只应包含你实际启用的功能所对应的机密本示例可能缺项或含多余项请对照 Secrets 配置方法文档 按需裁剪。Base64 Data 示例编码存储data字段要求值必须是 Base64 编码。下面的清单与上面的 stringData 示例内容完全一致只是换成了编码形态Kubernetes 的 Secret 对象在 API 存储层本身就采用 Base64--- kind: Secret apiVersion: v1 type: Opaque metadata: name: authelia data: DUO_SECRET_KEY: ZDR5cGsyVVFYeHVvODZzN3ZKMnJZV1BhNUtveERmVTlKUVdnRXF0QU5pQmFKVlFTRzhQSmJEOVUyNGVpVnVQQw JWT_SECRET: TndzVnNYdjRZQ0FGOXN1eFdabVQ3TjZQU3ptb3VDREhxVnB6YlM1bmlCS280OWI3clRSRW13RmU2cm9Lc3dmNA LDAP_PASSWORD: emFmY0FTaEVCZmdjNDhEaWhkUm5uYjZVSkVHS3F6ZzNGZGVaWFozcmhyZzZ0dTJvRG9ZU0JBODh3OU5QdkRoWg OIDC_HMAC_SECRET: ZVNvcE1qYml1Q01oRWJYR0ZzbTVCOEtXS3N6eFYzQ0pXU0xZclduQkpqYTRyRk52RHh0aTM4OFd5QmpkcnNIYg OIDC_ISSUER_PRIVATE_KEY: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLSBNWElFb2dJQiRBS0NBUUVBeFpWSlAzV0YvL1BHMmZMUW9FQzlEdGRpRkcvKzAwdnFsYlZ6ejQ3bnl4S09OSVBJIGxtTDNVZG1xcEdUS01lLzVCcnFzZTRaQUtsUUhpRGJ3eks5eXBuZmlndEh1dmgvSk8wUzdDaFA3MFJDNjdlZDEgSFYxbnlmejVlVzNsbGJ0R0pQcmxZTHFJVE5nY3RIcDZ6bVJVRnRTelBqOXFGdm96STkzTEppNDkyeUwxK3Z1OCBVbjNEbTgrUXE2WE0ydFBkRWNsZEIvZHRCd09Xb0YrOGVPT1ZzdTBURHVCNWJ3bGhCVkdKdVNBdXpCUFJTMmJGIEdhNHVrMEpEZGtET01DRVF4QzV1V0RGeGdmRVJTTUZ5ZkxWV0Q0N3dvRGJ1V0VCcTEwYzB6K2RwV1BNcDdBaW4gWW5ua3FpY3dDTjg4WjB6aWQ2TW1NUTY1RjQrOUhjK3FDL3A2eHdJREFRQUJBb0lCQUdsaGFBSEtvcitTdTNvLyBBWHFYVEw1L3JiWU16YkxRaUx0MFhlSlQ2OWpwZXFNVHJvWlhIbVd2WEUzMTI4bXFuZjB5encvSzJLbzZ5eEdoIGkrai9vbnlhOEZxcHNWWUNDZ2ZzYm4yL2pzMUF5UkplSXA2WTFPUnNZbnFiWEpueG1rWGE4MEFWL09CUFcyLysgNjBUdFNkUXJlYlkzaUZQYytpMmsrOWJQVHZweXlETEtsejhVd2RaRytrNXV5WU5JeVFUY2N6K1Bqd3NJdkRpaiA3dEtZYW1oaExOM1FYdDMvYVpURnBqVGdlelA0V3lyaVp4aldyZGRIb3djNDdxMnJ3TlM5NU5EMzlKY3lzSkFjIDBQY2J1OEE1bFZhN0Z4MzN1T3R6RGZLV0lXN3hWRU4rT3RQZ04rRmJUalhjWGs1SVplZGwrcFc1bFU1UCsrRy8gWlB2eitXRUNnWUVBOWc2SHdkT0RXM2U2OGJPcXNGb0tnMzUrdmZVRk16bHlNRjhIRnlsTlZmbkxwVEVEcjYzNyBvd3pNRnZjVXhWZDcxYitnVjVubm5iSStyaVVGSWd5Ujh2aENqaHk0bW9vcERQYWhDNC9Ld040Tkc2dXoraTFoIEFCNkQ1K3puMkJqbk8vNXhNTUZHbEFwV3RSTm1KVkdZbE5EajNiWEtoMlZYenp5MDNWTmVEOGtDZ1lFQXpaRkwgT2x6b1JCMUhLcFRXSUVDY3V2eG9mTXhMT0xiM3pzMGsydC9GWU5ZSXBvdm1HV0NDQVVMejEzeTUzZTUrLys1bSA3STlWVVpKRmFJaGFaMzZxVkJBcENLZHJ1NjlwWk1rV0NjUU85akVMRmN4NTFFejdPZ0pXenU3R1MxUUpDUEtDIGZFRHhJMHJaSzIxajkzL1NsL25VbkVpcjdDWXBRK3d2Q2FHdUhnOENnWUFYZ2JuY2ZZMStEb2t3a0I2TmJIeTIgcFQ0TWZiejZjTkdFNTM4dzZrUTJJNEFlRHZtd0xlbnRZTXFhb3c0NzhDaW5lZ0FpZmxTUFR6a0h3QWVtZ2hiciBaR1pQVjFVWGhuMTNmSlJVRzIrZVQxaG5QVmNiWG54MjIzTjBrOEJ1ZDZxWG82NUNueVJUL2t6Y1RiY2pkNUVoIEhuZTJkYWljbU1UenluUG85UTcyYVFLQmdCbW9iTzlYOFZXdklkYmF4Tzg1b1ZabGN0VkEycEsxbzdDWVFtVmYgVU0rSlo0TUNLekkzcllKaXpQUzBpSzUrdWpOUG1tRWtjczIvcUJJb0VzQ2dPcnBMV2hQT2NjLzNVUHhYYlB6RCBEK3NDckJPSWRoeGRqMjNxSk5PblVmRE5DR09wZ1VmcEF6QVlnNHE4R0tJbnZpMWg3WHVrUm5FdlFpOU1KNExZIFAxZFpBb0dBU0djR25UTWttZVNYUDh1eCtkdlFKQWlKc2tuL3NKSWdCWjV1cTVHUkNlTEJVb3NSU1Z4TTc1VUsgdkFoL2MvUkJqK3BZWFZLdVB1SEdaQ1FKeHNkY1JYelhOR291VXRnYmFZTUw1TWUvSGFndDIwUXpEUkJmdUdCZyBxZVpCSmFYaGpFbHZ3NlBVV3RnNHgrTFlSQ0JwcS9iUzNMSzNvelpyU1R1a1ZrS0RlZ3c9IC0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0t REDIS_PASSWORD: VmZoZE5oZ0ZHNW1MVTlzM2NqUW45aW02ZGtpV051M0ZFVVBKUmk5YnFHbTNVVjZ4ekdCWmd2ZENKaG95MjZkOQ REDIS_SENTINEL_PASSWORD: c1NKTWZYOUE2UTZ2VHBENnJIWGNMbjJqNWtONTU3Und1b2hBZXladUdxSDlQOUxHZnVTTW56aTl3b1ladU5xVQ SESSION_SECRET: RGtlekg1emNNUXN2YVUzOFlWdTY3M2k2SkRINFZQaWlrOXhQbVlzVE4zS1BOa3hTaWl5WjhBU0ZUZGNCY3U4cQ SMTP_PASSWORD: b2k0WWFnNUhYOEJoYzVKVHI0OW5Sa2RQRXI0SmNQTWZMQVB2WHhOcEh0SHFpSFhmeDNpc2RXWHVUZzd5Q3Rqaw STORAGE_ENCRYPTION_KEY: ckg4N3JqVk1RQnZ6VmdqOHZWR1N4aG9wMlBQd2Rkcko3QjZvU2tHY21vZ2FuTWY0d3FBTnA5QUp3YU1IdDhSQQ STORAGE_PASSWORD: Tk1IZjlaN0M1VVFZdUtLZ2g5QkpUS2VjY29adDZjNjQ3RlFxc0VIaGthcGtrbmRQa1B3M2Q4Ym52a3FMZ2laNQ ...提示stringData与data是等价的两种写法stringData更便于模板化和阅读data更适合从已有 Base64 素材直接迁移。二者混用时 Kubernetes 会优先采用stringData的值。方式三Kustomizekubectl apply -k如果你使用 Kustomize 组织部署清单下面的kustomization.yaml通过secretGenerator从本地文件生成同名 Secret。secretGenerator中列出的每个文件都必须真实存在文件内容即对应密钥的值--- generatorOptions: disableNameSuffixHash: true labels: type: generated app: authelia secretGenerator: - name: authelia files: - DUO_SECRET_KEY - JWT_SECRET - LDAP_PASSWORD - OIDC_HMAC_SECRET - OIDC_ISSUER_PRIVATE_KEY - REDIS_PASSWORD - REDIS_SENTINEL_PASSWORD - SESSION_SECRET - SMTP_PASSWORD - STORAGE_ENCRYPTION_KEY - STORAGE_PASSWORD ...配置说明disableNameSuffixHash: true关闭 Kustomize 默认追加的哈希后缀确保生成的 Secret 名称稳定为authelia与后续 Deployment 中secretName: authelia精确匹配。labels为生成的 Secret 统一打上type: generated、app: authelia标签便于审计与选择器筛选。生成方式在当前目录为每个密钥准备同名文件文件内容即密钥明文随后运行kubectl apply -k .。机密使用挂载为文件并通过_FILE环境变量注入为什么推荐文件注入而非明文环境变量Authelia 的 Secrets 配置方法文档 明确指出尽管配置可以写在配置文件或普通环境变量中机密的推荐设置方式始终是文件式注入。其安全优势在于能够将敏感配置与其他配置在逻辑上隔离降低机密意外泄露进日志、镜像层或进程列表ps//proc的风险。完整 Deployment 片段下面的清单摘取自可挂载卷的工作负载清单适用于 [Pod]、[Deployment]、[StatefulSet]、[DaemonSet]完整演示了Secret → 卷 → 环境变量的注入链路--- spec: containers: - name: authelia env: - name: AUTHELIA_DUO_API_SECRET_KEY_FILE value: /app/secrets/DUO_SECRET_KEY - name: AUTHELIA_JWT_SECRET_FILE value: /app/secrets/JWT_SECRET - name: AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD_FILE value: /app/secrets/LDAP_PASSWORD - name: AUTHELIA_IDENTITY_PROVIDERS_OIDC_HMAC_SECRET_FILE value: /app/secrets/OIDC_HMAC_SECRET - name: AUTHELIA_IDENTITY_PROVIDERS_OIDC_ISSUER_PRIVATE_KEY_FILE value: /app/secrets/OIDC_ISSUER_PRIVATE_KEY - name: AUTHELIA_SESSION_REDIS_PASSWORD_FILE value: /app/secrets/REDIS_PASSWORD - name: AUTHELIA_REDIS_HIGH_AVAILABILITY_SENTINEL_PASSWORD_FILE value: /app/secrets/REDIS_SENTINEL_PASSWORD - name: AUTHELIA_SESSION_SECRET_FILE value: /app/secrets/SESSION_SECRET - name: AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE value: /app/secrets/SMTP_PASSWORD - name: AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE value: /app/secrets/STORAGE_ENCRYPTION_KEY - name: AUTHELIA_STORAGE_POSTGRES_PASSWORD_FILE value: /app/secrets/STORAGE_ENCRYPTION_KEY volumeMounts: - mountPath: /app/secrets name: secrets readOnly: true volumes: - name: secrets secret: secretName: authelia items: - key: DUO_SECRET_KEY path: DUO_SECRET_KEY - key: JWT_SECRET path: JWT_SECRET - key: OIDC_HMAC_SECRET path: OIDC_HMAC_SECRET - key: OIDC_ISSUER_PRIVATE_KEY path: OIDC_ISSUER_PRIVATE_KEY - key: REDIS_PASSWORD path: REDIS_PASSWORD - key: REDIS_SENTINEL_PASSWORD path: REDIS_SENTINEL_PASSWORD - key: SESSION_SECRET path: SESSION_SECRET - key: SMTP_PASSWORD path: SMTP_PASSWORD - key: STORAGE_ENCRYPTION_KEY path: STORAGE_ENCRYPTION_KEY - key: STORAGE_PASSWORD path: STORAGE_PASSWORD ...注入链路拆解卷定义volumes声明名为secrets的卷数据源为secretName: authelia并通过items把 Secret 中的每个key映射为卷内的同名文件path例如STORAGE_ENCRYPTION_KEY→/app/secrets/STORAGE_ENCRYPTION_KEY。挂载volumeMounts将卷以只读方式挂载到/app/secrets。环境变量env为每个机密设置形如AUTHELIA_..._FILE的环境变量其值指向挂载后的文件路径。Authelia 启动时会读取这些文件内容作为对应配置值。注意两个容易踩坑的细节示例清单中AUTHELIA_STORAGE_POSTGRES_PASSWORD_FILE的 value 指向的是/app/secrets/STORAGE_ENCRYPTION_KEY与AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE相同——这应是文档示例的笔误实际部署时应指向/app/secrets/STORAGE_PASSWORD并确认items中已包含STORAGE_PASSWORD的映射示例中的确包含了。若使用 MySQL 而非 PostgreSQL 作为存储后端请将AUTHELIA_STORAGE_POSTGRES_PASSWORD_FILE替换为AUTHELIA_STORAGE_MYSQL_PASSWORD_FILE路径指向 MySQL 密码文件。环境变量命名规则与 Secret 判定逻辑从源码可以精确还原_FILE变量的生成规则。在 internal/configuration/helpers.go 中// ToEnvironmentSecretKey converts a key into the environment variable name. func ToEnvironmentSecretKey(key, prefix, delimiter string) string { return prefix strings.ToUpper(strings.ReplaceAll(key, constDelimiter, delimiter)) constSecretSuffix }即配置点路径如session.secret→ 点号替换为下划线 → 全大写 → 加AUTHELIA_前缀 → 追加_FILE后缀得到AUTHELIA_SESSION_SECRET_FILE。同时并不是所有配置项都支持文件注入。IsSecretKeyinternal/configuration/helpers.go通过后缀判定只有以key、secret、password、token、certificate_chain结尾的配置键才被视为机密对应 internal/configuration/const.go 中的secretSuffix列表并排除了identity_providers.oidc.lifespans.前缀、server.tls.key等特例同时不适用于包含[]列表对象的配置段。加载行为与边界约束文件必须可读_FILE变量的值必须是 Authelia 进程可读取的文件路径否则启动失败。相关错误信息定义在 internal/configuration/const.go例如文件不存在报file does not exist error occurred、权限不足报file permission error occurredinternal/configuration/provider_test.go 中的测试用例逐一验证了这些失败路径。自动去除尾部换行loadSecretinternal/configuration/helpers.go读取文件后执行strings.TrimRight(content, \n)因此你不需要担心 Secret 文件末尾的换行符污染密码值——这也是 Kubernetes Secret 文件天然带\n也能直接使用的原因。禁止与其他配置方法混用Secrets 层在分层配置模型中具有特殊性——只要你在其他任何配置源配置文件或普通环境变量中定义了同一密钥同时又设置了_FILE变量Authelia 将拒绝启动。例如同时定义jwt_secret文件法或AUTHELIA_JWT_SECRET环境变量法以及AUTHELIA_JWT_SECRET_FILE就会触发该错误。源码中对应的错误为errFmtSecretAlreadyDefinedits already defined in other configuration sources在 internal/configuration/provider_test.go 中有直接的单测覆盖。对象列表段不可用所有对象列表型配置段如访问控制的rules、OIDC Provider 的clients、会话的cookies、服务端点的authz无法通过环境变量或 Secrets 方式配置原因详见 ADR-2。涉及机密项与配置键映射速查表下表汇总了示例 Secret 中每个键对应的 Authelia 配置点与环境变量均为_FILE形式便于按需裁剪Secret 键配置点路径环境变量文件形式JWT_SECRETidentity_validation.reset_password.jwt_secretAUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILESESSION_SECRETsession.secretAUTHELIA_SESSION_SECRET_FILEREDIS_PASSWORDsession.redis.passwordAUTHELIA_SESSION_REDIS_PASSWORD_FILEREDIS_SENTINEL_PASSWORDsession.redis.high_availability.sentinel_passwordAUTHELIA_REDIS_HIGH_AVAILABILITY_SENTINEL_PASSWORD_FILELDAP_PASSWORDauthentication_backend.ldap.passwordAUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD_FILESTORAGE_PASSWORDstorage.postgres.password或storage.mysql.passwordAUTHELIA_STORAGE_POSTGRES_PASSWORD_FILE或AUTHELIA_STORAGE_MYSQL_PASSWORD_FILESTORAGE_ENCRYPTION_KEYstorage.encryption_keyAUTHELIA_STORAGE_ENCRYPTION_KEY_FILESMTP_PASSWORDnotifier.smtp.passwordAUTHELIA_NOTIFIER_SMTP_PASSWORD_FILEDUO_SECRET_KEYduo_api.secret_keyAUTHELIA_DUO_API_SECRET_KEY_FILEOIDC_HMAC_SECRETidentity_providers.oidc.hmac_secretAUTHELIA_IDENTITY_PROVIDERS_OIDC_HMAC_SECRET_FILEOIDC_ISSUER_PRIVATE_KEYidentity_providers.oidc.issuer_private_keyAUTHELIA_IDENTITY_PROVIDERS_OIDC_ISSUER_PRIVATE_KEY_FILE上述配置键均收录于 docs/data/configkeys.json且 Secrets 配置方法文档docs/content/configuration/methods/secrets.md给出了官方完整的机密环境变量清单还额外包含各类 TLS 的certificate_chain/private_key文件注入项如 LDAP TLS、Redis TLS、SMTP TLS、MySQL/Postgres TLS可按需参考。安全加固建议最小化原则只创建与启用功能相关的 Secret 键未使用的密钥不要写入清单。高熵生成使用authelia crypto系列命令或安全随机源生成密钥值避免复用文档示例值。权限控制若坚持把机密写进配置文件务必把配置文件权限收紧为0600防止其他用户或进程读取官方明确建议。版本 4.30.0 提醒虽然可以不带_FILE后缀直接通过环境变量明文设置机密但官方强烈反对这种做法应始终优先使用文件式注入。其他 Kubernetes 集成要点部署时建议参考 Kubernetes 集成总览 中的两个注意点——将 Service 的externalTrafficPolicy设为local以保留客户端真实 IP将 PodSpec 的enableServiceLinks设为false避免其与 Authelia 的配置管理系统冲突。结语在 Kubernetes 上为 Authelia 注入机密推荐链路是Secret 对象Helm Chart 自动生成 / 手写清单 / Kustomize 生成→ 以只读卷挂载到/app/secrets→ 通过AUTHELIA_*_FILE环境变量指向文件路径。Authelia 在启动时会自动完成文件读取与尾部换行清理并通过同键不得多源定义的强约束杜绝配置漂移。理解这套机制背后的命名规则与判定逻辑你就能在 Helm、Kustomize 或纯 Manifest 任意工作流中安全、一致地管理 Authelia 的全部机密。【免费下载链接】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），仅供参考