连接接口

连接接口处理不同身份提供方之下用户账号之间的连接。

连接接口

连接接口(Connect Interface) 允许外部身份提供者接入并使用 Epic在线服务 (EOS)生态系统。

连接接口(Connect Interface)

  • 允许访问 Epic在线服务(EOS) 的游戏服务。

  • 允许在跨平台服务中生成通用的唯一用户标识符。 将外部身份提供者

  • 允许将外部身份提供者的账户与我们的服务关联。

玩家可以将一个或多个外部用户的账户与他们的 产品用户ID (Product User ID,一种唯一的玩家ID)相关联。

产品用户ID可用于同一个组织中的所有产品。

关于受支持的部身份提供者及配置信息,请查阅部身份提供者

管理用户

用户需要凭借外部凭证来登录。若此产品中已有用户,则会为此用户提供一个持续一定时间(当前为一小时)的 访问令牌。在令牌过期之前,游戏将得到通知;届时需要刷新现有令牌,给出一个有效的外部凭证。

Epic在线服务接口无法控制外部提供方的访问授权。因此,连接接口

可以:

  • 验证外部账号提供方的用户是否仍有效

  • 延长用户能够访问我方服务的时间。

无法:

  • 隐式刷新令牌

  • 提供长期访问

外部账号提供方应具备对于应用程序的授权访问权限。

连接接口 - 账户流程

假如需要访问此用户ID可用的服务,需要通过 EOS_ProductUserId 数据接口进行外部账号验证。所有接口都会明确说明此用法,并应该确保类型的安全性。该数据结构独立于 EOS_EpicAccountId,后者与为Epic账户服务提供的验证接口有关。

当连接接口可用于所有受支持的外部账户类型时,不需要Epic Games账户。

登录

如需登录,请用 EOS_Connect_LoginOptions (其包含来自支持平台的外部凭证)调用 EOS_Connect_Login

在处理Epic Games账号时,从 EOS_Auth_CopyUserAuthToken 获取当前验证令牌并将 EOS_EExternalCredentialType 设为 EOS_ECT_EPIC 即可。

EOS_HConnect 句柄、EOS_Connect_LoginOptions 结构和回调信息传至 EOS_Connect_Login。假设 EOS_HPlatform 句柄正在更新,操作完成时将执行你提供的回调。

如结果成功,应用程序可能继续访问需要验证的的额外接口。如用户不存在,登录API将返回一个 EOS_InvalidUser 结果。此外将包含一个 EOS_ContinuanceToken。此令牌提供登录尝试的细节,在登录流畅的以下步骤中需要用到。

此时需要进行选择。询问用户是否已有在服务上注册的第二套外部凭证(请参见绑定外部账户),还是希望新建用户(参见创建用户)。

用户验证刷新通知

当现有访问令牌即将过期时,将运行提供给 EOS_Connect_AddNotifyAuthExpiration 的一个回调函数。这让应用程序每次都有足够时间来获取另一个外部访问令牌,并通过 EOS_Connect_Login 函数来将其提供给SDK。

使用 EOS_Connect_RemoveNotifyAuthExpiration 函数来停止监听这些通知。

用户验证状态变更通知

为确保应用程序能够获悉用户身份验证状态发生改变,连接接口将提供此类通知的回调。

本地用户的授权状态发生变化时,将运行你提供给 EOS_Connect_AddNotifyUserLoginStatusChanged 的回调函数。这种情况应只在以下条件下发生:如过期通知被忽略,外部提供方凭证无法刷新访问令牌;或出于某种权限原因,访问被后端服务显式撤销。只有当EOS生态系统中的其他回调检测到此验证令牌无效后,才会触发此回调函数;否则不会自动触发。

你必须处理可能因为验证而失败的调用中的所有错误信息。通常可以进行恢复,办法是调用 EOS_Connect_Login 然后在成功时重新尝试原始调用。

使用 EOS_Connect_RemoveNotifyUserLoginStatusChanged 函数来停止监听通知。

检查当前用户验证状态

使用 EOS_Connect_GetLoginStatus 函数即可根据需求检查玩家的当前状态。此函数基于与在线服务的最近通信来确定验证状态,因此将即刻返回结果,不使用回调函数。

创建新用户

创建用户时,将为登录时使用给定外部凭证的用户生成一个新的 产品用户ID。在新建用户之前,有必要向用户弹出提示,确定是否存在其他登录方法。这能减少跨平台操作时的困惑和用户进程合并问题。

如果应用程序要为用户创建新产品用户ID,调用 EOS_Connect_CreateUser 即可。EOS_Connect_CreateUserOptions 包含从上个调用到 EOS_Connect_LoginEOS_ContinuanceToken

EOS_HConnect 柄、EOS_Connect_CreateUserOptions 结构和回调信息传至函数。假设 EOS_HPlatform 柄正在tick,操作完成时将执行你提供的回调。

绑定外部账号

如果应用程序登录流程决定用户可以用第二套外部凭证登录,则保存来自首个登录调用的 EOS_ContinuanceToken、重新尝试通过 EOS_Connect_Login 登录,并在成功登录后立即调用 EOS_Connect_LinkAccount。这样便能把两个外部账号关联到一个产品用户ID。我们的服务得到拓展之后,还可以绑定两个以上的账户。

如应用程序的目的是用现有产品用户ID绑定一个新外部账号,则调用 EOS_Connect_LinkAccountEOS_Connect_LinkAccountOptions 包含从上个调用到 EOS_Connect_LoginEOS_ContinuanceToken;已登录用户的产品用户ID成功对 EOS_Connect_Login 进行调用。

EOS_HConnect 柄、EOS_Connect_LinkAccountOptions 结构和回调信息传至函数。假设 EOS_HPlatform 柄正在tick,操作完成时将执行你提供的回调。

搜索EOS连接用户的方法是根据其外部账号ID;或使用产品用户ID,通过开发者门户中的"账户绑定(Account Linking)"面板进行。用户绑定外部账号的钥匙串在组织层面上进行管理,因此"账户绑定(Account Linking)"面板处于组织管理菜单项的旁边。通过账号绑定面板可以找到玩家,客户支持也能够借此进行玩家请求的账户解绑。还可以使用此面板在SDK整合测试中移除EOS连接用户或任何绑定账户。我们还随此提供了网络REST API,以便开发者将EOS用户管理整合到现有的内部面板中。

取消绑定外部账号

在首次用户登录流程期间,用户可能最终处于这样一种状态,即他们无意中为登录的账号(通常是本地平台账号)创建了新的产品用户ID,而非使用已有的游戏进度;这些进度可能是因为他们在其他平台上玩了游戏,或使用了其他的外部账号凭证。用户可能不知道游戏的跨平台联机对战功能(crossplay)。

在这类情况下,用户会跳过所有的前期登录对话框,继续使用他们默认的平台账号凭证(已登录账号),通过 EOS_Connect_LoginEOS_Connect_CreateUser 接口创建新的 EOS_ProductUserId。因此,他们在游戏开始时与 EOS_Connect_Login 一起使用的登录账号现在意外绑定了一个产品用户ID。假如要从这种状态恢复,用户需要将登录账号与新创建的钥匙串解除关联,以便再次进入首次用户登录流程。

一旦他们解除了登录账号的链接,他们就可以使用另一组外部账号凭证(其与现有的其他钥匙串关联)进行登录。如果成功,他们就能按照上文 绑定外部账号 一节的描述,将默认登录账号与所需的现有钥匙串进行绑定。

在另一种情况下,用户可能只是想将登录账号与其当前钥匙串解除绑定,以便在平台之间分离游戏进度,或以其他方式将其与另一钥匙串绑定。

若要将当前已登录的产品用户ID的钥匙串与外部账号与解绑,请使用 EOS_Connect_UnlinkAccountOptions 调用 EOS_Connect_UnlinkAccount,指定 LocalUserId 为上次调用 EOS_Connect_Login 后返回的 EOS_ProductUserId。操作成功后,外部账号将停止与所有钥匙串绑定。这意味着下次尝试使用 EOS_Connect_Login 并使用同一外部账号关联的凭证登录时,会返回 EOS_InvalidUser 结果并附带 EOS_ContinuanceToken

与账号绑定的创建操作类似,你可以在开发者门户中通过账号仪表板来审查解除绑定的历史操作记录。

外部账号解除绑定限制

为了防止账号被盗,只有本地用户当前登录时使用的账号才能与钥匙串解绑。这可以防止恶意行为者访问其中某个绑定账号,并用它删除与钥匙串绑定的所有其他账号。它还可以防止恶意行为者将未绑定的账号替换为他们自己在同一平台上的账号,因为取消绑定操作能确保这样一个事实,即现有验证会话在未与钥匙串中其他已绑定账号进行验证的情况下,无法用于重新绑定和覆盖条目。

这类限制旨在限制与账号盗窃情景相关的潜在攻击层面。

使用设备ID

该功能仅适用于个人移动设备和桌面电脑。 设备ID无法与反作弊接口一起使用,因为反作弊接口需要有一个外部账户。

应用程序认为不足以为用户创建新账户或绑定现有账户时,应用程序可能会使用EOS链接设备ID功能来创建一个新的持久伪账户。此功能让应用程序能够为本地用户创建一个持久访问凭证,而无需使用外部登录凭证。这样后端设备便能在本地设备的多个游戏会话中记住当前用户。设备ID功能在个人移动设备上尤为实用,可以不弹出账户凭证提示而自动登录用户,无需立即要求玩家登录维持游戏进度数据便能开始游戏。

然而,设备ID未绑定到真实用户账户且只能用于独立识别本地设备。因此强烈建议在早期进行到一定时间段后,便要求用户绑定一种外部验证其设备ID账户的方法,以防止凭证和账号的丢失。

如果最终并未以真实用户身份绑定设备ID账号,设备本身一旦出现意外,所有游戏进度和数据便会永久丢失。EOS SDK将把设备ID凭证本地保存在本地设备当前登录用户的钥匙串中。如本地用户档案被重设或丢失,之后则无法恢复设备ID。

要创建新设备ID,应用程序必须用一个包含用户设备型号(DeviceModel)的有效EOS_Connect_CreateDeviceIdOptions结构来调用 EOS_Connect_CreateDeviceId 函数。此调用最终将对绑定到 EOS_Connect_OnCreateDeviceIdCallback 的函数触发一个回调。如新的设备ID已成功创建并被保存在本地设备登录用户的钥匙串中,那么回调参数的ResultCode参数将被设为 EOS_EResult::EOS_Success 。如已存在现有设备ID,则返回 EOS_EResult::EOS_DuplicateNotAllowed 。否则ResultCode参数将识别操作失败的原因。

要用专属设备ID登录本地用户,需要以 EOS_EExternalCredentialType::EOS_ECT_DEVICEID_ACCESS_TOKEN 外部凭证类型调用 EOS_Connect_Login API。因为SDK自动管理保存的设备ID凭证,输出 EOS_Connect_Credentials 结构体的 Token 参数必须被设为空(null)。然而,因为设备ID未绑定真实用户身份,EOS_Connect_UserLoginInfo 输入结构体需要带有用户的有效 DisplayName

要将本地设备ID绑定到真实外部用户账户,首先让游戏使用设备ID凭证类型正常登录本地用户。然后要求用户使用真实身份登录,在 EOS_Connect_Login 返回一个 EOS_ContinuanceToken 之后,使用 EOS_Connect_Link API绑定外部账号,将本地设备与用户的真实账号关联起来。之后每次游戏开始时便会自动登入用户,因为设备ID仍能用于自动登录用户,无需弹出外部用户账户凭证输入的提示。

删除设备ID凭证

你也可以调用 EOS_Connect_DeleteDeviceId API来删除本地设备当前用户档案的设备ID。删除为永久性操作,不可恢复。然而,用户始终可以新建一个设备ID,并将其与现有外部用户账户绑定,以恢复自动登录功能。

在安卓和iOS设备上,卸载应用会自动删除所有由应用创建的本地设备ID凭证。

在桌面平台上(Linux、macOS、Windows),设备ID凭证不会自动删除。应用在重新安装时,可以为本地OS用户复用已有的设备ID凭证,或者在首次运行时调用 EOS_Connect_DeleteDeviceId API,确保用户拥有全新的初始体验。

将基于设备ID的游戏进度与现有关联账号钥匙串相关联

有一种极端情况,在这种情况中,你无法通过常规渠道将设备ID伪账号与真实的外部用户账号关联。在这种情况中,已登录的真实用户账号已经属于同一EOS组织下的已有钥匙串。在这种情况中,当游戏首先自动使用本地设备ID登录类型登录用户,并且用户使用真实的外部用户账号凭证登录时,EOS_Connect_Login 接口将返回已有的 EOS_ProductUserId,而非 EOS_ContinuanceToken。为了处理这种特殊情况,需要使用 EOS_Connect_TransferDeviceIdAccount 接口。

设备ID伪账号无法关联现有钥匙串,因为 EOS_Connect_Link 接口要求使用 EOS_ContinuanceToken。另外,由于玩家现在面临两个单独的 EOS_ProductUserIds,游戏需要让玩家选择是否将其中一个作为过时的 EOS_ProductUserIds (即游戏档案)丢弃,继而使用另一个。如果玩家选择丢弃其中一个档案,游戏可以将本地设备ID账号关联到后端持续存在的已关联账号的现有钥匙串中。

为了处理出现两个 EOS_ProductUserIds 的情况,游戏需要能够识别:何时使用设备ID登录类型让本地用户登录,然后用户在同一游戏会话中使用外部账号登录 并且 收到另一个 EOS_ProductUserId 会话。当出现这种情况时,游戏应该尝试自动检测是否其中有一个 EOS_ProductUserIds 在后台没有任何有意义的游戏进度。这种情况下,游戏应自动丢弃它,并将本地设备ID伪账号与真实的外部用户账号的现有钥匙串关联起来。

假如游戏无法确定是否可以代表用户自动处理这一特殊情况,它应该提示用户,让用户选择该如何继续。在这类选择对话框中,玩家应该能够查看游戏进度,以比较形式查看每个 EOS_ProductUserId,并选择保留哪一个。应该清楚地告知用户,游戏进度丢弃后将永远丢失,之后将无法恢复。游戏还应该允许用户不丢弃任意一个档案,而是在当前游戏会话中选择继续玩某个档案。

如果用户选择丢弃其中一个游戏档案,永久切换到另一个,游戏应该调用 EOS_Connect_TransferDeviceIdAccount 接口,将本地设备ID伪账号传入与真实外部用户账号关联的密钥串中。在接口中,输入结构体 EOS_Connect_TransferDeviceIdAccountOptions,并将 ProductUserIdToPreserve 参数设置为指向正确的 EOS_ProductUserId,以便在设备ID转移操作中保留。

获取外部账号映射

其他接口将接收远程或其他外部用户的 EOS_ProductUserId(例如同一服务器上好友或玩家的列表)。可以通过映射API将外部用户账户辨识符转换为 EOS_ProductUserId

EOS_Connect_QueryExternalAccountMappings 是一个异步调用,将把外部账户ID转换为SDK代表。设置 EOS_EExternalAccountType,并以字符串形式提供外部账号ID的一个连续列表即可。

EOS_HConnect 柄、EOS_Connect_QueryExternalAccountMappingsOptions 结构和回调信息传至函数。假设EOS_HPlatform柄正在tick,操作完成时将执行你提供的回调。

回调成功返回后,即可通 过 EOS_Connect_GetExternalAccountMapping 获取映射。和之前一样,此函数接受 EOS_EExternalAccountType 并为每次调用返回一个单一 EOS_ProductUserId(此调用以字符串形式提供一个外部账号ID)。

一种常见用例是查询其他用户(该用户通过相同的账户系统与本地用户相连接)。基于其他账户系统的外部账户ID的查询可能无法实现,具体取决于账户系统的具体情况。

获取产品用户ID映射

可以获取给定产品用户ID的外部映射,同时也能反向操作。

EOS_Connect_QueryProductUserIdMappings 是一个异步调用,将把 EOS_ProductUserIds 转换为给定平台上的外部同类,以及包含显示名称和上次登录时间的额外账号数据。将提供产品用户ID的连续列表。

EOS_HConnect 柄、EOS_Connect_QueryProductUserIdMappingsOptions 结构和回调信息传至函数。假设 EOS_HPlatform 柄正在tick,操作完成时将执行你提供的回调。

回调成功返回后,即可通 过 EOS_Connect_GetProductUserIdMapping 获取映射。

此函数接受 EOS_EExternalAccountType、一个输入缓冲,以及缓冲长度来填充外部账号ID。如缓冲过小,则会返回缓冲的正常大小。

使用 EOS_Connect_GetProductUserExternalAccountCount 来获取产品使用者绑定的外部账号数量。

使用 EOS_Connect_CopyProductUserExternalAccountByIndex 来获取通过索引绑定到产品用户的外部账号的相关信息。

使用 EOS_Connect_CopyProductUserExternalAccountByAccountType 来获取绑定到产品用户的特定类型外部账号的相关信息。

使用 EOS_Connect_CopyProductUserExternalAccountByAccountId 来获取通过账号ID绑定到产品用户的外部账号的相关信息。

使用 EOS_Connect_CopyProductUserInfo 来获取产品用户的相关信息,以其最近登录所使用的外部账号来当作参考。

如产品用户ID未映射到给定的外部平台,则数据不会出现在为上述操作返回的结果中。这意味着用户从未将此外部账号类型绑定到其产品用户ID。

使用ID令牌进行用户验证

ID令牌是OpenID Connect协议的一部分,可用于在服务器端验证用户的身份。ID令牌是一种JSON格式的网络令牌(JWT),它包含验证用户相关的信息,如产品用户ID。这允许后端服务和游戏服务器安全地验证从客户端收到的用户标识符。

ID令牌无法用来代表用户执行行动。它们只用于用户身份验证。

为用户获取ID令牌

在用户通过EOS连接的验证后,游戏客户端可以通过调用 EOS_Connect_CopyIdToken SDK API来获取本地用户的ID令牌(传入一个包含用户 EOS_ProductUserIdEOS_Connect_CopyIdTokenOptions 结构)。

输出的 EOS_Connect_IdToken 结构包含用户的 EOS_ProductUserId,以及代表ID令牌数据的JWT。注意,等你不再需要时,你必须调用 EOS_Connect_IdToken_Release 来释放ID令牌结构。

获取后,游戏客户端就可以向另一方提供ID令牌。在每次成功的 EOS_Connect_Login 调用后都会提供一个新的ID令牌。

在本地用户的EOS连接认证会话的有效期内,ID令牌一直有效。当游戏客户端刷新验证会话时,它应默认之前使用的ID令牌会很快过期,并且如果需要,可以使用新的ID Token。

使用SDK在游戏服务器上验证ID令牌

EOS连接ID令牌的JSON网络密钥集合(JSON Web Key Set,JWKS)端点是:https://api.epicgames.dev/auth/v1/oauth/jwks

游戏服务器可以通过调用 EOS_Connect_VerifyIdToken SDK API,并传入包含 EOS_Connect_IdTokenEOS_Connect_VerifyIdTokenOptions 来验证ID令牌。注意,游戏服务器应该在调用验证前使用 EOS_ProductUserId_FromString 来填充 EOS_Connect_IdToken 结构中的 EOS_ProductUserId 部分,因为服务器的用户句柄与客户端的用户句柄不同。

不使用SDK在后台验证ID令牌

后台服务可以验证ID令牌的有效性,并使用所有公开的标准JWT库来提取令牌声明。请参见https://jwt.io/,了解与此相关的库列表。所使用的库应允许自动缓存检索的JWKS信息,以获得最佳性能并降低网络开销。

EOS SDK和其他支持库会处理安全验证ID令牌所需的步骤,然后才能安全地信任其包含的声明。所执行的步骤如下:

  1. 验证令牌签名算法("alg")是否存在并且没有被设置为 "无(none)"。

  2. 使用Epic在线服务托管的JWKS端点,对照预期的公共证书验证JWT签名。

  3. 验证令牌发行者("iss")是否存在,并且是否以https://api.epicgames.dev的基础URL开头。

  4. 验证令牌发行时间("iat")是否在过去时段。

  5. 验证令牌的到期时间("exp")是在未来时段。

  6. 验证客户ID("aud")与用于初始化EOS SDK以及游戏客户端的客户ID或其他用于验证用户与EOS连接的客户ID一致。

在成功验证ID令牌后,你可以信任产品用户UID("sub")值。

ID令牌结构

ID令牌包含以下JSON结构:

头部

Key

类型

介绍

alg

字符串

签名算法。

kid

字符串

用来签署令牌的密钥的标识符。

负载

Key

类型

介绍

aud

字符串

用于验证用户与EOS连接的客户ID。

exp

整型

令牌的失效时间,以起使时间以来的总秒数计算。

iat

整型

令牌的签发时间,以起使时间以来的总秒数计算。

iss

字符串

令牌签发者。始终以 https://api.epicgames.dev 开头。

pfdid

字符串

EOS部署ID。

pfpid

字符串

EOS产品ID。

pfsid

字符串

EOS沙盒ID。

sub

字符串

已验证用户的产品用户ID。

act

json对象

标识用于验证连接用户的外部账户。

外部账户信息(`act`)

Key

类型

介绍

eat

字符串

识别外部账户类型。可能的值包括: apple, discord, epicgames, gog, google, itchio, nintendo_id, nintentdo_nsa_id, oculus, openid, psn, steam, xbl

eaid

字符串

外部账户ID。

pltfm

字符串

用户连接的平台。可能的值包括:other, playstation, steam , switch, xbox

dty

字符串

设备类型。识别用户所连接的设备。可以用来安全地验证用户是否通过一个真正的主机设备连接的。可能的值包括:PSVITA, PS3, PS4, PS5, Switch, Xbox360, XboxOne