注意 :你也可以使用身份验证接口来进行认证。请参阅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 个账号。
下列片段展示了获取多个账号信息的请求示例:
以下片段是上述请求的响应示例: