Game Hub 上的社交身份验证

Aghanim 支持多个社交登录提供方（例如 Apple、Discord、Facebook、Google）以及通用的符合 OIDC 的提供方，用于通过 webhooks 进行玩家身份验证。这些 webhook 会将登录事件通知你的后端，需要验证 OAuth2 授权码以授予或拒绝对 game hub 的访问。

要求

要使用社交登录处理来自 Aghanim 的玩家验证事件，您的服务器必须：

公开一个HTTPS POST端点。
接受由Aghanim签名的webhook事件。
用适当的提供者通过 OAuth2 授权码授权流 使用 response_type=code 换取访问令牌的授权码。
验证并将生成的用户资料与您的玩家数据库匹配。
用 200 状态码和 JSON 载荷响应成功或失败。

支持的提供者

您必须在游戏应用程序控制面板中配置每个社交提供商，并确保OAuth2流程的重定向URI处理正确。当前支持以下提供者：

Apple
Discord
Google
Facebook
OIDC（任何符合 OpenID Connect 的提供方）

信息

对于未在上方列出的提供方，你可以使用通用的 OIDC Login 插件来集成任何符合 OpenID Connect 的身份提供方（例如 Keycloak、Auth0、Okta、Azure AD）。如果你需要进一步协助，请联系我们。

OAuth2 重定向 URI

对于每个提供商，请确保在相应的开发者控制台中添加以下重定向URI：

https://<GAME_HUB_DOMAIN>/oauth2/<PROVIDER>/callback

将 <GAME_HUB_DOMAIN> 替换为你的 Game Hub 域名（例如 demo.aghanim.com），并将 <PROVIDER> 替换为 facebook、google、apple、discord 或 oidc。

提供商特定配置

信息

虽然一般的 OAuth2 流程在所有提供商中一致，但设置步骤因平台而略有不同。详细的设置说明可以在每个提供商的开发者文档中找到。

Apple

前往 Apple 开发者门户
在 Identifiers 下注册新的 Sign In with Apple 服务
配置您的 服务 ID 和 重定向 URI
生成用于 OAuth2 代币交换的 client secret JWT

Discord

访问 Discord 开发者门户
创建应用程序并启用 OAuth2
设置您的重定向URI

Facebook

访问 Facebook 开发者
创建一个新应用程序（类型：Consumer）
添加 Facebook 登录 产品
在 Facebook 登录 → 设置 下配置：
- 客户端 OAuth 登录：是
- 对重定向 URI 使用严格模式：是
在 有效的 OAuth 重定向 URI 中设置您的 重定向 URI

Google

前往 Google 云控制台
在 APIs & Services → 凭证 下创建 OAuth2 凭证
配置重定向URI

OIDC

在你的符合 OIDC 的身份提供方（例如 Keycloak、Auth0、Okta、Azure AD）中配置客户端应用程序
记录 Discovery URL、Authorization Endpoint 和 Client ID
设置你的 Redirect URI
有关详细的设置说明，请参阅 OIDC Login 指南

配置步骤

通过以下方式注册您的端点：

Aghanim仪表板→ 游戏 > Webhooks > 新建 Webhook，选择玩家验证事件类型。
或通过创建 Webhook API

Request schema

下面是一个 player.verify Webhook 请求示例：

HTTP
cURL

POST /your/webhook/uri HTTP/1.1
Content-Type: application/json
Host: your-webhook-endpoint.com
User-Agent: Aghanim/0.1.0
X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812
X-Aghanim-Signature-Timestamp: 1725548450

{
  "event_type": "player.verify",
  "event_data": {
    "method": "google",
    "code": "4/0123abc...xyz"
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": null,
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "hub.login",
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}
            

curl "https://your-webhook-endpoint.com/your/webhook/uri" \
    -X POST \
    -H "Content-Type: application/json" \
    -H "User-Agent: Aghanim/0.1.0" \
    -H "X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812" \
    -H "X-Aghanim-Signature-Timestamp: 1725548450" \
    -d '{
      "event_type": "player.verify",
      "event_data": {
        "method": "google",
        "code": "4/0123abc...xyz"
      },
      "event_time": 1725548450,
      "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
      "idempotency_key": null,
      "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
      "sandbox": false,
      "trigger": "hub.login",
      "transaction_id": "whtx_eCacGbJVbvT",
      "context": null,
      "game_id": "gm_exTAyxPsVwh"
    }'
            

事件 Schema

键名	类型	描述
`event_id`	`string`	阿哈利姆生成的唯一事件标识符。
`game_id`	`string`	您的游戏在阿哈利姆中的唯一标识符。
`event_type`	`string`	事件的类型， `player.verify` 在此情境下。
`event_time`	`number`	以 Unix 时间戳表示的事件发生日期。
`event_data`	`EventData`	包含事件特定数据的字段，其中可能包含用于继承对象的各种键值。
`idempotency_key`	`string\|null`	即使出现重试情况，也能确保 Webhook 操作只执行一次。可以是 `null` 具体取决于事件类型。
`request_id`	`string\|null`	如果事件是通过 API 请求触发的，此字段将包含对应的请求 ID。
`sandbox`	`boolean`	标识事件是否来自沙盒测试环境的指示器。
`trigger`	`string\|null`	The trigger that caused the event to be sent.
`transaction_id`	`string`	阿哈利姆生成的交易标识符。在同一交易过程中触发的多个事件可能共享相同的交易 ID。
`context`	`object\|null`	事件的相关上下文信息。

EventData Schema

键名	类型	描述
`method`	`string`	用于认证的提供商。 `apple`、`discord`、`facebook`、`google` 或 `oidc` 之一。
`code`	`string`	由提供商生成的授权码。有关详细信息，请参见 RFC 6749 第 4.1.2 节。
`redirect_uri`	`string\	null`

处理 Webhook

您的后端应：

从请求正文中提取 method、code 和 redirect_uri。
使用相应的提供者的 OAuth2 令牌端点，用 code 换取访问令牌。如果 redirect_uri 不是 null，请将其包含在令牌交换请求中。
使用访问令牌获取用户资料。
将社交帐户与数据库中的玩家匹配。
使用适当的 Webhook 响应模式接收或拒绝登录。

成功响应架构

请参考 player.verify webhook 响应文档以了解预期结构。

失败响应架构

如果验证失败，返回 200 状态码和以下 JSON 响应：

{
 "status": "error",
 "code": "not_found",
 "message": "系统中不存在该玩家记录"
}

可能出现的错误代码列表：

not_found：系统中不存在该账户或玩家记录。
invalid_signature：请求的安全签名验证失败。
validation_error：请求中包含的数据格式或内容不符合要求。
banned：该账户或玩家已被系统封禁。

常见问题解答

否. Aghanim 永远不需要访问你的 OAuth 客户端密钥或 API 密钥。当玩家通过 Game Hub 上的社交提供商登录时，Aghanim 会从提供商接收授权 code，并通过 player.verify webhook 将其转发到你的后端。然后你的服务器会使用你自己的凭据将该 code 交换为访问令牌——与你的游戏已在使用的凭据相同。

否. 你应该使用与你的游戏已在使用的同一个 OAuth 应用。唯一需要的更改是将 Aghanim Redirect URI 添加到提供商开发者控制台中你现有应用的允许重定向 URI 列表里。

Meta (Facebook) 和 Apple 等提供商会发放限定于特定 OAuth 应用范围的玩家 ID。由于 Aghanim 使用 你现有的 OAuth 应用（而不是单独的应用），因此在令牌交换期间返回的玩家 ID 将与你的游戏已知的 ID 相同。不会出现 ID 不匹配。

需要技术支持？
联系我们的集成技术团队： [email protected]

要求