Auth Web APIs

介绍如何使用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` 授权类型不适用于启用2FA的情况。
`username`	账户的用户名（电子邮件地址）；仅与 `password` 授权类型一起使用。
`password`	账户密码；仅与 `password` 授权类型一起使用。
对于 `exchange_code` 授权类型
`exchange_code`	启动器传递到游戏客户端的交换代码；仅用于 `exchange_code` 授权类型。
对于 `authorization_code` 授权类型
`code`	从授权服务器中获取的授权代码。
对于 `client_credentials` 授权类型（参见网络授权）
`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 个账号。

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

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