身份验证接口

用于处理用户账户身份验证的接口，包括处理用户的登录和注销功能。

阅读时间30分钟

注意：你也可以用Auth Web API进行认证。请参阅EOS Web API参考文档：Auth Web API 获得更多信息。

身份验证接口

你可以使用身份验证接口，让玩家直接在你的游戏中登录其Epic Games账户。使用该接口来验证玩家，获得访问令牌，并处理与Epic在线服务的其他账户相关互动。当玩家登录到他们的Epic游戏账户时，你可以让他们使用其他Epic账户服务，例如好友、在线信息、用户信息和Ecom接口。

你也可以使用连接接口，让玩家借助受支持的身份提供者登录游戏。关于在游戏中使用连接接口的更多信息，请参见连接接口文档。身份验证接口和连接接口的区别列在下表中：

Auth InterfaceConnect Interface
Player IDThe player's Epic Games account ID. The player can sign in with an email and password combination, or a linked external account1.A Product User ID (PUID) for a player, that's linked to one or more supported identity providers2. Note that the PUID is specific to a single product.
AccessThe player can sign in to Epic Account Services across any PC (Windows, Mac, and Linux) platform and storefront. Note: Game console and mobile platform access is coming at a future date.The player can authenticate their account in your game to access EOS Game Services across any platform (PC (Windows, Mac, and Linux), console, and mobile) and storefront.
Supported ServicesThe player has access to the Friends3, Presence4, and Ecom5 interfaces, as well as the EOS Social Overlay6.The player has access to Game Services across Multiplayer, Progression, Moderation, and Operations.
Access Token LifetimeThe game automatically refreshes the token as long as it calls EOS_Platform_Tick7.The game must periodically refresh the player's token based on expiration notification events8.

如果你的客户端设置过程不涉及用户信息（例如你的客户端策略不需要用户），你可以只使用 client_credentials 初始化客户端。你不需要任何用户信息。

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

注意： 如要使用Epic在线服务（EOS）SDK，你的本地网络、路由器和防火墙必须允许对特定主机地址的访问。这些主机地址的完整列表，请参阅防火墙注意事项文档。

身份验证函数

要访问身份验证函数，需要调用 平台接口 函数获取 EOS_HAuth 句柄 EOS_Platform_GetAuthInterface。身份验证接口函数需要这个句柄来访问用户信息。

登录

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

品牌审核流程会验证你的游戏的品牌。一旦经过验证，你的 组织 以外的玩家就可以使用你的游戏中集成的Epic账户服务。在品牌审核之前，如果玩家试图用外部账户登录你的游戏，他们会收到一个错误。请参阅品牌审核申请过程，了解更多细节。

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

属性值
ApiVersionEOS_AUTH_CREDENTIALS_API_LATEST
Id用户登录身份信息。与大多数其他函数不同，该函数应该是一个用户可读的身份信息，如电子邮件地址或显示名称。
Token用户的登录凭证或身份验证令牌。
Type此登录尝试正在使用的凭证类型。EOS_ELoginCredentialType 将列出可用的凭证类型。
SystemAuthCredentialsOptions如有需要，此字段用于系统特定选项。
ExternalType如果 Type 设置为 EOS_LCT_ExternalAuth，此字段将指示使用哪种外部身份验证方法。请参阅EOS_EExternalCredentialType，了解所有可用方法的列表。

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

Epic账号首选登录类型

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

平台登录类型摘要
Epic Games启动程序EOS_LCT_ExchangeCode从 Epic Games 启动程序接收到的交换代码，用于自动登录用户。
任天堂SwitchEOS_LCT_AccountPortal with EOS_LCT_PersistentAuth用户会被提示使用其Epic账户凭据进行登录，之后会有一个长期有效的刷新令牌保存在本地，以便在连续的应用程序运行中实现自动登录。
Steam客户端EOS_LCT_ExternalAuth基于Steam会话的Ticket，用于让本地Steam用户自动登录与他们相关的Epic账户。
Epic Games启动程序EOS_LCT_ExchangeCode从启动程序接收并用于让用户自动登录的交换代码。
其他商店平台，以及PC/移动设备上的独立发行平台EOS_LCT_AccountPortal 与 EOS_LCT_PersistentAuth提示用户使用他们的Epic账户凭证登录，然后会在本地存储一个长期的刷新令牌，以便在后续实现自动登录。
Epic Games启动程序

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

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

属性值
AUTH_LOGIN该字段可能是用户ID，但当前未使用。
AUTH_PASSWORD该字段将是交换代码本身，应在登录时作为令牌提供。
AUTH_TYPE该类型将显示为 "exchangecode"，表示 EOS_Auth_LoginCredentials 应使用 EOS_LCT_ExchangeCode 类型。

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

任天堂Switch

你的游戏会在本地设备上存储一个长期有效的Epic刷新令牌，以便在游戏会话之间自动登录。有关更多信息，请参见Epic Games启动程序之外Epic帐户用户持久登录部分。

PlayStation、Steam 和 Xbox

你的游戏会从平台获取本地用户账户的访问令牌。平台用户会使用 EOS_LCT_ExternalAuth 登录类型，登录到其Epic账户。请参阅外部帐户身份验证，获取详细的登录流程，以及与平台代码集成相关的主机平台文档。

你只能在拥有适当权限的情况下访问控制台文档。请参阅入门步骤文档，获取有关如何访问控制台EOS SDK及其相关文档的更多信息。

PC或移动设备

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

身份验证作用域

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

多个用户可以同时在单个本地设备上登录，并使用相同的共享EOS_HPlatform实例

关联Epic Games启动程序

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

该命令行的重要字段如下：应用程序必须对此信息进行解析，并通过 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 结构体：

属性值
ApiVersionEOS_AUTH_LOGOUT_API_LATEST
LocalUserIdEOS_EpicAccountId

将身份验证接口句柄、你的 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账号。

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

EOS Authentication Flow

将游戏启动程序与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令牌不能用于代表用户执行操作。仅可用于对用户进行用户身份验证。

为用户检索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结构体：

头文件

密钥类型描述
alg字符串签名算法。
kid字符串用于对令牌签名的密钥的辨识符。
t字符串令牌类型。始终设置为 id_token。

负载

密钥类型描述
appid字符串EAS应用程序ID。
aud字符串使用Epic账号服务验证用户身份的客户端ID。
cty字符串Epic账户注册时使用的国家代码，采用ISO 3166双字符格式。如果应用程序要求使用 country 范围，则会出现这一可选项。
dn字符串Epic账号显示名称。
exp整型令牌的到期时间，时间戳开始计算时间起累积的秒数。
iat整型令牌的签发时间，时间戳开始计算时间起累积的秒数。
iss字符串令牌签发者。总是以 https://api.epicgames.dev 开头。
pfdid字符串EOS部署ID。
pfpid字符串EOS产品ID。
pfsid字符串EOS沙盒ID。
sub字符串验证了身份的用户的Epic账号ID。
eat字符串外部账户类型。 如果用户使用外部账户凭证登录他们的Epic账户（例如通过本地平台认证），则会出现此可选项。
eadn字符串外部账户显示名称。 此项可能不会一直出现。
pltfm字符串

用户连接的平台来源。 如 eat 存在则显示。可能值包括:

  • other
  • playstation
  • steam
  • switch
  • xbox

注释

  1. 参见身份验证接口，了解有关链接的外部账户的更多详情。↩

  2. 参见身份提供商管理，了解有关身份提供商的更多详情。↩

  3. 参见好友接口 ，了解有关使用好友接口的更多详情。↩

  4. 参见在线状态接口，了解有关使用在线状态接口的更多详情。↩

  5. 参见Ecom接口，了解有关使用Ecom接口的更多详情。↩

  6. 参见社交覆层概述，了解有关EOS社交覆层的更多详情。 ↩

  7. 参见Api参考文档 ，了解有关调用 EOS_Platform_Tick 的更多详情。 ↩

  8. 参见连接接口 ，了解有关失效通知事件的更多详情。 ↩