用户池迁移指南

[English Version]

ESP RainMaker 部署了两个 Cognito 用户池——rainmaker-user-pool 和 rainmaker-user-email-mobile-pool。

rainmaker-user-email-mobile-pool 用户池较新，除了支持 rainmaker-user-pool 已支持的功能，还支持基于 OTP 和电话号码的登录方式。Email & Phone User Pool 用户池处于持续更新中，因此建议在配置第三方和语音助手集成时，使用该用户池。Email User Pool 将很快被弃用。

如果你的 RainMaker 已经使用旧的用户池完成了配置，请按照本指南中的步骤迁移到新的用户池。

---

1. 升级

1a. 后端

• 参照这些 步骤 升级 RainMaker 后端。

1b. 前端

• 参照这些 步骤 升级 RainMaker 前端。

---

2. 创建域

• 参照这些 步骤 为你的公司创建新的域。

3. 手动更改第三方控制台

请首先确认当前配置的身份提供商，以判断此步骤是否适用。

• 使用管理员账号登录 RainMaker 管理面板，前往 Deployment Settings。

• 前往 Identity Providers 标签页，切换到旧用户池。

• 记下已启用的身份提供商。你只需针对已启用的身份提供商执行下面的步骤。

3a. 谷歌

谷歌开发者账号配置

• 在 网页 中使用谷歌开发者账号登录 Google API 控制台。

• 登录谷歌开发者控制台后可看到以下界面。

• 在控制台中，单击左侧导航窗格中的 Credentials。

• 界面中会显示 OAuth 2.0 Client ID 列表。

• 选择在 首次配置谷歌登录 时创建的客户端。

• 参照下表添加新 URI：

URI	获取该值的步骤
Authorized JavaScript origins	该值为 <new-company-domain>.auth.<aws-region>.amazoncognito.com，其中 <new-company-domain> 为 步骤 2 中新创建的域。
Authorized redirect URIs	该值为 https://<new-company-domain>.auth.<aws-region>.amazoncognito.com/oauth2/idpresponse，其中 <new-company-domain> 为 步骤 2 中新创建的域。

• 点击 Save 保存更改。

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

• 使用管理员账号登录 RainMaker 管理面板，前往 Deployment Settings。

• 打开 Identity Providers 选项卡，切换到旧的用户池并记下其参数值。

• 参照这些 步骤 为新用户池添加谷歌身份提供商，需用到之前记下的旧用户池参数值。

3b. 苹果

苹果开发者账号配置

• 在 网页 中使用苹果开发者账号登录苹果开发者控制台。

• 打开 Identifiers 并选择 Service IDs。

• 点击先前配置好的应用程序服务标识符。

• 点击 Configure。

• 点击网站 URL 旁边的 + 图标。

• 参照下表添加新 URI：

URL	获取该值的步骤
Domains and Subdomains	该值为 <new-company-domain>.auth.<aws-region>.amazoncognito.com，其中 <new-company-domain> 为 步骤 2 中新创建的域。
Return URLs	该值为 https://<new-company-domain>.auth.<aws-region>.amazoncognito.com/oauth2/idpresponse，其中 <new-company-domain> 为 步骤 2 中新创建的域。

• 点击 Next 和 Done。

• 点击 Continue。

• 点击 Save。

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

• 使用管理员账号登录 RainMaker 管理面板，前往 Deployment Settings。

• 打开 Identity Providers 选项卡，切换到旧的用户池并记下其参数值。

• 参照这些 步骤 为新用户池添加苹果身份提供商，需用到之前记下的旧用户池参数值。 （注意：你需要从苹果开发者控制台下载密钥文件。）

---

• 在 RainMaker 管理面板上，打开 Deployment Settings > Cognito Configurations。

• 检查启用的身份提供商和回调 URL 是否正确，可参考 安卓 URI 和 iOS URI。

---

4. Cognito 应用客户端配置

• 使用管理员账号登录 RainMaker 管理面板，前往 Deployment Settings。

• 打开 Cognito Configurations 标签页，切换到旧的用户池并记下 Enabled Identity Providers 和 Callback URLs 两个参数值。

• 打开 Email & Phone User Pool 标签页，将上述值复制到新用户池的相应参数中。

• 配置完成。

---

5. 电子邮件模板配置

• 使用管理员账号登录 RainMaker 管理面板，前往 Deployment Settings。

• 打开 Email Configurations 标签页，切换到旧的用户池并记下相关参数值。

• 按照这些 步骤 为新的用户池配置电子邮件模板，需用到刚才记下的参数值。

---

6. Skill 升级

• 前往 AWS 管理面板，搜索 "Serverless Application Repository" 或 "SAR" 打开 SAR 页面。

• 打开 Private applications 并勾选复选框——Show apps that create custom IAM roles or resource policies。

• 搜索并打开 ESP-RainMaker-3p-CognitoClients。

• 在新的浏览器页中，打开 Cloudformation 服务，确保区域为 us-east-1。

• 点击 View Nested 切换键开启该功能。

• 搜索堆栈名称 "serverlessrepo-ESP-RainMaker-3p-CognitoClients"。

• 打开 Cloudformation 堆栈的 Parameters 标签页。

• 返回 SAR 服务页面，查看需要填写的参数值。

• 查看所有 Cloudformation 参数的值，并将相应值复制到 SAR 服务页面的参数中。

• 参照下表为参数添加值：

参数	获取该值的步骤
SkillIdentityProvidersNewUserPool	- 登录 RainMaker 管理面板。 - 点击左侧导航栏中的 Deployment Settings。 -点击 Identity Providers 标签页。 - 记下 Identity Providers 参数值。 - 如果配置了谷歌、GitHub 或苹果登录，那么在部署 ESP-RainMaker-3p-CognitoClients SAR 应用程序时，SkillIdentityProvidersNewUserPool 的值应为 Google, GitHub, SignInWithApple, COGNITO。注意：如果未配置身份供应商，则默认值为 COGNITO。 - 输入上一步中记下的要配置的身份供应商。

• 点击 Deploy。

---

7. 在 Skill 控制台手动更改配置及重新认证

7a. Alexa

• 登录 Alexa 开发者控制台。

• 选择之前选择的 Skill。

• 点击左侧导航栏中的 Account Linking。

• 参照下表编辑相应参数值：

参数	获取该值的步骤
Your Web Authorization URI	该值为 https://<new-company-domain>.auth.<aws-region>.amazoncognito.com/oauth2/authorize，其中 <new-company-domain> 为 步骤 2 中新创建的域。
Access Token URI	该值为 https://<new-company-domain>.auth.<aws-region>.amazoncognito.com/oauth2/token，其中 <new-company-domain> 为 步骤 2 中新创建的域。
Your Client ID 和 Your Secret	参照这些 步骤 获取 esp-rainmaker-alexa-skill Alexa 客户端的相关值。

• 参照这些 步骤 为 Skill 重新获取证书。

7b. 谷歌语音助手

• 登录 Google Actions 控制台。

• 打开相应 Action 的 Develop 标签页。

• 打开 Account linking。

• 参照下表编辑相应参数值：

参数	获取该值的步骤
Client ID 和 Client secret	参照这些 步骤 获取 esp-rainmaker-google-action 客户端的详细参数值
Authorization URL	该值为 https://<new-company-domain>.auth.<aws-region>.amazoncognito.com/oauth2/authorize，其中 <new-company-domain> 为 步骤 2 中新创建的域。
Token URL	如果已经在 Skill 中使用了新的用户池，请使用： https://<new-company-domain>.auth.<aws-region>.amazoncognito.com/oauth2/token，其中 <new-company-domain> 为 步骤 2 中新创建的域。 否则，请使用旧的用户池： 在新的浏览器页面中，登录 RainMaker 管理面板。 打开 Deployment Settings 标签页。 打开 Deployment Settings 并复制 API Path URI 的参数值。 将 Token URI 编辑为 <api_path_uri>/custom_token，其中 <api_path_uri> 是在上一步中复制的 URL。

• 此后：
  1. 向 OAuth 页面添加图标
  2. 重新测试 Action
  3. 填写认证请求表格以重新认证 Action

---

8. 移动应用配置

8a. 安卓

• 在 Android Studio 中打开 RainMaker 项目（拉取并合并最新的源代码——https://github.com/espressif/esp-rainmaker-android）

• 在 local.properties 文件中，编辑以下字段的值。

配置字段	类型	获取该值的步骤
authUrl	字符串	OAuth URL。该值为 https://<new-company-domain>.auth.<aws_region>.amazoncognito.com/oauth2，其中 <new-company-domain> 为 步骤 2 中新创建的域。
clientId	字符串	在用户池中标识一个特定的应用程序。请参考 获取客户端 ID 的步骤。
alexaRMClientId (*如已设置 Alexa)	字符串	参考 获取客户端 ID 的步骤，获取 esp-rainmaker-alexa-skill 的客户端 ID。

• 完成后，在 Play Store 中重新发布应用程序。

8b. iOS

• 在 Xcode 中打开 RainMaker 项目（拉取并合并最新的源代码——https://github.com/espressif/esp-rainmaker-ios）

• 在 Configuration.plist 文件中，编辑以下字段的值。

字段	类型	获取该值的步骤
App Client ID	字符串	在用户池中标识一个特定的应用程序。请参考 获取客户端 ID 的步骤。
Authentication URL	字符串	OAuth URL。该值为 https://<new-company-domain>.auth.<aws_region>.amazoncognito.com/oauth2，其中 <new-company-domain> 为 步骤 2 中新创建的域。
Alexa RM Client Id (*如已设置 Alexa)	字符串	参考 获取客户端 ID 的步骤，获取 esp-rainmaker-alexa-skill 的客户端 ID。

• 完成后，在 App Store 上重新发布应用程序。

---

迁移到新用户池的影响

如果用户已经使用旧版本的应用完成了 App to App 账号关联功能配置，那么只要用户更新其应用程序，Alexa Skill 将无缝迁移到新用户池。

但是，如果用户尚未更新其应用程序，仍在使用针对旧用户池配置的旧版本，那么 App to App 账号关联功能配置可能会失败。如遇到此问题，请首先将应用程序更新到最新版本。

已关联的账号将维持关联状态。

建议提醒所有用户及时更新应用程序，以避免上述问题。