身份验证接口

身份验证接口

身份验证接口允许玩家（用户）使用Epic账号登录你的游戏（产品），以便访问 Epic账号服务（EAS）提供的多种功能，如好友、在线状态、UserInfo和Ecom接口。身份验证接口 将处理Epic账号与EOS的相关交互，进而提供验证用户身份并获取访问令牌的能力。

要使用身份验证接口，游戏（产品）的 Epic账号服务（EAS）必须为激活状态，并且必须获得访问 基本资料 数据的用户同意。你可以在开发人员门户激活EAS，或者在Epic的文档中了解更多信息。如果EAS未激活且未获得用户同意，仍然可以初始化EOS SDK和身份验证接口，但所有对后端服务的身份验证接口函数调用均将失败。

身份验证函数

要访问身份验证函数，需要调用

登录

要开始与EAS的在线功能进行交互，玩家必须首先使用有效的Epic账号登录。如需进行此操作，需要使用包含本地玩家账号凭证的 EOS_Auth_LoginOptions 结构体调用 EOS_Auth_Login 函数。无论登录尝试成功还是失败，完成时均将运行类型为 EOS_Auth_OnLoginCallback 的回调函数。

必须初始化 EOS_Auth_LoginOptions，并将其中的 ApiVersion 变量设置为 EOS_AUTH_LOGIN_API_LATEST，让 Credentials 变量（类型为 EOS_Auth_Credentials）包含以下信息：

将身份验证接口句柄、你的 EOS_Auth_LoginOptions 和你的回调信息传递给该函数。如果 EOS_HPlatform 句柄正在更新函数，则将在操作完成时运行提供的回调函数。

Epic账号首选登录类型

从SDK 1.5版本开始，各平台的首选登录类型如下：

主机

你的游戏将从平台为本地用户账号检索访问令牌。平台用户使用 EOS_LCT_ExternalAuth 登录类型登录Epic账号。请参阅外部账号身份验证，了解详细的登录流程，请参阅控制台特定文档，了解平台代码集成。

PC或移动设备

PC和移动设备通常使用持久登录，这是通过身份验证后端授予的长期刷新令牌启用的，并且为设备和用户账号专用。在这些平台上，SDK会根据需要自动存储并检索这些令牌，每次登录后这些令牌会更新。请参阅持久登录小节，了解更多信息。

Epic Games启动程序

当启动与Epic Games启动程序关联的应用程序时，启动程序将提供具有多个参数的命令行，格式如下：

-AUTH_LOGIN=unused -AUTH_PASSWORD=<password> -AUTH_TYPE=exchangecode -epicapp=<appid> -epicenv=Prod -EpicPortal  -epicusername=<username> -epicuserid=<userid> -epiclocale=en-US

该命令行的重要字段如下：

应用程序必须解析此信息，并通过 EOS_Auth_Credentials 结构体将其解析到 EOS_Auth_Login。EOS_Auth_Credentials 有三个变量：Id、Token、Type。Id 可以留空，因为此登录方法不需要ID。至于 Token，则需提供 AUTH_PASSWORD 命令行参数中的交换代码。最后，Type 应为 EOS_LCT_ExchangeCode。

身份验证作用域

从EOS SDK 1.5版本开始，EOS_Auth_LoginOptions 包含一个名为 ScopeFlags 的新字段，类型为 EOS_EAuthScopeFlags(API LINK)。作用域是应用程序正常运行所需的一组权限。例如，如果应用程序需要查看用户的好友列表，则必须请求 EOS_AS_FriendsList 作用域，在登录流程中需要征得用户对此操作的同意。如果用户不同意所请求作用域中的一项，则登录将失败。请求同意时，你的请求必须与在开发人员门户中为产品配置的作用域完全匹配。

关联Epic Games启动程序

当启动与Epic Games启动程序关联的应用程序时，启动程序将提供具有多个参数的命令行，格式如下：

-AUTH_LOGIN=unused -AUTH_PASSWORD=<password> -AUTH_TYPE=exchangecode -epicapp=<appid> -epicenv=Prod -EpicPortal -epicusername=<username>-epicuserid<userid> -epiclocale=en-US

该命令行的重要字段如下：应用程序必须对此信息进行解析，并通过 EOS_Auth_Credentials 结构体将其提供给 EOS_Auth_Login。EOS_Auth_Credentials 有三个变量：Id、Token、Type。对于 Type，请使用 EOS_LCT_ExchangeCode。

可以将 Id 留空，因为此字段不用于此登录类型。最后，提供来自 AUTH_PASSWORD 的交换代码，用作 Token。

Epic Games启动程序之外Epic帐户用户持久登录

在PC和移动平台上，为了支持Epic Games启动器之外的持久用户登录，请使用 EOS_LCT_AccountPortal 登录类型。

成功登录用户的Epic账号后，SDK会从身份认证后端自动接收刷新令牌，并将刷新令牌存储在设备上的本地登录用户的本地钥匙串中。对于本地钥匙串，SDK使用设备操作系统提供的安全凭证存储。

让本地用户自动登录时，游戏应该首先使用 EOS_LCT_PersistentAuth 登录类型调用 EOS_Auth_Login。由于SDK负责管理长期访问凭证，Id 和 令牌（Token） 输入字段应设置为 NULL。SDK将检查本地用户钥匙串中的刷新令牌，如果找到，将自动使用该令牌将用户登录到Epic账号。在这些平台上成功登录后，SDK将自动更新本地钥匙串中的刷新令牌。

如果 EOS_Auth_Login 因故失败，将继续使用平台的默认登录方法。如果 EOS_Auth_Login 找到刷新令牌，但因服务器拒绝该令牌而登录失败，这意味着调用失败不是因为没有令牌、连接或服务问题、操作取消或等待重试，应用程序应删除该令牌，因为它已经过时，并会继续导致今后所有会话失败。调用 EOS_Auth_DeletePersistentAuth 以显式移除用户在本地钥匙串中存储的任何凭证。然后应用程序应继续处理平台的默认登录流程。

如果已登录用户想要禁用自动登录，调用 EOS_Auth_Logout 以注销，并调用 EOS_Auth_DeletePersistentAuth 以撤销用户在身份验证后端上的长期存在的登录会话。这还将从本地用户的钥匙串中删除长期存在的刷新令牌。

注销

要注销，使用 EOS_Auth_LogoutOptions 数据结构体调用 EOS_Auth_Logout 函数。操作完成后，将运行类型为 EOS_Auth_OnLogoutCallback 的回调函数。按如下方式初始化 EOS_Auth_LogoutOptions 结构体：

将身份验证接口句柄、你的 EOS_Auth_LoginOptions 结构体、你的回调函数传递给 EOS_Auth_Logout。如果 EOS_HPlatform 句柄正在更新函数，则将在操作完成时运行提供的回调函数。

如果使用了 EOS_LCT_PersistentAuth 登录类型，请确保调用 EOS_Auth_DeletePersistentAuth 函数，以撤销验证后端上长期存在的登录会话。这也将永久忘记本地用户在本地设备上的登录信息。

状态变更通知

EOS SDK会在应用程序的整个生命周期内定期验证本地用户的身份验证状态。这样有助于确保用户没有在其他位置登录，如果用户在其他位置登录，就会因为应用程序自身以外的原因而无法访问。为了确保应用程序及时了解用户的身份验证状态变化，身份验证接口会在任何本地玩家出现这一变化时调用类型为 EOS_Auth_OnLoginStatusChangedCallback 的回调函数。你可以使用 EOS_Auth_AddNotifyLoginStatusChanged 函数将自己的回调函数附加到此过程。

应用程序生命周期内连接丢失并不代表用户已注销。发生注销事件后，EOS后端将显式通知身份验证接口，这是唯一可以安全假定用户被正式视为离线的情况。服务中断或本地硬件故障等用户连接问题可能会导致各种API功能出现故障。如果游戏可以在没有这些交互的情况下继续进行，建议的做法是继续游戏，因为我们假设连接最终可能会恢复，不需要用户注销。

检查当前身份验证状态

要在需要时检查玩家当前的状态，应使用 EOS_Auth_GetLoginStatus 函数。该函数可根据与在线服务的最新通信状态确定身份验证状态，因此可以立即返回结果，而不会使用回调函数。

外部账号身份验证

要使用外部账号通过 EOS_Auth_Login 登录，应将 EOS_Auth_Credentials 中的 Type 设置为 EOS_LCT_ExternalAuth，将 ExternalType 设置为外部凭证类型（请参阅EOS_EExternalCredentialType，了解所有可用方法的列表），并将 Token 设置为外部身份验证令牌。 例如，如果要使用Steam登录，可将 EOS_ECT_STEAM_SESSION_TICKET 用作 ExternalType，且 Token 将是Steam会话Ticket。

因外部账号未链接而导致外部身份验证登录失败时，将返回 EOS_InvalidUser。EOS_ContinuanceToken 将在 EOS_Auth_LoginCallbackInfo 数据中设置。应调用 EOS_Auth_LinkAccount，并将 EOS_ContinuanceToken 和 LinkAccountFlags 设置为 EOS_LA_NoFlags （大多数情况下需要通过账户门户或PIN授予来获得同意），以继续外部账号登录并关联外部账号。之后，外部账号将关联至用户的Epic账号。

你需要在开发人员门户上为产品配置 身份验证服务提供商，以允许使用外部账号身份验证服务关联提供商。请参阅配置身份验证服务提供商，了解更多信息。

将游戏启动程序与Epic Games商城集成

如果游戏的启动程序提供额外的启动选项、促销信息或其他新闻，则启动程序必须可以对登录流程进行管理。Epic Games启动程序生成的 交换代码 短时间内就会过期，所以必须留意，防止交换代码过期。如果Epic Games启动程序无法直接启动游戏应用程序，请使用以下模式：

1.Epic Games启动程序将启动第三方启动程序，按照上述 关联Epic Games启动程序 小节所述传递命令行上的交换代码。 2.第三方启动程序可使用交换代码让玩家登录，此时将用到 EOS_Auth_Login API。将 EOS_Auth_ClientCredentials 结构体的 类型（Type） 和 令牌（Token） 字段分别设置为 EOS_LCT_ExchangeCode 和命令行中的交换代码，从而初始化 EOS_Auth_LoginOptions。 3.玩家选择启动游戏时，使用 EOS_Auth_CopyUserAuthToken API获取令牌细节的副本。从 EOS_Auth_Token 复制 RefreshToken，然后调用 EOS_Auth_Token_Release API，释放SDK分配的内存。 4.设置游戏在启动时可以读取的环境变量，将刷新令牌传递给游戏应用程序。玩家退出第三方启动程序时，不要将其注销，否则刷新令牌会失效。 5.游戏进程启动时，游戏可以使用 EOS_Auth_Login API让玩家登录。将 EOS_Auth_ClientCredentials 结构体的 类型（Type） 和 令牌（Token） 字段分别设置为 EOS_LCT_RefreshToken 和环境变量中的刷新令牌从而初始化 EOS_Auth_LoginOptions。

使用ID令牌进行用户验证

ID令牌是OpenID Connect协议的一部分，可用于在服务器端验证用户的身份。ID令牌是一个JSON Web令牌(JWT)，它包含验证了身份的用户信息，比如他们的账号ID。后端服务和游戏服务器可以通过该功能安全地验证从客户端接接收的用户辨识符。

为用户检索ID令牌

游戏客户端可以在用户登录后调用 EOS_Auth_CopyIdToken SDK API，传入包含用户 EOS_EpicAccountId 的 EOS_Auth_CopyIdTokenOptions 结构体，进而为本地用户获取ID令牌。

输出的 EOS_Auth_IdToken 结构体包含用户的 EOS_EpicAccountId，以及代表ID令牌数据的JWT。注意，完成该操作后必须调用 EOS_Auth_IdToken_Release，以释放ID令牌结构体。

检索到令牌后，游戏客户端就可以将ID令牌提供给另一方。ID令牌始终可供登录的本地用户使用。

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

EOS身份验证ID令牌的JSON Web密钥集(JWKS)端点是：https://api.epicgames.dev/epic/oauth/v1/.well-known/jwks.json。

游戏服务器可以通过调用 EOS_Auth_VerifyIdToken SDK API，并传入包含 EOS_Auth_IdToken 的 EOS_Auth_VerifyIdTokenOptions 来验证ID令牌。注意，在调用验证前，游戏服务器应该使用 EOS_EpicAccountId_FromString 来填充 EOS_Auth_IdToken 结构体的 EOS_EpicAccountId 部分，因为服务器的用户句柄将与客户端的用户句柄不同。

不使用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，或者匹配你使用Epic 账号服务验证用户身份时使用的客户端ID。

成功验证ID令牌后，即可信任Epic账号ID("sub")的值。

ID令牌结构体

ID令牌包含以下JSON结构体：

头文件

负载

• • Share the document via:
  • Facebook
  • Twitter
  • LinkedIn
  • Reddit
  • Copy URL