SnapOtter OIDC/SSO配置教程:3步接入Google、GitHub与Okta单点登录【免费下载链接】SnapOtterOpen-source, self-hosted file-processing tool. Convert, compress, OCR, transcribe run local AI across image, video, audio, PDF documents, via UI, REST API pipelines. Your files never leave your network.项目地址: https://gitcode.com/gh_mirrors/st/SnapOtterSnapOtter是一款开源、自托管的文件处理工具支持转换、压缩、OCR、转写和运行本地 AI而它的OIDC 单点登录SSO功能可以让你用 Google、GitHub 或 Okta 账户直接登录彻底告别为每个用户维护密码的麻烦。本教程带你3 步完成配置全程无需修改代码。为什么要给文件处理工具加 SSO团队共享一台 SnapOtter 时本地账户密码意味着要手动开号、手动分配权限、离职后手动清理。接入 OIDC/SSO 后✅ 成员用公司 IdPGoogle Workspace、GitHub、Okta 等一键登录零密码下发✅ 新用户登录时自动创建账号默认开启并分配默认角色✅ 可把 IdP 身份与已有本地账号自动关联老用户无感迁移✅ 登录日志、MFA 策略与本地登录完全一致审计不缺位SnapOtter 的 SSO 由两个核心模块实现OIDC 走 plugins/oidc.tsSAML企业版走 plugins/saml.ts。两者共享同一个用户解析器 lib/external-auth-resolver.ts所以行为一致。准备工作先确认 3 件事在动手前确认你的部署满足以下条件已部署 SnapOtter通过 Docker Compose 部署参考 docker-compose.yml或源码部署均可有可访问的EXTERNAL_URL即浏览器访问 SnapOtter 的完整地址如https://files.example.com。启用 SSO 时该变量必填且路径必须与BASE_PATH一致否则登录会因 state 校验失败有 IdP 管理权限能在 Google Cloud Console / GitHub / Okta 创建应用第 1 步在身份提供商IdP创建 OIDC 应用三种主流 IdP 的操作路径都类似创建一个OIDC/OAuth 客户端拿到 Issuer、Client ID、Client Secret并登记回调地址。Google Workspace / Google Cloud进入 Google Cloud Console → 凭据 → 创建OAuth 客户端应用类型选Web在已获授权的重定向 URI中填入注意必须是 SnapOtter 的完整公网地址 固定路径https://你的域名/api/auth/oidc/callback记下 Client ID 与 Client SecretIssuer URL 固定为https://accounts.google.com确认 Google 应用已申请openid、profile、email这三个 scope 对应的数据访问GitHub进入 GitHub → Settings → Developer settings → OAuth Apps或 OAuth Apps 新入口创建应用回调地址同样填https://你的域名/api/auth/oidc/callbackIssuer URL 为https://github.com/login/oauth/openidOkta控制台 → Applications → Add Application → OIDCSign-in URL 填https://你的域名Allowed POST redirect URIs 填https://你的域名/api/auth/oidc/callbackIssuer URL 为你的租户地址https://你的租户名.okta.com 三个 IdP 的共同点回调路径永远是/api/auth/oidc/callback由 SnapOtter 自动发现元数据discovery完成其余握手你不需要填授权端点、令牌端点等细节。第 2 步配置 SnapOtter 环境变量拿到 IdP 凭证后编辑 Docker Compose 配置。docker/docker-compose.yml 中已内置了完整的 OIDC 配置注释块约第 67–87 行直接取消注释并填值即可。核心变量如下变量必填默认值说明OIDC_ENABLED✅false设为true开启OIDC_ISSUER_URL✅—IdP 发现地址上一步的值OIDC_CLIENT_ID✅—应用 Client IDOIDC_CLIENT_SECRET✅—应用 Client SecretEXTERNAL_URL✅—公网访问地址如https://files.example.comOIDC_SCOPES⬜openid profile email请求的权限范围OIDC_AUTO_CREATE_USERS⬜true首次登录自动建号OIDC_DEFAULT_ROLE⬜user自动建号的角色OIDC_AUTO_LINK_USERS⬜false按邮箱自动关联本地老账号OIDC_PROVIDER_NAME⬜—登录页按钮显示的名称OIDC_USERNAME_CLAIM⬜preferred_username取哪个声明作为用户名OIDC_CLOCK_TOLERANCE⬜30时钟容差秒解决服务器时间偏差这些变量的完整定义与启动校验逻辑见 lib/env.ts。两个值得注意的细节密钥走文件更安全Compose 注释中还提供了OIDC_CLIENT_SECRET_FILE/run/secrets/oidc_secret启动脚本 entrypoint.sh 支持从文件读取密钥避免明文写在 YAML 里用户名推导链登录成功后SnapOtter 按「指定 claim →preferred_username→ 邮箱前缀 → 姓名 → subject」的顺序推导用户名逻辑在 plugins/oidc.ts 的deriveUsername无需你手工维护映射表第 3 步重启并验证登录docker compose up -d --force-recreate打开https://你的域名/login你会看到登录页出现 IdP 的登录按钮按钮名由OIDC_PROVIDER_NAME决定点击后跳转到 IdP 登录页授权后自动回跳用户自动创建并进入主界面角色为OIDC_DEFAULT_ROLE验证排障清单现象原因与处理登录页无 SSO 按钮OIDC_ENABLED未设为true或未重启容器oidc_provider_unreachableIssuer URL 不可达检查 DNS / 防火墙 / 证书oidc_session_expiredEXTERNAL_URL与BASE_PATH路径不一致或 cookie 被浏览器拦截需 HTTPSoidc_user_not_authorizedOIDC_AUTO_CREATE_USERSfalse且该 IdP 身份未绑定本地账号IdP 报重定向 URI 不匹配回调地址少了协议头或末尾斜杠必须是https://域名/api/auth/oidc/callback时间相关校验失败调大OIDC_CLOCK_TOLERANCE进阶Okta 等企业 IdP 的 SAML 接入如果你的组织只发 SAML 断言如 Okta、Azure AD 的传统配置SnapOtter 也提供 SAML 2.0 支持企业版许可saml_sso功能开关。与 OIDC 的关键区别需要额外提供 IdP 证书与 SSO URLSAML_IDP_CERTIFICATE、SAML_IDP_SSO_URL均为必填IdP 配置时需要导入 SnapOtter 的 SP 元数据直接访问https://你的域名/api/auth/saml/metadata获取 XMLACS 回调地址https://你的域名/api/auth/saml/callback用户名/邮箱取自 SAML 断言属性SAML_USERNAME_ATTRIBUTE与SAML_EMAIL_ATTRIBUTE默认emailSAML 的完整握手与防重放校验InResponseTo绑定实现在 plugins/saml.ts基于 Redis 缓存请求 ID多实例部署也安全。常见问题速查QSSO 登录还能用密码登录吗可以两种方式并存登录页同时显示本地登录与 SSO 按钮。Q本地老账号怎么绑到 IdP开启OIDC_AUTO_LINK_USERStrue后IdP 邮箱与本地账号邮箱一致时自动关联也可由管理员在用户管理中手工绑定。Q登出会同步登出 IdP 吗会。如果 IdP 元数据提供了end_session_endpointSnapOtter 会在登出时发起 RP 发起的登出见 plugins/oidc.ts 的getOidcEndSessionEndpoint。Q和 MFA 是什么关系完全兼容。若用户已启用 TOTPOIDC/SAML 登录成功后仍会按 MFA 策略弹出二次验证安全策略不因 SSO 而绕过。参考资料环境变量完整定义apps/api/src/lib/env.tsOIDC 登录流程源码apps/api/src/plugins/oidc.tsSAML 登录流程源码apps/api/src/plugins/saml.ts用户解析与自动建号apps/api/src/lib/external-auth-resolver.tsDocker 部署配置含 OIDC 注释块docker/docker-compose.yml会话与登出逻辑apps/api/src/plugins/auth.ts按本文 3 步操作大约 10 分钟即可让你的 SnapOtter 接入企业级单点登录——文件不出内网登录交给 IdP管理从此省心 【免费下载链接】SnapOtterOpen-source, self-hosted file-processing tool. Convert, compress, OCR, transcribe run local AI across image, video, audio, PDF documents, via UI, REST API pipelines. Your files never leave your network.项目地址: https://gitcode.com/gh_mirrors/st/SnapOtter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考