身份验证网络API

介绍如何使用Web API完成Epic Games身份验证流程

阅读时间11分钟

注意 :你也可以使用身份验证接口来进行认证。请参阅Epic账户服务:身份验证接口,了解详情。

Epic游戏服务(Epic Games Services)使用OAuth 2.0协议进行身份验证和授权,它支持常见的web服务器和客户端应用用例。此外,Epic还针对一些特殊用例引入了自定义授权类型。

在开始之前,你需要从Epic获取OAuth 2.0客户端凭证。凭证会以客户端ID和密钥的形式提供,你从Epic授权服务器请求访问令牌时会用到它们。更多详情请参阅Epic账号服务入门中的使用指南。

场景

Epic Games商城中的游戏客户端

Epic Games商城 启动的游戏客户端会使用一次性 交换码 通过 Epic 授权服务器进行身份验证。该交换码由 Epic 启动程序 生成,作为命令行参数传递到 游戏客户端

游戏客户端启动后,会向 Epic 令牌端点发出请求,请求包中的信息包括客户端凭证和交换代码。响应包的内容包括 访问令牌刷新令牌(可选) 以及完成身份验证的客户端和账号的相关信息。

游戏客户端随后对Epic服务发出的所有请求都将包含该访问令牌。访问令牌还可传递至受信任的游戏服务器用于验证,或者用于服务到服务请求。

适用情况下,令牌响应中还可包含刷新令牌。访问令牌到期(一般为2小时)后,游戏客户端将需要使用刷新令牌。这通常会在访问令牌签发后的2小时内发生。

EGS客户端身份验证流程

展示Epic Games启动程序身份验证流程的图表。点击查看大图。

Web服务器应用程序

对于服务器端应用程序,该流程首先引导用户在Web浏览器上完成Epic授权流程来获取 授权代码 。系统将要求用户使用其Epic Games账号登录,并可能要求用户授权应用程序。授权完成后,用户代理将以授权代码作为查询参数,重定向回你的Web应用程序。

重定向之后,Web服务器将向Epic令牌端点发出请求,包括客户端凭证和授权代码。响应将包括访问令牌以及完成身份验证的客户端和账号的相关信息。

Web服务器随后对Epic服务发出的所有请求都将包含该访问令牌。

身份验证

作为验证流程中的第一步,用户必须使用Epic服务进行身份验证。我们仅支持使用OAuth 2.0进行身份验证,以及自定义授权类型。

当客户端获得了请求令牌所需的信息(包括交换代码、授权代码、用户凭证等)后,它会首先请求获取访问令牌。

请求访问令牌

要请求访问令牌,客户端将向Epic令牌端点发出HTTP请求,同时传递客户端凭证(客户端ID和密钥)和用户凭证。

Epic令牌端点地址为 https://api.epicgames.dev/epic/oauth/v1/token 。如果你想表面不再需要访问令牌,请使用 https://api.epicgames.dev/epic/oauth/v1/revoke。该端点实现了RFC 7009 - OAuth 2.0 Token Revocation

客户端凭证将使用基本授权模式在Authorization标头(header)中传递。此端点支持下列post参数:

参数名称说明
grant_type使用的授权类型: exchange_codepasswordrefresh_tokenclient_credentials
deployment_id客户端试图用于身份验证的部署ID。此参数会影响与其他需要部署的服务的交互。如果不是公共部署,则只有授权用户才能登录。如果部署未公开,则只有授权用户才能登录。有关部署和部署ID的更多信息,请参阅产品、沙盒和部署ID
注意:你必须使用该唯一标识符来使用电子商务API(Ecommerce API)以及请求游戏客户端使用的访问令牌。
scope将从用户请求的范围(权限)的空格分隔列表。例如:basic profilefriends_listpresence
对于password授权类型
参数名称说明
password授权类型可以在开发期间使用,但只允许用于作为此产品所关联组织的成员的账号。
注意:password授权类型在启用2FA时不适用。
username账号的用户名(电子邮件地址);仅用于password授权类型。
password账号的密码;仅用于password授权类型。
对于exchange_code授权类型
参数名称说明
exchange_code启动程序传递给游戏客户端的交换代码;仅用于exchange_code授权类型。
对于authorization_code授权类型
参数名称说明
code从授权服务器接收的授权代码。
对于client_credentials授权类型(参阅Web授权
参数名称说明
client_id你的应用程序的OAuth客户端ID。
client_secret你的应用程序的OAuth客户端密钥。

这些参数应包含在请求体中。查询参数将被忽略。

以下片段展示了一段简单的请求示例(使用 密码 授权类型):

响应包含以下字段:

响应说明
access_token访问令牌,可以有一个前缀(例如: eg1~token )。在Epic服务请求中,应使用 Bearer 类型在 Authorization 标头中按原样传递此值。
expires_in令牌过期之前的秒数。
expires_atISO 8601格式的到期日期。
account_id令牌目标用户的Epic账号ID。
client_id用于生成此令牌的客户端ID。
application_id与客户端关联的应用程序 ID。
token_type令牌类型,该值将始终为 bearer 类型。
refresh_token刷新令牌,根据客户端配置返回的可选项。此刷新令牌可用于在访问令牌到期之前或之后延长会话。
refresh_expires刷新令牌到期前的秒数。
refresh_expires_atISO 8601格式的刷新令牌到期时间。

以下片段展示了一段简单的响应示例:

访问令牌应始终按 Authorization 头文件中的原样传递给Epic服务。例如: Authorization: Bearer eyJraWQiOiJ0RkM...

Web应用程序

对于Web应用程序和服务器端应用程序,在请求访问令牌之前需要获得授权代码。使用Web授权之前,你的Epic OAuth客户端必须配置一个重定向URL。

如果你的客户端设置过程不涉及用户信息(例如你的客户端策略不需要用户),你就无需获取任何用户信息,可以跳过下面的重定向说明。你可以只使用 client_credentials 初始化客户端。

要启动该流程,应用程序需将用户重定向到授权页面,该页面将要求用户登录Epic Games账号。授权URL为:

你可以使用额外参数 redirect_uri={redirect_uri} 来定义多个重定向URL。如果多于一条重定向,验证URL是:

用户登录后,将使用授权代码返回到已配置的重定向URL。你的应用程序应该使用该代码获取访问令牌,并使用请求访问令牌中所述的 authorization_code 授权类型。

我们还支持可选的状态参数,该参数可维持请求与回调之间的状态,用于防止跨站点请求伪造攻击

以下是用户身份验证后的重定向示例:

验证访问令牌

离线验证

访问令牌是一个 JWT (JSON网络令牌),其中包括用于验证令牌真实性的标头和签名。

验证签名前,需要从我们的服务中获取以JSON Web密钥(JWK)形式发布的 公共密钥 。我们使用JWK集合格式(包括当前所有公共密钥)公开单个端点。虽然密钥集不会频繁更改,但随时可能轮换使用密钥。

JWK端点地址为 https://api.epicgames.dev/epic/oauth/v1/.well-known/jwks.json

建议已获取公共密钥的客户端将密钥缓存一段合理时间。虽然密钥会轮换使用,但对于给定的密钥ID,其密钥不会更改。

以下片段展示了从公共密钥端点返回的响应示例:

在线验证

如果无法选择离线验证,可以使用有效的访问令牌来调用令牌信息端点,进行在线验证。此端点实现了令牌内省规范。

此令牌信息端点地址为 https://api.epicgames.dev/epic/oauth/v1/tokenInfo

下列片段展示了用于验证令牌的请求示例:

以下片段展示了令牌信息端点的响应示例:

访问令牌和刷新令牌都可以使用此端点进行验证。

Epic Games商城中的游戏客户端

当你使用某个通过Epic Games商城连接的游戏客户端时,游戏客户端必须使用 exchange_code 授权类型来获取访问令牌,并传递其客户端凭证以及从启动器传递而来的代码。

在开发期间,你还可以使用 密码 授权类型,以便游戏客户端根据Epic服务进行身份验证,从而无需集成启动器。

当Epic Games启动程序启动游戏时,将传递以下命令行参数:

参数说明
AUTH_LOGIN不用于交换代码。
AUTH_PASSWORD游戏客户端将使用的凭证。其中包括要传递到身份验证服务器的交换代码。
epicapp内部应用程序名称。
epicenv启动时环境(始终是 Prod)。
epicusername在启动器中经过身份验证的账号的显示名称。
epicusername在启动器中经过身份验证的账号的Epic账号ID。
epiclocale基于用户偏好或系统语言的首选区域设置。
epicovt包含所有权验证令牌信息的文件的完整路径。
epicsandboxid应用程序运行的沙盒。例如,你的Live、Stage或Dev沙盒的ID。

以下是启动器传递命令行参数的示例:

账号信息

一旦拥有了访问令牌,你就能够代表用户向Epic服务发出请求。例如,你可以请求获取显示名称,或者用户好友的显示名称。

从访问令牌

你可以直接从访问令牌获取用户的一些相关信息。令牌被编码为 JSON Web令牌(JWT) 格式,它的头文件包含令牌类型和签名信息、一个有效负载(其中包含用户、客户端和会话的相关信息)以及一个签名。我们建议使用库来进行JWT的解码操作,如果无法使用库,请参考JWT规范。

该有效负载将包括以下信息:

声明类型说明
iss字符串发布令牌的Epic Games身份验证服务器的基本URI。
sub字符串使用client_credentials授权类型时,不会出现此声明。
aud字符串授权请求中指定的客户端ID。
iat整型令牌发布时间,UNIX时间戳格式。
exp整型令牌过期时间,UNIX时间戳格式。
jti字符串此令牌的唯一标识符。
t字符串令牌类型。此类型应始终为epic_id。该字符串将替代EG1令牌使用的版本前缀。
scope字符串授权给用户的范围列表,以空格分隔。
dn字符串用户的显示名称。
appid字符串授权请求中指定的应用程序ID。
pfpid字符串令牌请求中指定的用于部署的产品ID。
pfsid字符串令牌请求中指定的用于部署的沙盒ID。
pfdid字符串令牌请求中指定的部署ID。

我们可以使用前面例子中的令牌对有效负载进行解码,检查其是否包含以下内容:

获取账号

除了访问令牌中的信息之外,还可以请求已登录账号的类似信息,或任何与你的应用程序交互的其他账号的类似信息。

出于隐私方面的考虑,你只能请求之前已同意使用你的应用程序的那些用户的账号信息。

账号信息端点地址为 https://api.epicgames.dev/epic/id/v1/accounts 。调用此端点时,你需要为正在尝试解析的账号指定一个或多个accountId查询参数。单个请求最多允许包含 50 个账号。

下列片段展示了获取多个账号信息的请求示例:

以下片段是上述请求的响应示例: