身份验证网络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小时内发生。

展示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_code` 、 `password` 、 `refresh_token` 或 `client_credentials` 。
`deployment_id`	客户端试图用于身份验证的部署ID。此参数会影响与其他需要部署的服务的交互。如果不是公共部署，则只有授权用户才能登录。如果部署未公开，则只有授权用户才能登录。有关部署和部署ID的更多信息，请参阅产品、沙盒和部署ID。注意：你必须使用该唯一标识符来使用电子商务API（Ecommerce API）以及请求游戏客户端使用的访问令牌。
`scope`	将从用户请求的范围（权限）的空格分隔列表。例如：`basic profile`、`friends_list`和`presence`

对于`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_at`	ISO 8601格式的到期日期。
`account_id`	令牌目标用户的Epic账号ID。
`client_id`	用于生成此令牌的客户端ID。
`application_id`	与客户端关联的应用程序 ID。
`token_type`	令牌类型，该值将始终为 `bearer` 类型。
`refresh_token`	刷新令牌，根据客户端配置返回的可选项。此刷新令牌可用于在访问令牌到期之前或之后延长会话。
`refresh_expires`	刷新令牌到期前的秒数。
`refresh_expires_at`	ISO 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 个账号。

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

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