SpacetimeDB SpacetimeAuth 项目配置完全指南Clients、Scopes 与第三方身份提供商【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDBSpacetimeAuth 是 SpacetimeDB 提供的一项内置认证服务无需外部认证服务或额外托管服务器即可为部署在 Maincloud 上的模块提供 OpenID ConnectOIDC认证能力。本文基于 configuring-a-project.md 官方文档系统讲解 SpacetimeAuth 项目的核心配置项客户端Clients管理、作用域Scopes与声明Claims、重定向 URIRedirect 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 的应用程序。每个客户端都关联到唯一的项目并拥有自己独立的配置项包括重定向 URIRedirect URIs允许 SpacetimeAuth 在登录成功后把用户重定向回的位置登出后重定向 URIPost Logout Redirect URIs允许 SpacetimeAuth 在登出后把用户重定向回的位置名称Name客户端名称例如 My Web App。在项目 Dashboard 中切换到 Clients 标签页即可管理客户端。每个项目自带一个默认客户端可直接用于快速上手点击 Create Client 按钮可以创建更多客户端。需要几个客户端大多数项目只需要一个客户端即可完成用户对 SpacetimeDB 模块的认证。但是如果你有多个应用程序例如一个主应用加一个 sidecar、管理后台等并希望为每个应用使用不同的认证流程或不同的设置则可以创建多个客户端。典型的拆分场景包括Web 应用与移动应用共用同一个 SpacetimeDB 数据库但希望各自拥有独立的重定向 URI 配置主应用与管理后台希望采用不同的安全策略如是否启用client_credentials流程开发环境、预发布环境、生产环境使用独立的客户端配置。创建或编辑客户端时的配置项配置项说明Name客户端名称例如 My Web App。Redirect URIsSpacetimeAuth 允许在登录成功后重定向用户到这些 URI。它们必须与应用中实际使用的 URI 完全匹配。Post Logout Redirect URIsSpacetimeAuth 允许在登出后重定向用户到这些 URI。它们同样必须与应用中实际使用的 URI 完全匹配。:::danger务必妥善保管客户端密钥client secret绝不能将其暴露在客户端代码或公开仓库中。客户端 ID 不是敏感信息可以放心公开分享。客户端密钥仅在client_credentials流程中使用该流程允许在没有用户上下文的情况下获取令牌此时令牌中的sub声明会被设置为客户端 ID。 :::服务端视角客户端令牌如何被解析从源码结构可以进一步理解client_credentials流程与身份令牌在服务端是如何被处理的。SpacetimeDB 服务端通过 crates/auth/src/identity.rs 中定义的IncomingClaims结构解析 JWT 载荷其中subsubject、ississuer、audaudience、iat、exp是核心声明字段其余所有自定义声明例如角色通过#[serde(flatten)]落入extra字段。解析时服务端会基于issuer与subject计算出一个确定的Identity见Identity::from_claims并校验令牌中携带的hex_identity与该计算结果一致从而保证每个认证主体在 SpacetimeDB 中拥有稳定的身份。这也意味着client_credentials流程中sub被设为客户端 ID 时服务端会据此派生出一个与客户端对应的确定性身份供无用户上下文的机器对机器M2M场景使用。作用域与声明Scopes and Claims当前支持的作用域作用域Scope目前尚不可编辑仅限以下三种且基本能满足绝大多数应用的认证信息需求openidprofileemail在应用发起认证流程时可以请求全部作用域也可以请求其中一部分。各作用域提供的声明声明Claims即 ID Token 中携带的用户信息。各作用域对应的声明如下表作用域声明openid必需sub唯一用户标识符profilename、family_name、given_name、middle_name、nickname、preferred_username、picture、website、gender、birthdate、zoneinfo、locale、updated_atemailemail、email_verifiedopenid是 OpenID Connect 协议强制要求的作用域无论请求与否ID Token 中都会包含sub声明。源码层面的声明结构印证SpacetimeDB 服务端对 JWT 声明的建模位于 crates/auth/src/identity.rs 的SpacetimeIdentityClaims结构体它显式定义了identity映射为 JWT 的hex_identity、subjectsub、issueriss、audienceaud、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。重定向 URIRedirect URIs为什么它如此关键重定向 URI 是 OAuth2 与 OpenID Connect 流程中的关键安全机制。它保证用户完成认证后只会被重定向回你应用中的可信位置而不是任意第三方地址。配置匹配规则配置重定向 URI 时必须确保它与应用中实际使用的 URI完全一致包括以下每个组成部分协议schemehttp或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 支持多个第三方身份提供商允许用户使用已有的第三方账号完成认证。目前支持的提供商包括GoogleGitHubDiscordTwitchKick未来还会陆续添加更多提供商。声明的标准化映射来自第三方身份提供商的用户信息会被映射为 SpacetimeAuth 使用的标准 OpenID Connect 声明从而保证无论用户使用哪个提供商登录应用侧获得的用户体验都是一致的。例如提供商的用户名声明会被映射为标准preferred_username声明。配置步骤在项目 Dashboard 中切换到 Identity Providers 标签页由于 SpacetimeAuth 在此处扮演的是外部身份提供商的客户端你需要提供从该提供商开发者控制台申请的client ID 和 client secret在提供商的开发者控制台中将回调地址配置为指向 SpacetimeAuth具体地址见下表选择启用enable或禁用disable该提供商点击 Save 保存。此后该提供商便会出现在应用的登录页上。各提供商的回调 URI启用每个提供商时需要在对应提供商的开发者控制台中配置如下回调 URI提供商回调 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/kick各提供商 OAuth 应用创建指引为帮助你在各提供商的控制台中创建所需的 OAuth 应用有时称为 OAuth App 或 OAuth Client官方文档给出了对应指引要点如下Google在 Google Cloud 开发者控制台Google API Console中获取 Google API 客户端 ID创建 OAuth 2.0 客户端后按上表配置授权回调 URIGitHub在 GitHub 的 OAuth Apps 设置中创建 OAuth App填写回调 URL 并生成 Client secretDiscord在 Discord 开发者门户中创建一个 Application作为 OAuth2 客户端并配置重定向地址Twitch在 Twitch 开发者后台注册应用Register App获取 Client ID 与 Client Secret 并配置 OAuth 回调Kick在 Kick 的开发者文档指引下完成 Kick Apps 设置。创建完成后将获取到的 client ID 与 client secret 填入 SpacetimeAuth Dashboard 的 Identity Providers 标签页并保存即可。配置完成后的验证与下一步推荐先做一次端到端验证在编写任何集成代码之前官方强烈建议先验证你的配置是否正确。最简单的方式是使用OIDC Debugger这类在线工具它可以在浏览器中模拟 OAuth2/OIDC 授权码流程帮助你确认重定向 URI 配置正确验证客户端 ID 可用检查 ID Token 及其声明email、sub、preferred_username等在写代码之前发现配置问题。关键端点信息如下配置验证时使用授权端点https://auth.spacetimedb.com/oidc/auth令牌端点https://auth.spacetimedb.com/oidc/token客户端 ID取用 SpacetimeAuth Dashboard 中任意可用客户端重定向 URI需要将验证工具的回调地址加入客户端允许的重定向 URI 列表请求时建议勾选 PKCE并请求openid profile email或其子集作用域无需填写客户端密钥因为该工具运行在浏览器端。完整的验证步骤、字段取值与 ID Token 示例可参考 SpacetimeAuth 测试指南。开始集成配置并验证通过后即可将 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），仅供参考 SpacetimeDB SpacetimeAuth 项目配置完全指南：Clients、Scopes 与第三方身份提供商
SpacetimeDB SpacetimeAuth 项目配置完全指南Clients、Scopes 与第三方身份提供商【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDBSpacetimeAuth 是 SpacetimeDB 提供的一项内置认证服务无需外部认证服务或额外托管服务器即可为部署在 Maincloud 上的模块提供 OpenID ConnectOIDC认证能力。本文基于 configuring-a-project.md 官方文档系统讲解 SpacetimeAuth 项目的核心配置项客户端Clients管理、作用域Scopes与声明Claims、重定向 URIRedirect 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 的应用程序。每个客户端都关联到唯一的项目并拥有自己独立的配置项包括重定向 URIRedirect URIs允许 SpacetimeAuth 在登录成功后把用户重定向回的位置登出后重定向 URIPost Logout Redirect URIs允许 SpacetimeAuth 在登出后把用户重定向回的位置名称Name客户端名称例如 My Web App。在项目 Dashboard 中切换到 Clients 标签页即可管理客户端。每个项目自带一个默认客户端可直接用于快速上手点击 Create Client 按钮可以创建更多客户端。需要几个客户端大多数项目只需要一个客户端即可完成用户对 SpacetimeDB 模块的认证。但是如果你有多个应用程序例如一个主应用加一个 sidecar、管理后台等并希望为每个应用使用不同的认证流程或不同的设置则可以创建多个客户端。典型的拆分场景包括Web 应用与移动应用共用同一个 SpacetimeDB 数据库但希望各自拥有独立的重定向 URI 配置主应用与管理后台希望采用不同的安全策略如是否启用client_credentials流程开发环境、预发布环境、生产环境使用独立的客户端配置。创建或编辑客户端时的配置项配置项说明Name客户端名称例如 My Web App。Redirect URIsSpacetimeAuth 允许在登录成功后重定向用户到这些 URI。它们必须与应用中实际使用的 URI 完全匹配。Post Logout Redirect URIsSpacetimeAuth 允许在登出后重定向用户到这些 URI。它们同样必须与应用中实际使用的 URI 完全匹配。:::danger务必妥善保管客户端密钥client secret绝不能将其暴露在客户端代码或公开仓库中。客户端 ID 不是敏感信息可以放心公开分享。客户端密钥仅在client_credentials流程中使用该流程允许在没有用户上下文的情况下获取令牌此时令牌中的sub声明会被设置为客户端 ID。 :::服务端视角客户端令牌如何被解析从源码结构可以进一步理解client_credentials流程与身份令牌在服务端是如何被处理的。SpacetimeDB 服务端通过 crates/auth/src/identity.rs 中定义的IncomingClaims结构解析 JWT 载荷其中subsubject、ississuer、audaudience、iat、exp是核心声明字段其余所有自定义声明例如角色通过#[serde(flatten)]落入extra字段。解析时服务端会基于issuer与subject计算出一个确定的Identity见Identity::from_claims并校验令牌中携带的hex_identity与该计算结果一致从而保证每个认证主体在 SpacetimeDB 中拥有稳定的身份。这也意味着client_credentials流程中sub被设为客户端 ID 时服务端会据此派生出一个与客户端对应的确定性身份供无用户上下文的机器对机器M2M场景使用。作用域与声明Scopes and Claims当前支持的作用域作用域Scope目前尚不可编辑仅限以下三种且基本能满足绝大多数应用的认证信息需求openidprofileemail在应用发起认证流程时可以请求全部作用域也可以请求其中一部分。各作用域提供的声明声明Claims即 ID Token 中携带的用户信息。各作用域对应的声明如下表作用域声明openid必需sub唯一用户标识符profilename、family_name、given_name、middle_name、nickname、preferred_username、picture、website、gender、birthdate、zoneinfo、locale、updated_atemailemail、email_verifiedopenid是 OpenID Connect 协议强制要求的作用域无论请求与否ID Token 中都会包含sub声明。源码层面的声明结构印证SpacetimeDB 服务端对 JWT 声明的建模位于 crates/auth/src/identity.rs 的SpacetimeIdentityClaims结构体它显式定义了identity映射为 JWT 的hex_identity、subjectsub、issueriss、audienceaud、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。重定向 URIRedirect URIs为什么它如此关键重定向 URI 是 OAuth2 与 OpenID Connect 流程中的关键安全机制。它保证用户完成认证后只会被重定向回你应用中的可信位置而不是任意第三方地址。配置匹配规则配置重定向 URI 时必须确保它与应用中实际使用的 URI完全一致包括以下每个组成部分协议schemehttp或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 支持多个第三方身份提供商允许用户使用已有的第三方账号完成认证。目前支持的提供商包括GoogleGitHubDiscordTwitchKick未来还会陆续添加更多提供商。声明的标准化映射来自第三方身份提供商的用户信息会被映射为 SpacetimeAuth 使用的标准 OpenID Connect 声明从而保证无论用户使用哪个提供商登录应用侧获得的用户体验都是一致的。例如提供商的用户名声明会被映射为标准preferred_username声明。配置步骤在项目 Dashboard 中切换到 Identity Providers 标签页由于 SpacetimeAuth 在此处扮演的是外部身份提供商的客户端你需要提供从该提供商开发者控制台申请的client ID 和 client secret在提供商的开发者控制台中将回调地址配置为指向 SpacetimeAuth具体地址见下表选择启用enable或禁用disable该提供商点击 Save 保存。此后该提供商便会出现在应用的登录页上。各提供商的回调 URI启用每个提供商时需要在对应提供商的开发者控制台中配置如下回调 URI提供商回调 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/kick各提供商 OAuth 应用创建指引为帮助你在各提供商的控制台中创建所需的 OAuth 应用有时称为 OAuth App 或 OAuth Client官方文档给出了对应指引要点如下Google在 Google Cloud 开发者控制台Google API Console中获取 Google API 客户端 ID创建 OAuth 2.0 客户端后按上表配置授权回调 URIGitHub在 GitHub 的 OAuth Apps 设置中创建 OAuth App填写回调 URL 并生成 Client secretDiscord在 Discord 开发者门户中创建一个 Application作为 OAuth2 客户端并配置重定向地址Twitch在 Twitch 开发者后台注册应用Register App获取 Client ID 与 Client Secret 并配置 OAuth 回调Kick在 Kick 的开发者文档指引下完成 Kick Apps 设置。创建完成后将获取到的 client ID 与 client secret 填入 SpacetimeAuth Dashboard 的 Identity Providers 标签页并保存即可。配置完成后的验证与下一步推荐先做一次端到端验证在编写任何集成代码之前官方强烈建议先验证你的配置是否正确。最简单的方式是使用OIDC Debugger这类在线工具它可以在浏览器中模拟 OAuth2/OIDC 授权码流程帮助你确认重定向 URI 配置正确验证客户端 ID 可用检查 ID Token 及其声明email、sub、preferred_username等在写代码之前发现配置问题。关键端点信息如下配置验证时使用授权端点https://auth.spacetimedb.com/oidc/auth令牌端点https://auth.spacetimedb.com/oidc/token客户端 ID取用 SpacetimeAuth Dashboard 中任意可用客户端重定向 URI需要将验证工具的回调地址加入客户端允许的重定向 URI 列表请求时建议勾选 PKCE并请求openid profile email或其子集作用域无需填写客户端密钥因为该工具运行在浏览器端。完整的验证步骤、字段取值与 ID Token 示例可参考 SpacetimeAuth 测试指南。开始集成配置并验证通过后即可将 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），仅供参考