第三方登录

关于本文

本文档为 ESP RainMaker 用户提供了使用谷歌和苹果登录的分步指南。本文主要讲解了如何在谷歌 API 控制台和苹果开发者控制台中设置 OAuth 凭证、如何在 AWS Cognito 中配置身份验证设置，以及如何将这些身份提供商集成到 ESP RainMaker 管理面板。此外，本文还涵盖使用 Cognito 托管 UI 验证集成是否成功的步骤，以及如何启用苹果的私人邮件中继以增强隐私保护。
详情请参阅使用谷歌登录、使用苹果登录 或使用微信登录。
在此之前，请先在下方选择相应的使用范围。

---

全球地域

• 使用谷歌登录（可选）
  • 准备工作
  • 配置谷歌应用客户端
  • 验证谷歌登录
• 使用苹果登录（可选）
  • 准备工作
  • 配置苹果登录
  • 验证苹果登录

使用谷歌登录（可选）

终端用户可选择使用谷歌账户登录 RainMaker 移动应用。

本节将介绍如何为终端用户配置谷歌登录。

准备工作

---

1. 已创建谷歌开发者账户，网址为 https://console.developers.google.com/）。
2. 已部署 ESP-RainMaker-Core。
3. 已创建自定义域名（请参考配置客户域名）。

配置谷歌应用客户端

配置谷歌开发者账号

---

• 使用谷歌开发者账号登陆谷歌 API 控制台，请使用网址
  https://console.developers.google.com/。

• 登录谷歌开发者控制台后，会看到以下窗口。

• 要创建谷歌 API 控制台项目，请点击左上角标题栏旁的 ▼ 图标，如下图所示。

• 在跳出的窗口中，点击右上角的 NEW PROJECT。

• 输入项目名称并点击 CREATE。

项目创建完成后，需要配置 OAuth 授权界面。下面介绍如何配置 OAuth 授权。

注意：你需要对新创建的项目进行配置。 如果你的谷歌开发者账号有多个项目，请从项目列表中选择新创建的项目，再点击左上角标题栏中的 ▼ 图标。

• 前往谷歌 API 控制台，在左边的导航窗格中，点击 OAuth consent screen。

• 选择 User Type 为 External，然后点击 CREATE。

• 在 App information 部分，填写 App name 和 User support email 字段。你也可以填写 Application Home Page、Application Privacy Link、Application Terms of Service Link 等可选信息。

• 在 Authorized domains 部分，点击 ADD DOMAIN。

• 输入域名 amazoncognito.com，如下图所示。

• 在 Developer contact information 部分，输入有效的电子邮件地址，该地址为开发者的联系信息。

• 点击 SAVE AND CONTINUE。

• 然后再次点击 SAVE AND CONTINUE。

• 检查改动，如果无误，点击 BACK TO DASHBOARD。

• 接着需要获取 OAuth 2.0 客户端凭证。前往谷歌 API 控制台，在左边的导航窗格中，点击 Credentials。

• 点击 + CREATE CREDENTIALS 并选择 OAuth client ID。

• 在 Application type 字段中选择 Web Application。

• 在 Name 字段中输入你 OAuth 客户端的名字。
• 在 Authorized JavaScript origins 部分，点击 ADD URI。

对比标准 RainMaker 和 OAuth-only RainMaker

标准 RainMaker

• 输入你的 Amazon Cognito 域名 https://<your-company-domain>.auth.<aws-region>.amazoncognito.com， 如下所示。
  该域名可通过配置 Cognito 域名 获取。

---

OAuth-only RainMaker

• 输入 HTTP 基础 URL（不含阶段）
• 参考示例 https://<API gateway Id>.execute-api.<AWS-Region>.amazonaws.com

• 在 Authorized redirect URIs 部分，点击 ADD URI。

对比标准 RainMaker 和 OAuth-only RainMaker

标准 RainMaker

• 输入你的 Amazon Cognito 域名
  https://<your-company-domain>.auth.<aws-region>.amazoncognito.com/oauth2/idpresponse，如下图所示。
  该域名可通过配置 Cognito 域名 获取。

提醒

记得在自定义的 Cognito 域后面添加 /oauth2/idpresponse。

---

OAuth-only RainMaker

• 获取 HTTP API 端点。
• 重定向 URI 为 {HTTP API Endpoint}/cognitocallback

---

:::

• 点击 CREATE。

• 在 OAuth 客户端对话框中，找到 Client ID 和 Client Secret，记下这些值以备后用。

至此，你已完成谷歌应用客户端配置。

在 RainMaker 管理面板中将谷歌配置为身份提供商

---

• 用管理员账号登录 RainMaker 管理面板，打开 Deployment Settings。

• 打开 Identity Providers 标签页。

• 点击 + 图标，添加身份供应商配置。

• 从 Identity Provider 下拉菜单中选择 Google。

• 添加前面步骤中提到的 Client ID 和 Client Secret。

将谷歌启用为身份供应商

信息

此功能与 OAuth-only RainMaker 无关。

1. 用管理员账户登录 RainMaker 管理面板，打开 Deployment Settings。

2. 打开 Cognito Configurations 标签页。

3. 根据自身需求，为客户端启用 google 身份提供商。启用该选项后，用户可以使用谷歌账户登录客户端。

配置回调 URL（重定向 URI）

回调 URL 指明了用户使用第三方认证成功登录后将被重定向的网页。用户使用第三方认证服务成功注册后，将被重定向至这些网页之一。

若需要将用户重定向至手机应用，则应为该应用设置回调 URL。为手机应用设置回调 URL（重定向 URI），请参考以下小节：

• 为安卓应用获取重定向 URI

• 为 iOS 应用获取重定向 URI

在 RainMaker 管理面板中配置回调 URL，请参考配置 Cognito 回调 URL。

验证谷歌登录

信息

OAuth-only RainMaker 尚不支持此功能。

---

本节将介绍如何验证谷歌登录是否已配置成功。

• 登录 AWS 控制台，前往 Amazon Cognito > User pools，获取用户池列表。

• 点击 rainmaker-user-email-mobile-pool。

• 前往 App integration > App Client Lists。

• 点击 rainmaker-user-email-mobile-pool-client，此处可以查看应用客户端的相关信息。

• 向下滚动页面并点击 View Hosted UI。

• 在跳出的窗口中，可以看到以下选项：

• 点击 Continue with Google。

• 输入你的电子邮件地址和密码。

• 点击 Next，你将被重定向到 Cognito 应用客户端中配置好的回调 URL，并且可以在浏览器网址栏中查看验证码。

注意：本示例已将回调 URL 设置为乐鑫官网主页网址，因此会被重定向至该页面。

---

使用苹果登录（可选）

终端用户可使用苹果账号登录 RainMaker 移动应用。
本节将介绍如何为终端用户配置苹果登录。

准备工作

---

1. 已创建苹果开发者账号，并已注册开发者项目 (Apple Developer Program)。网址为 https://developer.apple.com/programs/enroll/）。
2. 已部署 ESP-RainMaker-Core。
3. 已创建自定义域（请参阅配置自定义域名）。

配置苹果登录

配置苹果开发者账号

---

1. 若尚未创建苹果应用 ID，请在苹果开发者控制台创建应用 ID。

2. 点击左侧 Keys。

3. 点击 + 图标添加新密钥。

4. 在 Key Name 字段输入密钥的名称，并在下方选择 Sign in with Apple。

5. 在 Sign in with Apple 一栏右侧点击 Configure。

6. 在 Primary App ID 字段选择应用 ID，格式为 "<teamId>.<bundleId>"。其中 Team ID 值和 Bundle ID 值请参见步骤 1。

7. 点击 Save 保存配置。

8. 在 Register a New Key 页面，点击 Continue。

9. 检查更改，并点击 Register 以创建新的密钥。

10. 记下密钥 ID 并下载密钥文件，在 RainMaker 管理面板中配置苹果登录时将会用到这些内容。

11. 点击 Identifiers，然后点击 + 图标。

12. 从列表中选择 Service IDs 并点击 Continue。

13. 在 Register a Services ID 页面，选择 Sign in with Apple 以启用服务，然后选择 Configure。

14. 在 Identifier 和 Description 字段为服务填写标识符和描述。

15. 记下标识符，即服务 ID (Services ID)。在 RainMaker 管理面板中配置苹果登录时将会用到这一 ID。

16. 点击 Register 以注册服务 ID。

17. 重新回到 Identifiers 页面，点击上述步骤中已经注册的服务 ID。

18. 启用 Sign In With Apple，然后点击 Configure。

19. 配置域名。

标准 RainMaker 或 OAuth-only RainMaker

标准 RainMaker

• 输入 Amazon Cognito 域名 https://<your-company-domain>.auth.<aws-region>.amazoncognito.com，如下所示。
  该域名可通过配置 Cognito 域名 获取。

---

OAuth-only RainMaker

• 输入 HTTP 基础 URL（不含阶段）

20. 返回 URL。

标准 RainMaker 或 OAuth-only RainMaker

标准 RainMaker

• 输入 Amazon Cognito 域名
  https://<your-company-domain>.auth.<aws-region>.amazoncognito.com/oauth2/idpresponse，如下所示。
  该域名可通过配置 Cognito 域名 获取。

注意

记得在自定义的 Cognito 域后面添加 /oauth2/idpresponse。

---

OAuth-only RainMaker

• 获取 HTTP API 端点。
• 重定向 URI 为 {HTTP API Endpoint}/cognitocallback。此处的域名为 AWS Cognito 中创建的域名。返回 URL 应为 https://<domain>/oauth2/idpresponse。

:::

在 RainMaker 管理面板中将苹果配置为身份提供商

---

1. 用管理员账号登录 RainMaker 管理面板，打开 Deployment Settings。

2. 打开 Identity Providers 标签页。

3. 点击 + 图标，添加身份提供商配置。
4. 从 Identity Provider 下拉菜单中选择 SignInWithApple。
5. 添加 Client ID，即“配置苹果开发者账号”小节步骤 15 中提到的服务 ID。
6. 在 Provider Name 字段输入 "Apple"。
7. 在 Key ID 字段输入“配置苹果开发者账号”小节步骤 1 和 10 中提到的密钥 ID。
8. 在 Team ID 字段输入“配置苹果开发者账号”小节步骤 1 中提到的团队 ID。详情请参阅创建 App ID。
9. 在 Private Key 字段输入“配置苹果开发者账号”小节步骤 10 中所下载文件的内容。

将苹果启用为身份提供商

注意

此功能与 OAuth-only RainMaker 无关。

1. 用管理员账户登录 RainMaker 管理面板，打开 Deployment Settings。

2. 打开 Cognito Configurations 标签页。

3. 根据自身需求，为客户端启用 signinwithapple 身份提供商。启用该选项后，用户可以使用苹果账户登录客户端。

配置回调 URL（重定向 URIs）

回调 URL 指明了用户使用第三方认证成功登录后将被重定向的网页。用户使用第三方认证服务成功注册后，将被重定向至这些网页之一。

若需要将用户重定向至手机应用，则应为该应用设置回调 URL。设置 iOS 应用回调 URL（重定向 URI）的方法可以参考创建重定向 URL。

在 RainMaker 管理面板中配置回调 URL，请参考配置 Cognito 回调 URL。

验证苹果登录

---

注意

对于OAuth-only RainMaker，请参考此文。

本节介绍如何验证苹果登录是否已配置成功。

• 登录 AWS 控制台，前往 Amazon Cognito > User pools，获取用户池列表。

• 点击 rainmaker-user-email-mobile-pool。

• 前往 App integration > App Client Lists。

• 点击 rainmaker-user-email-mobile-pool-client，此处可以查看应用客户端的相关信息。

• 向下滚动页面并点击 View Hosted UI。

5. 在跳出的窗口中，可以看到以下选项：

6. 点击 Continue with Apple。

7. 输入你的苹果账号 ID和密码。

8. 点击 Next，你将被重定向到 Cognito 应用客户端中配置好的回调 URL，并且可以在浏览器网址栏中查看验证码。

注意：本示例已将回调 URL 设置为乐鑫官网主页网址，因此会被重定向至该页面。

电子邮件转发服务

苹果私人邮件转发服务 适用于重视隐私的用户，使其在创建账户时保持个人邮箱地址的私密性。使用转发服务向用户发送电子邮件，你需要注册出站电子邮件域名、子域名或电子邮件地址。此外，你还必须为所有注册域名创建 SPF (Sender Policy Framework) 的 DNS TXT 记录。

请参考以下步骤，查看你的组织电子邮件域名是否已创建 SPF 记录：

1. 访问 https://dnschecker.org/spf-record-validation.php。
2. 输入你的电子邮件域名并点击 validate。
3. 向下滚动页面。如果看到的页面如下图所示，则代表你的电子邮件域名已创建 SPF 记录。

请参考以下步骤添加域名：

1. 在 Certificates, Identifiers & Profiles 中，从侧边栏中选择 More，然后点击 Configure Sign in with Apple for Email Communication。
2. 在 Email Sources 部分，点击左上角的添加按钮 +。
3. 输入用于电子邮件通信的域名、子域名和唯一电子邮件地址，不同名称之间用逗号隔开，然后点击 Next。
4. 确认你输入的电子邮件域名信息无误后，点击 Register。
5. 如果你注册的电子邮件域名已通过 SPF 验证，则将看到以下内容：

中国地域

• 使用微信登录（可选）
  • 准备工作
  • 创建开发者账号
  • 在微信中创建客户端
  • 在 RainMaker 中创建提供商

使用微信登录（可选）

准备工作

在中国地域 (cn-north-1) 部署 RainMaker。

创建开发者账号

1. 访问 https://open.weixin.qq.com/。
2. 如果尚未注册，请注册一个已验证的企业账号。
3. 你需要支付一笔一次性的审核费用（在撰写本文档时约为 300 人民币）。
4. 详细步骤如下：
   https://developers.weixin.qq.com/doc/oplatform/cn/Third-party_Platforms/2.0/operation/open/create.html
5. 审核需要 3～5 个工作日。
6. 审核通过后，你的账号将如下所示：

在微信中创建客户端

应用客户端

1. 安卓用户需要提供以下信息：

你需要提供 APK 签名证书的 MD5 摘要。

2. 苹果用户需要提供以下信息：

你需要为应用提供一个通用链接。请参考以下步骤创建通用链接。

3. 应用类型为“工具-设备管理”
4. 参考下列步骤：
   https://developers.weixin.qq.com/doc/oplatform/cn/Third-party_Platforms/2.0/operation/open/create.html
5. 审核需要 1～7 个工作日。
6. 审核通过后，你将获得 AppID 和 AppSecret。

在 RainMaker 中创建提供商

1. 使用 RainMaker API。请参考 "WeChat" 示例，并输入已获得的 AppID 和 AppSecret。
2. 为应用程序创建提供商，并将 provider_type 设为 WeChat。

RainMaker 手机应用配置

确保安卓和 iOS 的重定向 URI 已添加至客户端配置。详情请查看本指南。

安卓

• 在 local.properties 文件中：
  • isChinaRegion=true
  • isMatterSupported=false
• 在 AndroidManifest.xml 文件中：
  • your_app_id=WeChat app id

iOS

请参考 https://github.com/espressif/esp-rainmaker-ios/blob/master/RegionConfig.md。

注意：调用 Token API 时，请添加标志wechat_token_only=true。

信息

如需部署或设置中国区域特定的部署要求，请联系 ESP RainMaker 支持团队，邮箱地址为 esp-rainmaker-support@espressif.com。

---