OnlyOffice扫码登录设置方法

本文详细介绍了如何为 ONLYOFFICE 门户配置扫码登录功能，涵盖三种主流实现方式：基于 Authentik（SAML）、Keycloak（OIDC）的外部身份提供者集成，以及无需第三方 IdP 的 ONLYOFFICE 内置 JWT 轻量级方案；每种路径均提供从身份平台配置、回调地址设置、令牌签名要求到 ONLYOFFICE 控制面板具体参数填写的完整操作指南，帮助管理员快速搭建安全、便捷、可定制的二维码免密登录体验，显著提升内网协作或对外门户的用户访问效率与安全性。

如果您希望用户通过扫描二维码快速登录 OnlyOffice 门户，而非输入账号密码，则需启用并正确配置快捷认证（Quick Authentication）功能。该机制依赖于外部身份提供者（IdP）生成动态二维码，并由 ONLYOFFICE SP 完成扫码后的 SAML 或 OIDC 回调验证。以下是实现扫码登录的多种配置路径：

一、配置 ONLYOFFICE 与 Authentik IdP 实现扫码登录

Authentik 支持通过 SAML 流程集成动态二维码登录界面，其 QR 码由 Authentik 的“Prompt Flow”或自定义 Webhook 触发生成，ONLYOFFICE 作为 SP 接收经签名的 SAML 响应完成认证。

1、登录 Authentik 管理面板（https://authentik.yourdomain.com/if/admin/）。

2、转到流程 → 创建新流程，选择类型为“Authentication”，启用“Prompt”步骤并添加“QR Code Prompt”组件。

3、在提供商 → SAML 提供商中，确认 ACS URL 设置为 https://myportal-address.com/sso/acs，且启用“签名断言”和“签名响应”。

4、在应用程序 → 创建中，将提供商绑定至新应用，并启用“允许无会话访问”选项以支持未登录状态下的扫码入口。

5、进入 ONLYOFFICE 控制面板 → 集成 → 单点登录，粘贴 Authentik 提供商元数据 XML URL，点击加载元数据。

6、启用“快捷认证”开关，并在“扫码登录入口 URL”字段填入 https://authentik.yourdomain.com/if/flow/authenticate/qr-flow-slug/（需替换为实际流程 slug）。

二、配置 ONLYOFFICE 与 Keycloak IdP 实现扫码登录

Keycloak 可通过自定义主题与 JavaScript 扩展渲染二维码登录页，并利用其 Admin REST API 动态生成一次性登录令牌，ONLYOFFICE SP 通过 OIDC 授权码流完成后续认证。

1、以管理员身份登录 Keycloak 管理控制台，进入 Realm Settings → Themes，上传支持 QR 渲染的自定义登录主题包。

2、在 Clients → 创建客户端，Client ID 设为 onlyoffice-scan-client，Client Protocol 设为 openid-connect，Access Type 设为 public。

3、在该客户端的 Settings 标签页中，设置 Valid Redirect URIs 为 https://myportal-address.com/sso/callback，Web Origins 为 *（或限定域名）。

4、进入 ONLYOFFICE 控制面板 → 集成 → 单点登录，切换认证类型为 OIDC。

5、填写以下字段：
授权端点：https://keycloak.yourdomain.com/auth/realms/your-realm/protocol/openid-connect/auth
令牌端点：https://keycloak.yourdomain.com/auth/realms/your-realm/protocol/openid-connect/token
用户信息端点：https://keycloak.yourdomain.com/auth/realms/your-realm/protocol/openid-connect/userinfo
客户端ID 与 客户端密钥：分别填入 Keycloak 中创建的客户端对应值。

6、在“扫码登录入口 URL”字段填入 Keycloak 自定义登录页地址，例如：https://keycloak.yourdomain.com/auth/realms/your-realm/login-actions/scanning?client_id=onlyoffice-scan-client。

三、启用 ONLYOFFICE 内置 JWT 快捷认证扫码模式

ONLYOFFICE 文档服务器支持基于 JWT 的临时登录令牌，配合前端扫码组件可实现免 IdP 的轻量级快捷认证，适用于内网或受控环境。

1、编辑文档服务器配置文件：/etc/onlyoffice/documentserver/local.json，确保 token.inbox.enable 和 token.outbox.enable 均设为 true。

2、在 token.inbox.header 字段指定为 X-JWT-Token，secret.inbox.string 设置为共享密钥（如 qrcode-secret-2026）。

3、部署一个独立的扫码服务（如 Node.js Express 应用），接收扫码请求后调用 ONLYOFFICE 的 JWT 接口生成含 user.id、user.name、exp（建议 120 秒）的 JWT。

4、扫码服务返回重定向 URL：https://myportal-address.com/auth/jwt?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...，其中 token 为已签名 JWT。

5、在 ONLYOFFICE 控制面板 → 集成 → 单点登录中启用“JWT 认证”，并将“JWT 密钥”字段填入与 local.json 中一致的密钥字符串。

6、确保 ONLYOFFICE 门户的 Nginx/Apache 配置中，/auth/jwt 路径被代理至文档服务器的 coauthoring service。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~