认证方法

概述

Stirling-PDF 支持四种主要的身份验证方法：

用户名/密码身份验证 - 传统的基于表单的登录
OAuth2 身份验证 - 与外部身份提供商集成
SAML2 身份验证 - 企业单点登录集成
API 密钥身份验证 - 用于对 API 进行编程访问

身份验证可以全局启用或禁用，并且每种方法都可以单独配置。

来源： src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java104-292

认证系统架构

下图显示了 Stirling-PDF 中身份验证系统的高层架构

来源： src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java45-97

配置选项

Stirling-PDF 中的身份验证在很大程度上是可配置的。主要的配置发生在 SecurityConfiguration 类中，该类设置了 Spring Security 的过滤器链。

启用/禁用身份验证

身份验证可以完全禁用，这将允许所有请求而无需登录

# Settings to disable login
SYSTEM_SECURITY_LOGINENABLED: false

禁用身份验证时，CSRF 保护也会被禁用。

来源： src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java104-107 src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java287-290

身份验证方法配置

每种身份验证方法都可以独立启用或禁用

来源： src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java210-286

用户名/密码认证

这是标准的基于表单的身份验证方法，用户通过提供用户名和密码来登录。

实现细节

用户名/密码身份验证是使用 Spring Security 的表单登录机制实现的。流程如下：

使用 BCrypt 加密，将用户凭据与存储的密码进行验证。

来源： src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java211-223 src/main/java/stirling/software/SPDF/config/security/UserService.java354-356

当用户首次登录时（或当管理员设置了 forceChange 标志）时，他们将被重定向到一个密码更改屏幕。

来源： src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java147 src/main/resources/templates/change-creds.html1-88

OAuth2 身份验证

Stirling-PDF 支持与多种提供商（包括 Google、GitHub 和 Keycloak）的 OAuth2 身份验证。

配置

OAuth2 提供商在应用程序设置中进行配置

来源： src/main/java/stirling/software/SPDF/controller/web/AccountWebController.java72-197

下图说明了 OAuth2 身份验证流程

来源： src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java226-255 src/main/java/stirling/software/SPDF/config/security/UserService.java80-92

SAML2 认证

SAML2 身份验证提供企业单点登录功能，该功能在 Pro 和 Enterprise 版本中可用。

要求

SAML2 身份验证要求：

运行 Pro 或更高版本
在应用程序设置中进行 SAML2 配置
已配置身份提供商 (IdP)

来源： src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java257-286

API 密钥身份验证

API 密钥提供了用于 Stirling-PDF API 的程序化请求进行身份验证的方法。

API 密钥生成

每个用户都可以关联一个 API 密钥到其账户。API 密钥通过用户界面或 API 进行生成和管理。

来源： src/main/resources/templates/account.html78-252 src/main/java/stirling/software/SPDF/controller/api/UserController.java356-383

API 密钥认证流程

API 密钥在 HTTP 头 X-API-KEY 中传递，并由系统验证。

当提供有效的 API 密钥时，对该请求的 CSRF 检查将被绕过。

来源： src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java120-142 src/main/java/stirling/software/SPDF/config/security/UserService.java94-163

会话管理

Stirling-PDF 实现了会话管理来控制用户会话。

关键的会话管理功能包括：

会话创建策略：IF_REQUIRED
每个用户的最大会话数：10
用于跟踪活动会话的会话注册表
带有持久化令牌的“记住我”功能

来源： src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java148-180

初始用户设置

Stirling-PDF 首次启动时，会创建一个初始管理员用户。

管理员用户可以通过应用程序设置进行配置，或使用默认值：

用户名： admin
密码： stirling

来源： src/main/java/stirling/software/SPDF/config/security/InitialSecuritySetup.java36-95

用户界面集成

身份验证方法通过几个关键页面集成到用户界面中。

登录页面根据配置显示可用的身份验证方法。

来源： src/main/java/stirling/software/SPDF/controller/web/AccountWebController.java72-198

账户页面

账户页面提供了以下接口：

更改用户名（针对用户名/密码身份验证）
更改密码（针对用户名/密码身份验证）
管理 API 密钥
同步账户和浏览器之间的设置

来源： src/main/resources/templates/account.html1-361 src/main/java/stirling/software/SPDF/controller/web/AccountWebController.java338-401

安全考量

Stirling-PDF 实施了多项安全措施：

CSRF 保护：当身份验证启用时，默认启用跨站请求伪造保护，API 密钥身份验证的请求除外。
密码编码：密码使用 BCrypt 编码存储。
速率限制：一个基本的速率限制过滤器可防止暴力破解攻击。
“记住我”安全性：使用安全的 cookie 来实现“记住我”功能。
会话管理：适当的会话管理可防止会话固定攻击。

来源： src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java112-145 src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java301-306