Epic账号服务入门介绍

如何对你的产品设置Epic账号服务(EAS)

如果你计划在2022年10月前在主机上发布一款集成了Epic账户服务(EAS)的游戏,请联系我们eas-on-console-beta@epicgames.com确定你的发行计划。

Epic账号服务(EAS)Epic在线服务(EOS) 的独立产品。除了与身份提供程序无关的EOS服务系列之外,Epic账号服务还引入了单独的Epic账号专用服务系列。Epic在线服务 需要使用Epic账号服务,但是你始终可以将EAS作为你的EOS身份提供程序之一启用,并使用身份验证界面。有关使用与身份提供程序无关的服务的更多信息,请参阅连接界面

在开始设置Epic账号服务账号和应用程序之前,请确保你满足以下先决条件:

  • 注册开发人员门户,并在该账号上启用多重要素验证。

  • 创建自己的 组织 或加入现有组织。你需要Epic账号或管理员角色才能继续操作。

  • 创建或选择产品,使用Epic账号服务。

  • 下载最新版EOS SDK。查看EOS快速入门指南,了解更多细节。

1. 在开发人员门户访问Epic账号服务

你可以在 开发人员门户 通过导航面板或产品主页找到Epic账号服务。

要继续使用EAS控制面板,你需要查看并接受 Epic账号服务的服务附录。你始终可以在 开发人员门户 组织 部分的 许可证(Licenses) 选项卡查看所有已接受协议。

你还可以查看 Epic Games隐私政策,了解Epic Games如何收集、使用和共享用户数据。

根据你的组织类型,你可能只需要接受每种许可协议一次(作为 公司 实体)。然而,个人 实体需要每个成员有接受协议的EAS控制面板访问权限。

借助标准EOS服务,你授权Epic Games为服务提供商,代表你处理用户数据。 但借助EAS,Epic Games可管理用户数据和身份验证流程,并在用户同意的情况下代表用户公开此数据和功能。对于你而言,你同意将数据仅用于 Epic账号服务的服务附录 中所定义的许可用途。

2. 设置EAS应用程序

在Epic账号服务控制面板中,你可以继续创建第一个应用程序。开发人员门户将显示未来应用程序的占位符,但不显示任何配置细节。

点击查看大图。

应用程序配置包括三个主要部分:

  1. 品牌设置:名称、徽标、隐私政策URL和支持URL。

  2. 权限:应用程序向用户请求的访问权限。

  3. 已关联客户端:身份验证流程中,应用程序与SDK使用的客户端凭证关联。

点击 配置(Configure) 继续各项操作。

应用程序品牌设置

配置应用程序的第一部分是 应用程序品牌设置

点击查看大图。

左侧你可以预览同意对话框,该对话框将向Epic用户展示,要求用户允许与该应用程序共享信息。预览分为移动版和网站版。

最初,红色警告横幅将显示在同意对话框预览的顶部。此警告指示尚未对应用程序品牌设置就潜在病毒性或品牌欺诈尝试进行审核。此外,未验证应用程序的同意对话框前面还有另一个警告对话框。双重警告旨在完全确保用户理解继续使用未验证应用程序的所有影响。

所有应用程序在创建时均未验证,并且具有受众限制。仅同一开发组织的成员能使用Epic Games账号对未验证应用程序进行身份验证。所有其他用户将看到受众限制错误消息。受众限制旨在保护Epic用户,同时允许开发人员在准备应用程序品牌审核时迭代集成。

要删除限制,必须在右侧字段填写细节并提交,用于应用程序品牌审核。包括:

  • 应用程序名称:将向用户展示应用程序的友好名称。默认情况下,设置为产品名称。

  • 隐私政策URL:用户可查看应用程序隐私政策的URL。

  • 应用程序徽标:128x128不透明PNG或JPG图片,用于在同意对话框中表示应用程序。

你更新这些字段时,预览将立即更新以体现更改。

点击查看大图。

创建应用程序并保存品牌设置后,请转到下一个选项卡。

应用程序权限

权限(Permissions) 选项卡中,你可以定义应用程序向用户请求的访问级别。

点击查看大图。

Epic账号服务支持三种基本权限:

  • 基本资料:允许读取用户显示名称、语言首选项和关联账号的显示名称。

  • 在线状态:允许该应用程序设置当前用户的在线状态并接收好友的在线状态更新。

  • 好友:允许读取当前用户账号的好友列表。

Epic账号服务始终需要基本资料权限,并且无法停用,因为若没有该权限,你将无法访问任何用户数据。可根据应用程序需求启用或禁用在线状态和好友权限。切换你要为应用程序启用的权限,然后点击 保存(Save) 保存更改。同意对话框预览将更新,体现添加或删除的权限。

点击查看大图。

应用程序客户端

最后,可通过 客户端(Clients) 选项卡配置与此应用程序关联的客户端列表。客户端 是可在Epic账号服务后端中访问应用程序数据的软件或网站。与应用程序关联的所有客户端都列在产品设置中,一旦用户同意,所有客户端均共享用户授予的同意。

点击查看大图。

若你已为应用程序设置客户端,则你可以从 选择客户端(Select Clients) 下拉列表中选择。否则,请点击 创建新客户端(Create New Client),打开 产品设置(Product Settings) 页面并配置新客户端。有关更多信息,请参见客户端凭证页面,获取有关添加新客户端的更多信息。

你将客户端添加到此列表后,点击 保存(Save) 按钮保存更改。

点击查看大图。

此时,你已完成EAS应用程序配置。你可以从此处将EAS集成到产品中,并用EAS访问用户数据。审核你提交的应用程序品牌设置后,将取消受众限制,并且组织外的用户可看到该应用程序。

点击查看大图。

3. 使用EOS SDK验证Epic Games用户的身份

使用Epic账号无需在EOS SDK中进行特殊设置。但是,你必须使用适合你目标平台的登录类型(请参阅身份验证界面),并且你必须记住在你的品牌审核申请期间,将你希望用户在登录调用中同意的范围(他们的配置文件、在线状态和朋友列表)包括在内。

例如,要在PC上通过账号门户登录,登录调用可能显示如下:

EOS_Auth_Credentials Credentials = { 0 };
Credentials.ApiVersion = EOS_AUTH_CREDENTIALS_API_LATEST;
Credentials.Type = EOS_LCT_AccountPortal;

EOS_Auth_LoginOptions LoginOptions = { 0 };
LoginOptions.ApiVersion = EOS_AUTH_LOGIN_API_LATEST;
LoginOptions.ScopeFlags = EOS_AS_BasicProfile | EOS_AS_FriendsList | EOS_AS_Presence;
LoginOptions.Credentials = &Credentials;

EOS_Auth_Login(AuthHandle, &LoginOptions, NULL, OnLoginCallback);

这将打开默认的系统Web浏览器,提示用户登录并查看访问应用程序请求。

4. 在网站上验证Epic Games用户的身份

为了对网站和Web应用程序上的用户进行身份验证,我们支持[OpenID Connect Core 1.0]的授权代码流(https://openid.net/specs/openid-connect-core-1_0.html)。在你开始之前,你必须配置品牌审核应用程序客户端凭证

用户授权

要启动身份验证流程,应用程序需将用户重定向到授权页面,他们可以在该页面登录Epic Games账号。

将用户重定向到此授权URL:

https://www.epicgames.com/id/authorize?client_id={client_id}&response_type=code&scope=basic_profile&redirect_uri=https://www.example.com&state=rfGWJux2WL86Zxr6nKApCAnDo8KexEUE

要请求其他权限,请使用用空格分隔的所需权限列表修改授权请求中的范围参数。例如 scope=basic_profile friends_list

然后,你需要在开发人员门户配置客户端的重定向URL。

用户登录后,将要求他们批准请求权限。接受之后,用户将被重定向回应用程序,并提供 代码 参数。请求访问令牌时将使用该代码。

Epic Games还支持 可选状态 参数,你可以使用该参数维护请求和回调之间的状态。这可以防止跨站点请求伪造攻击。

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

https://www.example.com/?code=cfd1de1a8d224203b0445fe977838d81&state=rfGWJux2WL86Zxr6nKApCAnDo8KexEUE

请求访问令牌

要请求访问令牌,客户端将向令牌端点发出请求,包括客户端凭证和授权代码。Epic Games令牌端点为 https://api.epicgames.dev/epic/oauth/v1/token

客户端凭证将使用基本授权授权 标头中传递。

你还需要在请求中指定 authorization_code 授权类型,并包括来自授权流程的代码和重定向URL。

以下片段显示的是请求示例(使用密码授权类型):

POST /epic/oauth/v1/token HTTP/1.1
Host: api.epicgames.dev
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Zm9vOmJhcg==
grant_type=authorization_code&
deployment_id=foo&
scope=basic_profile&
code=cfd1de1a8d224203b0445fe977838d81&
redirect_uri=https://www.example.com

响应包含以下字段:

响应

说明

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格式的刷新令牌到期日期。

以下片段显示了响应示例:

{
  "scope": "basic_profile",
  "token_type": "bearer",
  "access_token": "eyJ0IjoiZXBpY19pZCIsImFsZyI6IlJTMjU2Iiwia2lkIjoibldVQzlxSFVldWRHcnBXb3FvVXVHZkFIYmVWM2NsRnlsdFRYMzhFbXJKSSJ9.eyJhdWQiOiJ4eXphNzg5MWxoeE1WWUdDT043TGduS1paOEhRR0Q1SCIsInN1YiI6Ijk2MjZmNDQxMDU1MzQ5Y2U4Y2I3ZDdkNWE0ODNlYWEyIiwidCI6ImVwaWNfaWQiLCJzY29wZSI6ImJhc2ljX3Byb2ZpbGUgZnJpZW5kc19saXN0IHByZXNlbmNlIiwiYXBwaWQiOiJmZ2hpNDU2N08wM0hST3hFandibjdrZ1hwQmhuaFd3diIsImlzcyI6Imh0dHBzOlwvXC9hcGkuZXBpY2dhbWVzLmRldlwvZXBpY1wvb2F1dGhcL3YxIiwiZG4iOiJLcm5icnkiLCJleHAiOjE1ODgyODYwODMsImlhdCI6MTU4ODI3ODg4Mywibm9uY2UiOiJuLUI1cGNsSXZaSkJaQU1KTDVsNkdvUnJDTzNiRT0iLCJqdGkiOiI2NGMzMGQwMjk4YTM0MzdjOGE3NGU1OTAxYzM0ODZiNSJ9.MZRoCRpjIb--dD7hxoo2GvjSPhUSNpOq1FhtShTBmzMJ1qlHFPzNaUiAEETAc3mabGPKyOxUP6Q1FBadr_P_UtbtB7kf34hN2VTv5czW6WOx1HdpjwUQZuxFyDc_aix7FCS0Egu4rZlC65b-B0FUVlial_s_FrH8ou5L_d-4I0KVpIwtv-b_M6EQ9jtLdQRfMaP6aV0rIerrbqFZ617Pe7XT4IO9jZFwM8F5aDTeDHkkOO41wyVibrm38799lP4B65RIv9CwbAL-TVmV1L5gFYITaZhi5ShfZzTvxAk-3Dxwp8c5JvcO68zpbya5gFSAfhsd7vt9YLU0gQR2uXq3Vw",
  "refresh_token": "eyJ0IjoiZXBpY19pZCIsImFsZyI6IlJTMjU2Iiwia2lkIjoibldVQzlxSFVldWRHcnBXb3FvVXVHZkFIYmVWM2NsRnlsdFRYMzhFbXJKSSJ9.eyJhdWQiOiJ4eXphNzg5MWxoeE1WWUdDT043TGduS1paOEhRR0Q1SCIsInN1YiI6Ijk2MjZmNDQxMDU1MzQ5Y2U4Y2I3ZDdkNWE0ODNlYWEyIiwidCI6ImVwaWNfaWQiLCJhcHBpZCI6ImZnaGk0NTY3TzAzSFJPeEVqd2JuN2tnWHBCaG5oV3d2Iiwic2NvcGUiOiJiYXNpY19wcm9maWxlIGZyaWVuZHNfbGlzdCBwcmVzZW5jZSIsImlzcyI6Imh0dHBzOlwvXC9hcGkuZXBpY2dhbWVzLmRldlwvZXBpY1wvb2F1dGhcL3YxIiwiZG4iOiJLcm5icnkiLCJleHAiOjE1ODgzMDc2ODMsImlhdCI6MTU4ODI3ODg4MywianRpIjoiYzczYjA2NmUyZDU4NGVkNTk0NjZiOThiNzI3NzJiMjAifQ.O-eVa46NimubKwxe9SwlHxciivu0XWe1-DSL74mMiA_PpPoW0yKL9DfmsLxiPCwsRB5_hQTc6_FM7G1FyfKtX_VVAp90MZPkhCbAbfKmTpQVcL0Ya6kve4KMG8KxeLVfLLhubCbJTYlnDNVHobbpvpQtHd8Ys321ZNDJj05l_tnZzdgus-xmCO6orX4UP4wDd1jAOXXeqRT47OXuLCgSE0q6Osfh-ENPwh6ph1i7ld759xPV0oNcQb8XiPxnT6_FUmFugzG1YS1z9bTnVWmbP2RmYluue5VQm5EKGJZ91Alve8s2eNEtDfUqaBLZ45pqGkc1KjbYTtP0a_1ue2BpkQ",
  "expires_in": 7200,
  "expires_at": "2020-04-30T22:34:43.549Z",
  "refresh_expires_in": 28800,
  "refresh_expires_at": "2020-05-01T04:34:43.549Z",
  "account_id": "9626f441055349ce8cb7d7d5a483eaa2",
  "client_id": "xyza7891lhxMVYGCON7LgnKZZ8HQGD5H",
  "application_id": "fghi4567O03HROxEjwbn7kgXpBhnhWwv"
}

你应该始终将访问令牌,它位于Epic Games服务的授权标头中。例如:Authorization: Bearer eyJraWQiOiJ0RkM...

端点

名称

URL

OpenID 配置

https://api.epicgames.dev/epic/oauth/v1/.well-known/openid-configuration

授权

https://www.epicgames.com/id/authorize

令牌

https://api.epicgames.dev/epic/oauth/v1/token

用户信息

https://api.epicgames.dev/epic/oauth/v1/userInfo

令牌信息

https://api.epicgames.dev/epic/oauth/v1/tokenInfo

JWK

https://api.epicgames.dev/epic/oauth/v1/.well-known/jwks.json