SpacetimeDB SpacetimeAuth 项目创建指南为 Maincloud 模块启用内置 OIDC 身份认证【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDBSpacetimeAuth 是 SpacetimeDB 为托管在 Maincloud 上的模块提供的内置身份认证服务它基于 OpenID ConnectOIDC协议实现使开发者无需搭建额外认证服务器即可完成用户注册、登录与授权。本文以官方 Creating a project 文档为主体完整梳理从部署模块、启用服务到探索项目仪表盘的每一步操作并结合仓库内的 配置指南、测试指南 与认证声明使用文档帮助你在读完本文后能够独立创建、配置并验证一个 SpacetimeAuth 项目并把它接入 SpacetimeDB 模块的 reducer 鉴权逻辑。1. SpacetimeAuth 是什么先理解几个核心概念在动手之前先明确 SpacetimeAuth 在 SpacetimeDB 架构中的位置。根据 SpacetimeAuth 总览SpacetimeAuth 是用于管理 SpacetimeDB 应用认证的服务允许你在不依赖外部认证服务、甚至不需要自建托管服务器的情况下完成用户认证。它本身是一个OIDC Provider因此可以与任何兼容 OIDC 的客户端库配合使用。认证流程结束时你的应用会收到一个包含身份声明identity claims如 email、username、roles的ID Token随后可以借助任何 SpacetimeDB SDK 用这个 Token 向 SpacetimeDB 服务器完成用户的认证与授权。SpacetimeAuth 引入了几组容易混淆的术语创建项目前务必厘清术语含义Project项目管理认证的逻辑单元每个项目拥有独立的用户、角色、认证方式以及独立的邮件模板、网页等配置。项目与 SpacetimeDB 数据库相互独立可被一个或多个数据库共用User用户通过 SpacetimeAuth 认证到应用的个体拥有唯一用户 ID可被分配一个或多个角色Client客户端OIDC 术语中的 Relying Party即依赖 SpacetimeAuth 完成认证的应用。每个客户端绑定一个项目拥有自己的 client ID 与 client secret。注意Client 与 User 是两回事Role角色用于应用内访问控制的字符串如admin、user可分配给一个或多个用户并作为 claim 写入签发给用户的 ID Token项目Project的独立性带来几个典型的组织方式同一数据库被 Web 应用和移动应用共用可创建一个SpacetimeAuth 项目两个应用共享同一用户基不同环境dev / staging / production各有一个数据库可为每个环境创建独立项目从而隔离各环境的用户不同应用各有数据库可为每个应用创建独立项目隔离应用之间的用户。Beta 提示SpacetimeAuth 目前处于 beta 阶段部分功能可能尚未开放或后续会调整使用过程中可能遇到缺陷。官方文档要求在使用服务时将遇到的问题反馈给官方以帮助改进因此在生产环境大规模接入前应做好回归验证。2. 前提条件先把模块发布到 MaincloudSpacetimeAuth 是为发布在 Maincloud 上的模块提供的服务因此在启用之前你必须先把模块发布到 Maincloud。完整步骤见 Deploy to Maincloud 指南核心流程如下安装 SpacetimeDB CLI执行spacetime login用 GitHub 或 Google 账号完成浏览器登录将 CLI 身份与 Maincloud 网页账号绑定若此前未登录就发布过数据库需先spacetime logout再spacetime login重新绑定发布模块spacetime publish my-database --server maincloudSpacetimeDB 会编译你的模块、上传、运行initreducer若有定义并输出数据库身份database identity请妥善保存该身份用于后续管理操作。重复执行同一条命令即可热更新模块且不会断开已连接的客户端。模块发布成功后数据库仪表盘dashboard的左侧边栏中便会出现SpacetimeAuth入口这就是开启认证服务的大门。3. 分步启用 SpacetimeAuth从仪表盘到项目创建如果你还没有部署模块请先参考上一节的 Maincloud 发布流程完成部署。以下步骤基于 Creating a project 文档确保模块已发布到 Maincloud进入已部署模块的仪表盘有三种方式可以到达点击页面右上角的头像在下拉菜单中选择My profile从你已部署模块的列表中选择目标模块。进入模块后看到的就是模块仪表盘在左侧边栏中点击SpacetimeAuth点击Use SpacetimeAuth按钮完成启用。启用动作会为你创建默认项目同时自动创建一个默认客户端default client——也就是说创建项目后你可以立刻用它发起认证流程无需再手工配置。从仓库源码结构看认证相关的 JWT 校验逻辑集中在 crates/core/src/auth/mod.rs包含JwtKeys、EcKeyPair等密钥与签名实现与 crates/core/src/auth/token_validation.rs包含 issuer 校验、token 重签等测试这印证了 SpacetimeAuth 签发的 Token 最终会由 SpacetimeDB 服务器端进行验签与校验。4. 探索项目仪表盘五大标签页各司其职启用成功后你会进入 SpacetimeAuth 项目仪表盘。仪表盘通过多个标签页管理项目的不同方面Overview总览项目摘要包含近期用户列表。它是查看项目整体状态的第一站Clients客户端列出所有可用于应用认证的客户端。创建项目时系统会自动创建一个默认客户端你也可以在此新建更多客户端Users用户项目内所有用户的列表支持搜索、过滤和管理用户Identity Providers身份提供商项目可用的第三方身份提供商如 Google、GitHub 等列表用于让用户使用已有账号登录Customization自定义实时编辑器用于自定义登录页的颜色、Logo 以及认证方式例如开启/关闭匿名认证与魔法链接认证。说明原文档的章节编号从## 1跳到## 4本文按实际操作逻辑重新组织了顺序——创建项目、探索仪表盘、配置客户端/身份提供商、验证测试最后进入下一环节。5. 配置客户端ClientsRedirect URI 与 Scope 详解创建项目只是第一步。创建项目的下一站就是配置完整操作见 Configuring your project。5.1 客户端是什么客户端代表将使用 SpacetimeAuth 进行认证的应用。每个客户端拥有独立的名称、Redirect URIs、Post Logout Redirect URIs 等设置。绝大多数项目只需要一个客户端就能完成模块的用户认证只有当你有多个应用如 sidecar、管理后台且希望为它们使用不同认证流程或设置时才需要创建多个客户端。创建或编辑客户端时可配置以下字段字段说明Name客户端名称例如My Web AppRedirect URIs登录成功后 SpacetimeAuth 允许重定向回应用的 URI 列表必须与应用实际使用的 URI 完全一致Post Logout Redirect URIs退出登录后允许重定向回的 URI 列表同样必须与应用一致5.2 客户端密钥安全危险提示务必妥善保管 client secret绝不要把它放进客户端代码或公开仓库中。client ID 可以放心公开因为它不是敏感信息。Client secret 仅在client_credentials流程中使用通过该流程可以拿到一个不带用户上下文的 Token此时subclaim 会被设为 client ID。5.3 Scopes 与 Claims目前 Scope尚不可编辑固定为openid、profile和email三个。这三个 Scope 对绝大多数应用已足够它们覆盖了认证用户所需的全部关键信息。各 Scope 对应的 ID Token claims 如下ScopeClaimsopenid必选sub唯一用户标识profilename、family_name、given_name、middle_name、nickname、preferred_username、picture、website、gender、birthdate、zoneinfo、locale、updated_atemailemail、email_verified在应用发起认证流程时可以请求全部或部分 Scope例如只需要邮箱验证时可省略profile。5.4 Redirect URI 的匹配规则Redirect URI 是 OAuth2 / OIDC 流程的关键安全环节它保证用户认证成功后只会被重定向回你信任的应用位置。配置时必须与应用的 URI逐字符匹配包括协议http/https、域名、端口如有和路径。例如应用托管在https://myapp.com从https://myapp.com/login发起认证流程那么可以设置 Redirect URI 为https://myapp.com/callback。至于应用侧到底该填什么 URI请以你所使用的认证库文档为准或参考仓库内的 React 集成指南 等框架集成文档。6. 配置第三方身份提供商一行表看懂回调地址SpacetimeAuth 支持多个第三方身份提供商让用户用既有账号直接登录。目前已支持 Google、GitHub、Discord、Twitch、Kick未来还会增加更多。第三方身份提供商的用户信息会被映射为 SpacetimeAuth 使用的标准 OIDC claims从而保证无论用户用哪个提供商登录应用拿到的数据模型都一致。例如提供商的 username 会被映射到标准的preferred_usernameclaim。在仪表盘的Identity Providers标签页中可以管理提供商。由于 SpacetimeAuth 此时扮演外部身份提供商的客户端client你需要从提供商的开发者控制台developer console获取 client ID 与 client secret 并填入在提供商的开发者控制台把回调地址配置为指向 SpacetimeAuth地址见下表按需启用/禁用该提供商点击Save保存提供商即出现在应用的登录页上。各提供商需要在开发者控制台配置的回调地址Redirect URIProviderRedirect URIGooglehttps://auth.spacetimedb.com/interactions/federated/callback/googleGitHubhttps://auth.spacetimedb.com/interactions/federated/callback/githubDiscordhttps://auth.spacetimedb.com/interactions/federated/callback/discordTwitchhttps://auth.spacetimedb.com/interactions/federated/callback/twitchKickhttps://auth.spacetimedb.com/interactions/federated/callback/kick7. 写代码前先验证用 OIDC Debugger 跑通整个流程在编写应用代码之前官方建议先用 OIDC Debugger 快速验证客户端与 Redirect URI 是否配置正确。详细步骤见 Testing 指南。OIDC Debugger 会在浏览器中模拟完整的 OAuth2/OIDC Authorization Code 流程可用于确认 Redirect URIs 配置正确验证 client ID 可用检查 ID Token 与其中的 claimsemail、sub、preferred_username等在写任何代码之前发现配置问题。Step 1 — 收集配置记下以下端点与参数项值Authorization Endpointhttps://auth.spacetimedb.com/oidc/authToken Endpointhttps://auth.spacetimedb.com/oidc/tokenClient ID从 SpacetimeAuth 仪表盘获取任意可用客户端Redirect URIhttps://oidcdebugger.com/debug需先在仪表盘中加入该客户端的允许列表Step 2 — 打开 OIDC Debugger并按下表填写其余字段保持默认如 response type code、state、nonce字段值Authorize URIhttps://auth.spacetimedb.com/oidc/authClient ID你的 SpacetimeAuth client IDScopeopenid profile email或其子集Use PKCE?勾选Token URIhttps://auth.spacetimedb.com/oidc/token由于该工具运行在浏览器中此处无需填写 client secret。Step 3 — 运行流程点击Send Request→ 通过任一已配置的提供商登录 SpacetimeAuth → 被重定向回 OIDC Debugger 并获得 authorization code → 工具自动用 code 换取 Token 并展示结果。Step 4 — 检查 Token根据请求的 Scope你会得到一个类似下面的 ID Token可用任意 JWT 解码器查看其中的 claims{ sub: user_ergqg1q5eg15fdd54, project_id: project_xyz123, email: userexample.com, email_verified: true, preferred_username: exampleuser, first_name: Example, last_name: User, name: Example User }注意project_id字段——它正是你创建的这个 SpacetimeAuth 项目在 Token 中的体现后续应用侧可通过它区分不同项目签发的 Token。8. 把 Token 用起来在 reducer 中读取认证声明创建并配置好项目之后真正落地的一步是把 ID Token 交给 SpacetimeDB 模块使用。SpacetimeDB 允许在 reducer 中直接访问 JWT 中携带的认证声明auth claims具体用法见 Using Auth Claims。以 Rust 模块为例在client_connectedreducer 中读取sub与iss#[reducer(client_connected)] pub fn connect(ctx: ReducerContext) - Result(), String { let auth_ctx ctx.sender_auth(); let (subject, issuer) match auth_ctx.jwt() { Some(claims) (claims.subject().to_string(), claims.issuer().to_string()), None { return Err(Client connected without JWT.to_string()); } }; log::info!(sub: {}, iss: {}, subject, issuer); Ok(()) }使用 SpacetimeAuth 时的两个安全实践同样来自该文档限制 issuer任何合法签发的 Token 都可能被用来连接你的模块因此应在连接时校验iss只接受https://auth.spacetimedb.com/oidc签发的 Token防止接受来自其他 OIDC 提供商的 Token校验 audience务必检查audclaim 是否为你的 client ID确保签发给你应用的 Token 不会被其他应用复用。角色roles也会作为 claim 写入 ID Token。在 reducer 中可以通过解析完整 JWT payload 来读取roles数组并做基于角色的访问控制RBAC例如只允许admin角色调用特定 reducer。9. 下一步继续深入配置与集成至此你已经完成了 SpacetimeAuth 项目从无到有的完整创建流程。接下来可以根据应用需求继续深入配置项目Configuring your project管理客户端、设置第三方身份提供商、定制登录主题测试配置Testing用 OIDC Debugger 验证端到端流程React 集成指南基于react-oidc-context将 SpacetimeAuth 接入 React 应用使用认证声明Using Auth Claims在 TypeScript / C# / Rust / C 四种语言中消费 JWT claims 并实现授权逻辑若需对比外部认证方案可参考仓库内的 Auth0、Clerk、BetterAuth 文档。核心要点回顾SpacetimeAuth 项目与数据库相互独立可一库一项目、也可一库多项目默认客户端开箱即用多应用场景才需要新增客户端Scope 目前固定为openid、profile、emailclient secret 仅在client_credentials流程使用且严禁暴露接入模块后务必在 reducer 中校验iss与aud以收紧安全边界。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考