SpacetimeDB SpacetimeAuth 项目配置完全指南：Clients、Scopes 与第三方身份提供商-迪斯科星球

SpacetimeDB SpacetimeAuth 项目配置完全指南：Clients、Scopes 与第三方身份提供商

【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB

SpacetimeAuth 是 SpacetimeDB 提供的一项内置认证服务，无需外部认证服务或额外托管服务器，即可为部署在 Maincloud 上的模块提供 OpenID Connect（OIDC）认证能力。本文基于 configuring-a-project.md 官方文档，系统讲解 SpacetimeAuth 项目的核心配置项：客户端（Clients）管理、作用域（Scopes）与声明（Claims）、重定向 URI（Redirect URIs）以及 Google、GitHub、Discord 等第三方身份提供商的接入方法。读完本文，你将能够独立完成一个 SpacetimeAuth 项目的完整配置，并理解配置背后的 OIDC 原理与 SpacetimeDB 服务端的 claim 解析机制。

:::warning SpacetimeAuth 目前处于 beta 阶段，部分功能可能尚未开放或会在未来发生变化。使用过程中可能遇到 bug 或问题，欢迎反馈问题以帮助改进该服务。 :::

配置前须知：项目、客户端与身份提供商的关系

在动手配置之前，需要先厘清几个核心概念。SpacetimeAuth 使用"项目（Project）"为单位来管理认证：

每个项目拥有自己独立的用户集、角色集和认证方式；
每个项目拥有自己独立的邮件模板、网页等配置；
每个项目与 SpacetimeDB 数据库解耦，可被一个或多个数据库共用。

关于项目的完整概念（Projects、Users、Clients、Roles 四类实体及其典型使用场景），可参阅 SpacetimeAuth 概述。本文聚焦于项目创建之后的配置环节——即文档 00300-configuring-a-project.md 所覆盖的内容。

若你尚未创建 SpacetimeAuth 项目，请先完成前置步骤：将模块部署到 Maincloud（参考部署到 Maincloud 指南），然后在模块 Dashboard 左侧边栏点击 "SpacetimeAuth"，点击 "Use SpacetimeAuth" 按钮启用，并按照创建项目指南完成项目的初始化。每个新项目都会自动创建一个默认客户端，可以直接用于开始集成。

管理客户端（Managing Clients）

什么是客户端

客户端（Client）代表使用 SpacetimeAuth 进行认证的应用程序。在 OpenID Connect 术语中，客户端又称依赖方（Relying Party）——即依赖 SpacetimeAuth 完成认证、并以此获取 OIDC ID Token 的应用程序。

每个客户端都关联到唯一的项目，并拥有自己独立的配置项，包括：

重定向 URI（Redirect URIs）：允许 SpacetimeAuth 在登录成功后把用户重定向回的位置；
登出后重定向 URI（Post Logout Redirect URIs）：允许 SpacetimeAuth 在登出后把用户重定向回的位置；
名称（Name）：客户端名称，例如 "My Web App"。

在项目 Dashboard 中切换到 "Clients" 标签页即可管理客户端。每个项目自带一个默认客户端，可直接用于快速上手；点击 "Create Client" 按钮可以创建更多客户端。

需要几个客户端？

大多数项目只需要一个客户端即可完成用户对 SpacetimeDB 模块的认证。但是，如果你有多个应用程序（例如一个主应用加一个 sidecar、管理后台等），并希望为每个应用使用不同的认证流程或不同的设置，则可以创建多个客户端。

典型的拆分场景包括：

Web 应用与移动应用共用同一个 SpacetimeDB 数据库，但希望各自拥有独立的重定向 URI 配置；
主应用与管理后台希望采用不同的安全策略（如是否启用client_credentials流程）；
开发环境、预发布环境、生产环境使用独立的客户端配置。

创建或编辑客户端时的配置项

配置项	说明
Name	客户端名称，例如 "My Web App"。
Redirect URIs	SpacetimeAuth 允许在登录成功后重定向用户到这些 URI。它们必须与应用中实际使用的 URI 完全匹配。
Post Logout Redirect URIs	SpacetimeAuth 允许在登出后重定向用户到这些 URI。它们同样必须与应用中实际使用的 URI 完全匹配。

:::danger务必妥善保管客户端密钥（client secret），绝不能将其暴露在客户端代码或公开仓库中。客户端 ID 不是敏感信息，可以放心公开分享。客户端密钥仅在client_credentials流程中使用，该流程允许在没有用户上下文的情况下获取令牌（此时令牌中的sub声明会被设置为客户端 ID）。 :::

服务端视角：客户端令牌如何被解析

从源码结构可以进一步理解client_credentials流程与身份令牌在服务端是如何被处理的。SpacetimeDB 服务端通过 crates/auth/src/identity.rs 中定义的IncomingClaims结构解析 JWT 载荷，其中sub（subject）、iss（issuer）、aud（audience）、iat、exp是核心声明字段，其余所有自定义声明（例如角色）通过#[serde(flatten)]落入extra字段。解析时，服务端会基于issuer与subject计算出一个确定的Identity（见Identity::from_claims），并校验令牌中携带的hex_identity与该计算结果一致，从而保证每个认证主体在 SpacetimeDB 中拥有稳定的身份。

这也意味着：client_credentials流程中sub被设为客户端 ID 时，服务端会据此派生出一个与"客户端"对应的确定性身份，供无用户上下文的机器对机器（M2M）场景使用。

作用域与声明（Scopes and Claims）

当前支持的作用域

作用域（Scope）目前尚不可编辑，仅限以下三种，且基本能满足绝大多数应用的认证信息需求：

openid
profile
email

在应用发起认证流程时，可以请求全部作用域，也可以请求其中一部分。

各作用域提供的声明

声明（Claims）即 ID Token 中携带的用户信息。各作用域对应的声明如下表：

作用域	声明
openid（必需）	`sub`（唯一用户标识符）
profile	`name`、`family_name`、`given_name`、`middle_name`、`nickname`、`preferred_username`、`picture`、`website`、`gender`、`birthdate`、`zoneinfo`、`locale`、`updated_at`
email	`email`、`email_verified`

openid是 OpenID Connect 协议强制要求的作用域，无论请求与否，ID Token 中都会包含sub声明。

源码层面的声明结构印证

SpacetimeDB 服务端对 JWT 声明的建模位于 crates/auth/src/identity.rs 的SpacetimeIdentityClaims结构体：它显式定义了identity（映射为 JWT 的hex_identity）、subject（sub）、issuer（iss）、audience（aud）、iat、exp，并将所有其他声明扁平化合并到extra字段。该结构的单元测试（同文件 identity.rs）验证了aud既可以是一个字符串也可以是字符串数组、缺失时默认为空数组，以及时间戳iat/exp的秒级解析逻辑——这为理解 SpacetimeAuth 下发的 ID Token 结构提供了可靠的实现依据。

另外，客户端接入层 crates/client-api/src/auth.rs 中的SpacetimeAuth结构承载了请求携带的凭证（SpacetimeCreds）、解析后的声明（SpacetimeIdentityClaims）以及原始 JWT 载荷字符串，服务端再将其转换为ConnectionAuthCtx供后续连接与 reducer 鉴权使用。新令牌由JwtKeyAuthProvider使用 ES256 算法签名（见 auth.rs），并在签发时自动附加iat与可选的exp。

重定向 URI（Redirect URIs）

为什么它如此关键

重定向 URI 是 OAuth2 与 OpenID Connect 流程中的关键安全机制。它保证用户完成认证后，只会被重定向回你应用中的可信位置，而不是任意第三方地址。

配置匹配规则

配置重定向 URI 时，必须确保它与应用中实际使用的 URI完全一致，包括以下每个组成部分：

协议（scheme）：http或https；
域名（domain）；
端口（port）（若适用）；
路径（path）。

例如，如果应用托管在https://myapp.com，并从https://myapp.com/login发起认证流程，那么可以设置重定向 URI 为https://myapp.com/callback。

如何确定正确的重定向 URI

请参考你所使用认证库的文档，或查阅 SpacetimeAuth 与各类框架的集成指南（例如 React 集成指南）来确定应用中应该配置的重定向 URI。

设置第三方身份提供商（Third-Party Identity Providers）

支持的提供商

SpacetimeAuth 支持多个第三方身份提供商，允许用户使用已有的第三方账号完成认证。目前支持的提供商包括：

Google
GitHub
Discord
Twitch
Kick

未来还会陆续添加更多提供商。

声明的标准化映射

来自第三方身份提供商的用户信息会被映射为 SpacetimeAuth 使用的标准 OpenID Connect 声明，从而保证无论用户使用哪个提供商登录，应用侧获得的用户体验都是一致的。例如，提供商的用户名声明会被映射为标准preferred_username声明。

配置步骤

在项目 Dashboard 中切换到 "Identity Providers" 标签页；
由于 SpacetimeAuth 在此处扮演的是外部身份提供商的客户端，你需要提供从该提供商开发者控制台申请的client ID 和 client secret；
在提供商的开发者控制台中，将回调地址配置为指向 SpacetimeAuth（具体地址见下表）；
选择启用（enable）或禁用（disable）该提供商；
点击 "Save" 保存。此后该提供商便会出现在应用的登录页上。

各提供商的回调 URI

启用每个提供商时，需要在对应提供商的开发者控制台中配置如下回调 URI：

提供商	回调 URI
Google	`https://auth.spacetimedb.com/interactions/federated/callback/google`
GitHub	`https://auth.spacetimedb.com/interactions/federated/callback/github`
Discord	`https://auth.spacetimedb.com/interactions/federated/callback/discord`
Twitch	`https://auth.spacetimedb.com/interactions/federated/callback/twitch`
Kick	`https://auth.spacetimedb.com/interactions/federated/callback/kick`

各提供商 OAuth 应用创建指引

为帮助你在各提供商的控制台中创建所需的 OAuth 应用（有时称为 OAuth App 或 OAuth Client），官方文档给出了对应指引，要点如下：

Google：在 Google Cloud 开发者控制台（Google API Console）中获取 Google API 客户端 ID，创建 OAuth 2.0 客户端后按上表配置授权回调 URI；
GitHub：在 GitHub 的 OAuth Apps 设置中创建 OAuth App，填写回调 URL 并生成 Client secret；
Discord：在 Discord 开发者门户中创建一个 Application，作为 OAuth2 客户端并配置重定向地址；
Twitch：在 Twitch 开发者后台注册应用（Register App），获取 Client ID 与 Client Secret 并配置 OAuth 回调；
Kick：在 Kick 的开发者文档指引下完成 Kick Apps 设置。

创建完成后，将获取到的 client ID 与 client secret 填入 SpacetimeAuth Dashboard 的 "Identity Providers" 标签页并保存即可。

配置完成后的验证与下一步

开始集成

配置并验证通过后，即可将 SpacetimeAuth 集成到你的应用：

若使用 React，参考 React 集成指南；
认证流程结束时应用会获得包含身份声明的 ID Token（如邮箱、用户名、角色），随后即可配合任意 SpacetimeDB SDK 向服务端认证并授权用户。

小结

SpacetimeAuth 项目配置的核心可以概括为三件事：管理好客户端（含重定向 URI）、按需请求作用域以获得对应声明、接入第三方身份提供商并正确配置回调 URI。其中重定向 URI 的精确匹配与客户端密钥的安全保管是安全底线；作用域与声明的对应关系决定了应用能拿到哪些用户信息；而第三方提供商接入的关键在于双向配置——既要在 SpacetimeAuth 侧填入 provider 的 client ID/secret，也要在 provider 侧把回调指向https://auth.spacetimedb.com/interactions/federated/callback/<provider>。结合 crates/auth/src/identity.rs 与 crates/client-api/src/auth.rs 的源码，可以更深入地理解这些配置最终如何转化为服务端可验证、可鉴权的身份声明。

【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析