跳到主要内容
Documentation Hub

部署设置

警告

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

OAuth-only 部署​

某些部署级别的设置可以根据不同的需求进行配置。Rainmaker 提供了一种基于标准 OAuth 2.0 协议的身份管理替代方案，仅允许社交登录，且使用 Amazon Cognito 身份池，而非用户池登陆，对客户端的配置产生较大影响。除以下功能限制外，RainMaker 的大部分功能均受支持。

功能限制：​

  1. Phone app Sign up and Login experience: The native app experience of logging in with username and password will be replaced with a pop-up URL redirected to browser. This will be fine if you plan to use standard social identity providers as they always require browser. However, username password based users will be impacted.
  2. Mutiple Identity providers are not supported for Voice assistant account linking.
  3. Email and phone number based users cannot be directly created. Hence, Signup, password operations are disabled. (You can however use Amazon Cognito from any AWS account or any other standard OIDC provider which support such users.)
  4. Admin user management: MFA is unsupported. Also, standard APIs and Cloud to Cloud based APIs aren't supported.
  5. REST API gateway is unavailable (HTTP API gateway is the default). For more details refer to RainMaker API URL (Base URL). As a result, API rate limiting is also unavailable.
  6. Enabling or disabling identity providers per app client (Right now all are enabled) is not customisable.
  7. ESP Insights is unsupported for now.
  8. Superadmin user email cannot be updated. (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