Stirling-PDF项目SSO集成配置指南：以Authentik为例

背景概述

在现代企业应用架构中，单点登录(SSO)已成为身份认证的核心组件。Stirling-PDF作为开源PDF处理工具，支持通过OAuth 2.0和SAML协议与主流身份提供商集成。本文将深入解析如何配置Authentik与Stirling-PDF的SSO对接。

OAuth 2.0集成配置

核心参数解析

oauth2:
  issuer: http://your-authentik-server/application/o/stirlingpdf/
  clientId: 5ibI9L0
  clientSecret: DFSD3B7MKLkWuEAasxxm2hghuzulPr37jdkrojPsGBz9MGwkfc
  autoCreateUser: true
  blockRegistration: false
  useAsUsername: email
  scopes: openid, profile, email
  provider: authentik

关键参数说明：

1. issuer：需指向Authentik的OpenID发现端点，系统会自动获取.well-known/openid-configuration
2. clientId/clientSecret：在Authentik应用注册时生成的凭证
3. autoCreateUser：首次登录自动创建本地用户账户
4. scopes：建议至少包含openid和profile，获取用户基本信息

Authentik后台配置要点

1. 在Applications中创建OAuth2 Provider
2. 授权类型选择"Authorization Code"
3. 回调URL格式为：https://your-pdf-domain/login/oauth2/code/authentik
4. 确保分配的Scope包含email和profile

SAML 2.0集成方案（Alpha阶段）

配置模板

saml2:
  enabled: true
  autoCreateUser: true
  registrationId: stirling
  idpMetadataUri: http://your-authentik-server/application/saml/stirlingpdf/metadata/
  idpSingleLogoutUrl: http://your-authentik-server/application/saml/stirlingpdf/slo/binding/post/
  idpSingleLoginUrl: http://your-authentik-server/application/saml/stirlingpdf/sso/binding/post/
  idpIssuer: authentik
  encryptionKey: /path/to/encryption_key.pem
  spCert: /path/to/certificate.pem
  idpCert: /path/to/certificate.pem

注意事项：

1. 需启用enableAlphaFunctionality标志
2. 证书文件建议使用4096位RSA密钥
3. NameID格式建议使用urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

最佳实践建议

1. 测试环境验证：建议先在非生产环境完成端到端测试
2. 证书管理：定期轮换签名证书（建议90天周期）
3. 属性映射：通过useAsUsername配置项控制用户标识字段
4. 日志监控：启用DEBUG级别日志排查连接问题

常见问题排查

1. 元数据加载失败：检查网络连通性和TLS证书有效性
2. 签名验证错误：确认SP和IdP的证书指纹匹配
3. 用户属性缺失：检查请求的scope是否包含必要字段
4. 跨域问题：确保回调URL与应用域名完全一致

通过以上配置，企业用户可以无缝集成现有身份管理体系与Stirling-PDF，实现统一身份认证的同时保障文档处理安全。