第三方登录

关于本文

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

全球地域
中国地域

On this page

使用谷歌登录（可选）
使用苹果登录（可选）

使用谷歌登录（可选）

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

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

准备工作

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

配置谷歌应用客户端

配置谷歌开发者账号

使用谷歌开发者账号登陆谷歌 API 控制台，请使用网址
https://console.developers.google.com/。
登录谷歌开发者控制台后，会看到以下窗口。

谷歌开发者控制台

要创建谷歌 API 控制台项目，请点击左上角标题栏旁的 ▼ 图标，如下图所示。
在跳出的窗口中，点击右上角的 NEW PROJECT。

谷歌 API 控制台项目

输入项目名称并点击 CREATE。

谷歌项目创建

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

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

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

谷歌 API 控制台

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

谷歌 OAuth 授权界面

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

谷歌 OAuth 授权界面

在 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。

Create OAuth Client ID

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

授权的 Javascript 源

对比标准 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

Cognito 域名

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

添加授权的重定向 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

:::

Add authorized redirect URI

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

OAuth 客户端对话框

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

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

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

管理面板部署设置

打开 Identity Providers 标签页。

身份提供商

点击 + 图标，添加身份供应商配置。
从 Identity Provider 下拉菜单中选择 Google。
添加前面步骤中提到的 Client ID 和 Client Secret。

身份提供商

将谷歌启用为身份供应商

信息

此功能与 OAuth-only RainMaker 无关。

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

管理面板部署设置

打开 Cognito Configurations 标签页。

Cognito 配置

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

配置回调 URL（重定向 URI）

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

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

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

验证谷歌登录

信息

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

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

Verifying Sign-in with谷歌

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

验证谷歌登陆

前往 App integration > App Client Lists。

验证谷歌登陆

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

验证谷歌登陆

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

Hosted UI

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

托管 UI

点击 Continue with Google。

托管 UI

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

托管 UI

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

托管 UI

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

现在要获取访问令牌，请调用 token API。使用 Token URL 获取 token URL。

    POST <Token URL>

    Headers:
    Content-Type: application/x-www-form-urlencoded

    Body:
    grant_type=authorization_code
    &client_id=<CLIENT_ID>
    &code=<AUTHORIZATION_CODE>
    &redirect_uri=<REDIRECT_URI>

    其中：
    CLIENT_ID：应用客户端的客户端 ID [参见此处](/i18n/zh-Hans/docusaurus-plugin-content-docs/current/deploy/faq-deployment/faq-generic.md#在哪里可以找到第三方集成和手机应用的-client-id-和回调-url)
    REDIRECT_URI：上述获取代码的回调 URL
    AUTHORIZATION_CODE：你在浏览器中获得的代码

你应该在响应中获得访问令牌和刷新令牌。

使用苹果登录（可选）

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

准备工作

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

配置苹果登录

配置苹果开发者账号

若尚未创建苹果应用 ID，请在苹果开发者控制台创建应用 ID。
点击左侧 Keys。
点击 + 图标添加新密钥。

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

在 Sign in with Apple 一栏右侧点击 Configure。
在 Primary App ID 字段选择应用 ID，格式为 "<teamId>.<bundleId>"。其中 Team ID 值和 Bundle ID 值请参见步骤 1。

点击 Save 保存配置。
在 Register a New Key 页面，点击 Continue。
检查更改，并点击 Register 以创建新的密钥。
记下密钥 ID 并下载密钥文件，在 RainMaker 管理面板中配置苹果登录时将会用到这些内容。
点击 Identifiers，然后点击 + 图标。

苹果身份提供商

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

服务 ID

在 Register a Services ID 页面，选择 Sign in with Apple 以启用服务，然后选择 Configure。
在 Identifier 和 Description 字段为服务填写标识符和描述。

服务配置

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

服务配置

重新回到 Identifiers 页面，点击上述步骤中已经注册的服务 ID。
启用 Sign In With Apple，然后点击 Configure。

服务配置

配置域名。

标准 RainMaker 或 OAuth-only RainMaker

标准 RainMaker

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

OAuth-only RainMaker

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

返回 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。

:::

网页 URLs

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

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

管理面板部署设置

打开 Identity Providers 标签页。

身份提供商

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

身份提供商

将苹果启用为身份提供商

注意

此功能与 OAuth-only RainMaker 无关。

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

管理面板部署设置

打开 Cognito Configurations 标签页。

Cognito 配置

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

配置回调 URL（重定向 URIs）

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

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

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

验证苹果登录

注意

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

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

验证谷歌登陆

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

验证谷歌登陆

前往 App integration > App Client Lists。

验证谷歌登陆

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

验证谷歌登陆

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

托管 UI

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

托管 UI

点击 Continue with Apple。
输入你的苹果账号 ID和密码。
点击 Next，你将被重定向到 Cognito 应用客户端中配置好的回调 URL，并且可以在浏览器网址栏中查看验证码。

托管 UI

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

现在要获取访问令牌，请调用 token API。使用 Token URL 获取 token URL。

    POST <Token URL>

    Headers:
    Content-Type: application/x-www-form-urlencoded

    Body:
    grant_type=authorization_code
    &client_id=<CLIENT_ID>
    &code=<AUTHORIZATION_CODE>
    &redirect_uri=<REDIRECT_URI>

    其中：
    CLIENT_ID：应用客户端的客户端 ID [参见此处](/i18n/zh-Hans/docusaurus-plugin-content-docs/current/deploy/faq-deployment/faq-generic.md#在哪里可以找到第三方集成和手机应用的-client-id-和回调-url)
    REDIRECT_URI：上述获取代码的回调 URL
    AUTHORIZATION_CODE：你在浏览器中获得的代码

你应该在响应中获得访问令牌和刷新令牌。

电子邮件转发服务

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

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

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

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

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

私人邮件转发/添加域名

On this page

使用微信登录（可选）

使用微信登录（可选）

准备工作

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

创建开发者账号

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

WeChat Account

在微信中创建客户端

应用客户端

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

WeChat App

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

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

WeChat App

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

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

在 RainMaker 中创建提供商

使用 RainMaker API。请参考 "WeChat" 示例，并输入已获得的 AppID 和 AppSecret。
为应用程序创建提供商，并将 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。

使用谷歌登录（可选）​

准备工作​

配置谷歌应用客户端​

配置谷歌开发者账号​

标准 RainMaker​

OAuth-only RainMaker​

标准 RainMaker​

OAuth-only RainMaker​

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

将谷歌启用为身份供应商​

配置回调 URL（重定向 URI）​

验证谷歌登录​

使用苹果登录（可选）​

准备工作​

配置苹果登录​

配置苹果开发者账号​

标准 RainMaker​

OAuth-only RainMaker​

标准 RainMaker​

OAuth-only RainMaker​

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

将苹果启用为身份提供商​

配置回调 URL（重定向 URIs）​

验证苹果登录​

电子邮件转发服务​

使用微信登录（可选）​

准备工作​

创建开发者账号​

在微信中创建客户端​

应用客户端​

在 RainMaker 中创建提供商​

RainMaker 手机应用配置​

安卓​

iOS​

使用谷歌登录（可选）

准备工作

配置谷歌应用客户端

配置谷歌开发者账号

标准 RainMaker

OAuth-only RainMaker

标准 RainMaker

OAuth-only RainMaker

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

将谷歌启用为身份供应商

配置回调 URL（重定向 URI）

验证谷歌登录

使用苹果登录（可选）

准备工作

配置苹果登录

配置苹果开发者账号

标准 RainMaker

OAuth-only RainMaker

标准 RainMaker

OAuth-only RainMaker

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

将苹果启用为身份提供商

配置回调 URL（重定向 URIs）

验证苹果登录

电子邮件转发服务

使用微信登录（可选）

准备工作

创建开发者账号

在微信中创建客户端

应用客户端

在 RainMaker 中创建提供商

RainMaker 手机应用配置

安卓

iOS