认证 | ObjectOS

ObjectOS 使用由 Better Auth 驱动的 ObjectStack 认证插件。认证是项目本地的：每个项目拥有独立的身份表和会话作用域。

支持的能力

视所打包的应用和已启用的设置而定，ObjectOS 可支持：

邮箱/密码登录；
会话管理；
密码重置和邮箱验证；
Google、GitHub、Microsoft、Apple 等社交 OAuth Provider；
Okta、Entra ID、Keycloak、Ping 等企业级 OIDC/SSO；
双因素认证；
Passkey/WebAuthn；
魔法链接；
手机号登录与短信 OTP（需显式开启）；
CLI/浏览器设备流程。

手机号登录与短信（ObjectStack 14.3+）

通过 auth.plugins.phoneNumber 设置开启手机号认证。开启后：

POST /sign-in/phone-number 接受手机号 + 密码登录；
短信 OTP 覆盖登录验证和自助密码重置，并自带按号码冷却、滚动小时上限和按 IP 限流；
sys_user 增加唯一的 phone_number 与 phone_number_verified 列；仅手机号账户会获得占位邮箱。

短信发送由 @objectstack/plugin-sms 提供，支持阿里云短信、Twilio 或开发环境日志回退，通过 sms 设置命名空间配置。含 OTP 验证码的消息体永不持久化或写入日志。通知也可以通过 notify(channels: ['sms']) 走 sms 通道。

管理员用户管理（ObjectStack 14.3+）

平台管理员可以不经邮件邀请流程直接开通账户：

POST /api/v1/auth/admin/create-user 直接创建用户，可选生成一次性密码（仅返回一次，不持久化）。must_change_password 标志强制首次登录时修改密码（未修改前返回 403 PASSWORD_EXPIRED）。
POST /api/v1/auth/admin/import-users 批量导入行 / CSV / XLSX（每次请求最多 500 行），支持 dry-run 和按邮箱或手机号 upsert；已存在用户的密码永不重置。自 16.0 起，默认 passwordPolicy 为 'auto'：具有可送达通道的行（真实邮箱 + 已接通的邮件服务，或手机号 + 短信邀请通道）会被邀请，只有无法触达的行才得到临时密码（仅返回一次，must_change_password）。依赖旧的仅建身份默认行为的调用方现在必须显式传入 passwordPolicy: 'none'；每行结果在 rows[].delivery 上，并附 summary.delivery 汇总。

必需的 Secret

设置：

OS_AUTH_SECRET=replace-with-a-strong-random-secret

ObjectOS 基于该值和项目环境 id 派生稳定的项目级 secret。这意味着：

会话能在容器重启后保持；
一个项目的 token 不能在另一个项目中复用；
轮换 OS_AUTH_SECRET 会使会话失效。

完整的认证相关设置列表（包括旧版 AUTH_SECRET 别名）请参阅 Environment variables。

会话隔离

在多项目部署中，Cookie 限定到项目主机名。ObjectOS 故意避免使用宽泛的根域 Cookie 作为项目会话——以防止会话跨客户项目泄漏。

社交登录

通过环境变量或系统设置配置 Provider 凭据，具体取决于应用包暴露认证配置的方式。

Provider 回调 URL 取决于 Provider 类型。ObjectStack 暴露了两条不同的回调路径，并且它们不可互换：

Provider 类型	回调路径
内置社交（Google、GitHub、Microsoft、Apple ……）	`/api/v1/auth/callback/<provider>`
通用 OIDC / OAuth2（Okta、Entra ID、Keycloak、Ping ……）	`/api/v1/auth/oauth2/callback/<provider>`

示例：

https://crm.example.com/api/v1/auth/callback/google
https://crm.example.com/api/v1/auth/callback/microsoft
https://crm.example.com/api/v1/auth/oauth2/callback/okta
https://crm.example.com/api/v1/auth/oauth2/callback/entra

在 ObjectOS 中启用 Provider 前，先在身份提供方的应用注册中配置匹配的 redirect URI。

企业级 OIDC/SSO

OIDC Provider 注册为通用 OAuth2 Provider，使用 /api/v1/auth/oauth2/callback/<provider> 路径。典型配置需要：

字段	说明
Provider id	稳定 id，例如 `okta` 或 `entra`（用于回调 URL）
显示名	给用户看的按钮文案
Discovery URL	`.well-known/openid-configuration` 端点
Client id	来自身份提供方的应用 client id
Client secret	存于环境变量或加密设置
Scopes	通常为 `openid email profile`

对客户部署，优先使用 OIDC discovery URL，而不是手工配置 authorization/token/userinfo 端点。

平台 SSO

在云连接部署中，ObjectOS 可以使用控制面登录作为平台 SSO Provider。已经登录控制面的建设者无需创建独立的项目本地账户即可被预置到项目运行时。

这要求控制面与 ObjectOS 共享同一个 OS_AUTH_SECRET 基础 secret。仅在客户希望每个项目拥有完全独立的登录边界时才禁用平台 SSO。

运行检查

上线前：

确认过期 token 返回 401；
确认登出会撤销活动会话；
如策略需要，确认密码重置会撤销其他会话；
确认回调 URL 与公开的项目域名一致；
确认可信 origin 仅包含已批准的域名；
确认 OS_AUTH_SECRET 存于 secret manager，而不是源码。

后续步骤

认证确立的是用户是谁。要控制用户登录后能访问什么，请参阅 Permissions。对于非浏览器客户端和机器对机器的访问，请参阅 API access。

认证

On this page