本文档全面概述了 Stirling-PDF 中的安全和认证功能。它涵盖了认证方法、用户管理、API 安全和配置选项。有关这些安全功能如何与 REST API 交互的信息，请参阅API 参考。
Stirling-PDF 提供了一个灵活的安全系统，可以根据您的部署需求启用或禁用。当安全功能启用时，它提供多种认证方法、用户管理功能、会话处理和 CSRF 保护。
来源
默认情况下，Stirling-PDF 的安全功能是禁用的。要启用它，请修改配置文件中的security.enableLogin设置。
当安全功能启用时，除静态资源和登录页面外，所有端点都需要认证。
来源
Stirling-PDF 支持多种认证方法，可单独使用或组合使用
来源
这是标准的基于表单的认证方法。用户通过登录表单输入其用户名和密码。
如何配置
当安全功能启用且没有用户存在时，会自动创建初始管理员用户。首次登录时，系统将提示用户更改密码。
来源
Stirling-PDF 支持 OAuth2 认证，支持多个提供商，包括 Google、GitHub 和 Keycloak。
如何配置 OAuth2
当用户通过 OAuth2 登录时，系统将使用配置的属性（例如，电子邮件）作为用户名。如果启用了autoCreateUser，新用户将在首次 OAuth2 登录时自动创建。
来源
SAML2 认证支持企业用户。它允许与 Okta 等身份提供商集成。
如何配置 SAML2
SAML2 认证需要额外的配置，包括身份提供商和服务提供商的证书。
来源
API 密钥可用于认证 API 请求，而无需登录会话。每个用户都可以拥有一个 API 密钥，可在其帐户页面查看和刷新。
API 密钥在 API 请求中通过X-API-KEY头部传递。当提供了 API 密钥时，该请求的 CSRF 保护将被绕过。
来源
Stirling-PDF 包含一个全面的用户管理系统，允许管理员创建、更新和删除用户。
系统具有预定义的用户角色
| 角色 | 描述 |
|---|---|
| ROLE_USER | 具有 PDF 操作访问权限的标准用户 |
| ROLE_ADMIN | 具有用户管理访问权限的管理员 |
| ROLE_DEMO_USER | 用于演示目的的受限用户 |
| ROLE_INTERNAL_API_USER | 用于内部 API 访问的特殊角色 |
管理员可以通过管理员设置界面（/adminSettings）或通过 API 端点管理用户
POST /api/v1/user/admin/saveUserPOST /api/v1/user/admin/changeRolePOST /api/v1/user/admin/changeUserEnabled/{username}POST /api/v1/user/admin/deleteUser/{username}用户可以通过以下方式管理自己的帐户
POST /api/v1/user/change-usernamePOST /api/v1/user/change-passwordPOST /api/v1/user/get-api-keyPOST /api/v1/user/update-api-keyPOST /api/v1/user/updateUserSettings来源
Stirling-PDF 提供了几个用于安全和认证的用户界面页面
来源
登录页面（/login）根据配置的认证方法提供不同的登录选项
登录页面还可以显示登录失败的错误消息，以及注册或密码更改成功的确认消息。
来源
帐户页面（/account）允许用户
来源
管理员设置页面（/adminSettings）允许管理员
来源
Stirling-PDF 安全设置通过settings.yml文件配置。主要安全设置包括
默认情况下，CSRF 保护是启用的。可以通过将security.csrfDisabled设置为true来禁用它，但不建议在生产环境中使用此设置。当使用 API 密钥时，这些请求的 CSRF 保护将自动绕过。
来源
Stirling-PDF 使用 Spring Security 的会话管理，具有以下特点
application.properties）来源
API 密钥可用于认证 API 请求。每个用户都可以拥有一个 API 密钥，该密钥通过其帐户页面生成和管理。
要在请求中使用 API 密钥，请将其包含在X-API-KEY头部中
X-API-KEY: your-api-key
当提供了 API 密钥时，该请求的 CSRF 保护将被绕过。
来源
可以配置全局 API 密钥，以允许访问所有 API 端点，而无需用户特定的认证
设置后，此 API 密钥可在X-API-KEY头部中使用以认证请求。
来源
出于安全原因，您可以限制可上传的最大文件大小
该值必须是数字，后跟 KB、MB 或 GB。如果留空，则没有限制。
来源
下图说明了不同认证方法的认证流程
来源
当部署启用安全功能的 Stirling-PDF 时，请考虑以下最佳实践
启用 CSRF 保护：保持csrfDisabled设置为false以防止 CSRF 攻击。
使用强密码：为所有用户帐户使用强密码，特别是初始管理员帐户。
更改默认凭据：首次登录后，务必立即更改默认管理员凭据。
使用 HTTPS：将 Stirling-PDF 部署在 HTTPS 之后，尤其是在通过公共网络访问时。
限制 API 密钥访问：定期重新生成 API 密钥，并且只与受信任的方共享。
启用登录尝试限制：为loginAttemptCount和loginResetTimeMinutes设置合理的值，以防止暴力破解攻击。
限制文件上传大小：使用fileUploadLimit设置，以防止通过大文件上传进行拒绝服务攻击。
使用 OAuth2 或 SAML2：对于企业环境，考虑将 OAuth2 或 SAML2 与您组织的身份提供商集成，以实现集中认证。
定期用户审计：定期审查用户帐户，并删除或禁用未使用的帐户。
来源