Authelia与Stirling PDF的OpenID Connect集成指南

本文将详细介绍如何将Authelia身份认证系统与Stirling PDF文档处理工具通过OpenID Connect 1.0协议进行集成，实现单点登录功能。

集成背景

OpenID Connect是基于OAuth 2.0协议的身份认证层，它允许客户端应用验证终端用户的身份，并获取基本的用户信息。Authelia作为开源的身份认证和授权服务器，支持OpenID Connect协议，而Stirling PDF作为文档处理工具，也提供了OAuth 2.0/OpenID Connect的集成能力。

配置准备

在开始集成前，请确保您已具备以下条件：

1. 已部署Authelia服务并正常运行
2. 已部署Stirling PDF服务(版本0.41.0或以上)
3. 管理员权限可修改两边的配置文件

Authelia服务端配置

在Authelia的配置文件中，需要添加Stirling PDF作为OIDC客户端。以下是关键配置项：

identity_providers:
  oidc:
    clients:
      - id: stirlingpdf
        description: Stirling PDF
        public: false
        secret: '替换为安全的客户端密钥'
        authorization_policy: two_factor
        redirect_uris: 'Stirling PDF服务地址/login/oauth2/code/oidc'
        scopes:
          - 'openid'
          - 'email'
          - 'profile'

配置说明：

• id: 客户端标识符，需与Stirling PDF配置一致
• secret: 客户端密钥，建议使用强密码
• redirect_uris: 认证成功后回调的URL
• scopes: 请求的用户信息范围

Stirling PDF客户端配置

在Stirling PDF的配置文件中，需要添加以下OAuth 2.0相关配置：

oauth2:
  enabled: true
  issuer: 'Authelia服务地址'
  clientId: 'stirlingpdf'
  clientSecret: '与Authelia配置相同的密钥'
  autoCreateUser: true
  blockRegistration: false
  useAsUsername: email
  scopes: openid, profile, email
  provider: Authelia

配置说明：

• enabled: 启用OAuth 2.0登录
• issuer: Authelia服务的基础URL
• autoCreateUser: 允许自动创建不存在的用户
• useAsUsername: 使用email作为用户名
• provider: 设置为Authelia以标识认证提供者

测试与验证

完成配置后，建议按以下步骤测试集成是否成功：

1. 访问Stirling PDF的登录页面
2. 应能看到OAuth登录选项
3. 点击后应跳转至Authelia登录页面
4. 成功登录后应返回Stirling PDF并显示已登录状态

常见问题解决

1. 认证失败：检查两边的clientId和secret是否一致
2. 回调错误：确认redirect_uri配置正确且URL编码无误
3. 用户信息缺失：确保请求的scope包含所需信息(如email, profile)
4. HTTPS问题：生产环境必须使用HTTPS，开发环境可能需要特殊配置

安全建议

1. 定期轮换客户端密钥
2. 限制redirect_uri为已知的安全URL
3. 根据实际需求设置适当的授权策略(如two_factor)
4. 监控认证日志以发现异常行为

通过以上配置，您已成功将Stirling PDF与Authelia集成，实现了基于OpenID Connect的单点登录功能，既提高了安全性又改善了用户体验。