跳到主要内容
ESP RainMaker Classic 文档

部署设置

警告

以下内容适用于中国部署。
位于中国地域 (cn-north-1) 的 RainMaker 默认仅支持 OAuth 方式部署。
本节提到的“仅限 OAuth 部署”与第三方登录设置无关。

此配置不适用于现有客户。此操作无法撤销，操作前需仔细阅读功能限制。

OAuth-only 部署​

在整个部署范围内，有一些设置可以根据你的需求进行配置。Rainmaker 提供了一种基于标准 OAuth 2.0 协议的身份管理替代方案，该方式仅支持社交账号登录，且使用 Amazon Cognito 的 Identity 身份池，而非用户池。这对客户端的配置产生较大影响。除以下功能限制外，RainMaker 的大部分功能均受支持。

功能限制​

  1. 手机应用的注册与登录体验： 原本在原生 App 里输入用户名和密码进行登录的方式，将被替换为弹出重定向 URL，跳转到浏览器完成登录。如果使用标准社交身份提供商，则不会带来变化，因为这些登录本就需要通过浏览器完成。依赖用户名和密码的用户则会受到影响。
  2. 如果需要通过语音助手绑定账号，只能使用单一身份提供商。
  3. 无法基于邮箱或手机号创建用户账号，因此，注册与密码相关操作均被禁用。（不过仍然可以通过任意 AWS 账号下的 Amazon Cognito，或其他支持邮箱/手机号用户的标准 OIDC 身份提供商来支持这类用户。）
  4. 管理员用户管理： 不支持多重要素验证 (MFA)，也不支持标准 API 和云对云 API。
  5. REST API 网关不可用（默认使用 HTTP API 网关），详情请参阅 RainMaker API 地址（基础 URL）。因此，API 限流也不可用。
  6. 无法针对某个应用客户端单独启用或禁用身份提供商（目前全部启用）。
  7. 暂不支持 ESP Insights。
  8. 超级管理员用户的邮箱地址无法修改。(Swagger)

OAuth 限制​

  1. 尚未实现隐式授权和密码授权这两种安全性较低的授权方式
  2. 尚未实现客户端凭证授权
  3. 尚未实现设备码授权
  4. 尚未实现 PKCE
  5. 作用域受到限制，目前仅支持 OpenID
  6. 尚未实现令牌撤销
  7. 尚未实现 client_secret_jwt 和 private_key_jwt 这两种客户端身份验证方法
  8. 尚未实现状态管理

如果需要支持上述受限制的功能，请联系 RainMaker 支持团队。(esp-rainmaker-support@espressif.com)

启用步骤​

  1. 登录：通过 API 进行登录，请使用部署详情邮件中发送给超级管理员的 HTTP Base URL。登录后，你将收到一个访问令牌，后续调用任何 API，都需要在 Authorization 头部包含此令牌。

    请注意，如果在此之前更改过密码，那么在启用 oauth_only 设置后，你需要再次选择 Forgot Password 并设置新密码。

  2. 启用设置：调用部署设置 API，将 oauth_only 设置为 true。

  3. 现在就可以像标准的 OAuth 2.0 一样，添加兼容 OIDC 的身份提供商（如 Google、Apple 或 Amazon Cognito）。

    如何判断身份提供商是否兼容 OIDC？
    该身份提供商应提供包含 .well-known/openid-configuration 的服务发现 URL，例如：

重要提示

在使用 RainMaker 前，你的身份提供商用户需关联电子邮件或电话号码。这些信息应包含在 JWT ID 令牌中，对应字段为 email 或 phone_number。

  1. 在你选择的身份提供商平台上创建一个 OAuth 客户端。

    添加回调 URL 或重定向 URL：{HTTP API Endpoint}/cognitocallback

    其中：

    重要提示：RainMaker 用户需要使用电子邮件或电话号码，请确保在配置时允许访问这些信息。

    示例：如要将 Cognito 作为身份提供商，请参考步骤。如果使用 Cognito，请确保作用域包含 aws.cognito.signin.user.admin，以支持默认的密码更改功能。

    创建 OAuth 客户端后，你会从身份提供商的管理控制台中获得一个客户端 ID（即 App ID）和一个密钥。

  2. 将身份提供商添加到 RainMaker。

    Apple 和 Google 内置支持，可直接添加：

    对于其他提供商，请使用 API 进行配置。请参考示例 OIDC 身份提供商（仅限 OAuth 部署）。

    其中：

    • client_id 和 client_secret 来自步骤 4。
    • oidc_url 为 OIDC 发行者 URL。在此 URL 后添加 .well-known/openid-configuration，可以获取 OIDC 的元数据。详情请参考相关文档。

验证 OAuth 登录​

  1. 打开浏览器。
  2. 粘贴授权 API。客户端 ID 和重定向 URL 可从管理面板中获取。identity_provider 应选择配置好的身份提供商名称。
  3. 在弹出的身份提供商登录界面中进行登录。
  4. 登录成功后，浏览器的重定向 URL 中会显示一个授权码。如有必要，可使用开发者工具检查网页。
  5. 调用 Token API，使用 authorization_code 作为 grant_type，传入授权码及其他参数。
  6. 成功返回令牌。

资源所有者密码凭证 (ROPC) 授权​

  1. 调用 Token API 时需包含以下参数：grant_type(password)、username、password、client_id、client_secret 和 identity_provider（配置好的身份提供商名称）。
  2. 成功返回令牌。

手机应用配置​

  1. tokenUrl: {HTTP Base URL}/{Stage}/token (Swagger)。
  2. 参考此步骤，确保 Android 和 iOS 应用的重定向 URI 已添加至客户端配置。

更多信息，请联系 ESP RainMaker 支持团队，邮箱地址为 esp-rainmaker-support@espressif.com。

On this page