goauthentik/authentik 项目配置详解：从基础到高级设置

goauthentik/authentik 项目配置详解：从基础到高级设置

authentik The authentication glue you need. 项目地址: https://gitcode.com/gh_mirrors/au/authentik

前言

goauthentik/authentik 是一款开源的 Identity Provider（身份提供商）解决方案，提供了丰富的身份验证和授权功能。本文将全面解析 authentik 的配置选项，帮助系统管理员和技术人员正确配置和优化 authentik 部署。

配置基础

配置方式与环境变量

authentik 采用环境变量作为主要配置方式，所有配置项都通过环境变量设置。这些变量遵循特定的命名约定：

• 使用双下划线(__)表示层级关系，这些配置在内部会被转换为 YAML 结构
• 支持从不同来源加载配置值，包括：
  • env://<变量名>：从环境变量加载
  • file://<文件名>：从文件加载
  • 两种方式都支持设置默认值，如env://<变量名>?<默认值>

配置验证方法

部署配置后，可以通过以下命令验证配置是否正确应用：

Docker Compose 环境：

docker compose run --rm worker dump_config

Kubernetes 环境：

kubectl exec -it deployment/authentik-worker -c worker -- ak dump_config

数据库配置

PostgreSQL 核心配置

authentik 使用 PostgreSQL 作为主要数据库，关键配置包括：

• AUTHENTIK_POSTGRESQL__HOST：数据库主机名
• AUTHENTIK_POSTGRESQL__NAME：数据库名称
• AUTHENTIK_POSTGRESQL__USER：数据库用户名
• AUTHENTIK_POSTGRESQL__PORT：数据库端口（默认5432）
• AUTHENTIK_POSTGRESQL__PASSWORD：数据库密码

高级连接选项：

• AUTHENTIK_POSTGRESQL__SSLMODE：SSL验证严格程度（默认"verify-ca"）
• AUTHENTIK_POSTGRESQL__CONN_MAX_AGE：连接生命周期（0表示不持久化）
• AUTHENTIK_POSTGRESQL__CONN_HEALTH_CHECKS：是否启用连接健康检查

读写分离配置

authentik 支持配置只读副本数据库来分担读负载：

AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__HOST=replica1.example.com
AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__NAME=authentik
...

注意：如果配置了只读副本，主数据库将不再处理读请求。如需主库也参与读操作，需要将其显式添加为副本之一。

连接池优化

当使用 PgBouncer 或 PgPool 等连接池工具时，需要特别注意：

1. 调整连接生命周期设置：

   AUTHENTIK_POSTGRESQL__CONN_MAX_AGE=60  # 设置合理的超时值
   

2. 禁用服务器端游标：

   AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS=true
   

缓存与消息队列配置

Redis 配置

authentik 使用 Redis 作为缓存、消息队列和通道层的基础：

AUTHENTIK_REDIS__HOST=redis.example.com
AUTHENTIK_REDIS__PORT=6379
AUTHENTIK_REDIS__DB=0
AUTHENTIK_REDIS__TLS=true

缓存策略

可以针对不同类型的数据设置不同的缓存超时：

AUTHENTIK_CACHE__TIMEOUT=300          # 常规缓存超时（秒）
AUTHENTIK_CACHE__TIMEOUT_FLOWS=300    # 流程缓存超时
AUTHENTIK_CACHE__TIMEOUT_POLICIES=300 # 策略缓存超时

网络监听配置

authentik 支持多种协议的监听配置：

AUTHENTIK_LISTEN__HTTP=0.0.0.0:9000      # HTTP服务
AUTHENTIK_LISTEN__HTTPS=0.0.0.0:9443     # HTTPS服务
AUTHENTIK_LISTEN__LDAP=0.0.0.0:3389      # LDAP服务
AUTHENTIK_LISTEN__METRICS=0.0.0.0:9300   # 监控指标

安全提示：AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS 用于设置可信代理的CIDR范围，确保只有可信来源可以设置代理头信息。

文件存储配置

authentik 支持本地文件系统和 S3 兼容存储两种方式存储媒体文件：

本地存储：

AUTHENTIK_STORAGE__MEDIA__BACKEND=file

S3存储：

AUTHENTIK_STORAGE__MEDIA__BACKEND=s3
AUTHENTIK_STORAGE__MEDIA__S3__BUCKET_NAME=my-bucket
AUTHENTIK_STORAGE__MEDIA__S3__REGION=us-east-1

核心安全配置

密钥配置

AUTHENTIK_SECRET_KEY 是用于会话签名的密钥，更改此值会使现有会话失效。对于 2023.6.0 之前的版本，此密钥还用于生成用户ID，因此不应更改。

日志级别

AUTHENTIK_LOG_LEVEL=info  # 可选：debug, info, warning, error, trace

警告：trace 级别会记录敏感信息，仅限调试使用。

错误报告

可以配置错误报告发送到 Sentry：

AUTHENTIK_ERROR_REPORTING__ENABLED=true
AUTHENTIK_ERROR_REPORTING__SENTRY_DSN=your-dsn
AUTHENTIK_ERROR_REPORTING__ENVIRONMENT=production

邮件服务配置

authentik 的邮件服务配置示例：

AUTHENTIK_EMAIL__HOST=smtp.example.com
AUTHENTIK_EMAIL__PORT=587
AUTHENTIK_EMAIL__USE_TLS=true
AUTHENTIK_EMAIL__FROM="Authentik <noreply@example.com>"

高级功能配置

外置服务配置

AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=my-registry/%(type)s:%(version)s
AUTHENTIK_OUTPOSTS__DISCOVER=true  # 自动发现集成

LDAP 同步设置

AUTHENTIK_LDAP__TASK_TIMEOUT_HOURS=2    # LDAP同步任务超时
AUTHENTIK_LDAP__PAGE_SIZE=50            # 每页同步对象数

信誉系统

AUTHENTIK_REPUTATION__EXPIRY=86400  # 信誉数据保存时间（秒）

最佳实践建议

1. 生产环境安全：

   • 始终使用 HTTPS
   • 合理设置日志级别，避免记录敏感信息
   • 定期轮换密钥和证书

2. 性能优化：

   • 为高负载环境配置读写分离
   • 根据实际负载调整缓存超时设置
   • 考虑使用连接池优化数据库连接

3. 监控与维护：

   • 启用监控端点收集指标
   • 配置适当的错误报告机制
   • 定期检查系统日志

通过合理配置这些选项，您可以构建一个安全、高效且可靠的 authentik 身份管理平台，满足企业级身份验证和授权需求。

authentik The authentication glue you need. 项目地址: https://gitcode.com/gh_mirrors/au/authentik