身份源管理

身份源说明

身份源用于集成已有的账号体系，被集成的账号体系内的用户可以访问魔笔搭建的应用。

每个身份源会配置一个默认权限组，通过该身份源登录时会自动将用户映射到默认权限组。

身份源界面

身份源列表

在身份源页中，开发者可以查看当前空间的所有身份源及其详细信息，包括：

• 身份源名称

• 类型

• 状态

• 默认权限组

• 回调地址

• 描述

这些信息帮助开发者了解当前空间的身份源信息。特别地，在创建身份源后，会自动生成回调地址信息，该回调地址在第一次创建身份源后保持不变，不支持修改。开发者可以使用该回调地址配置自己的 OIDC 服务器的回调地址。

身份源操作

魔笔支持对自定义的 OIDC 身份源和 JWT 身份源进行启用、停用、编辑和删除操作。在身份源页的列表中，开发者可以在每一项身份源的操作选项中选择希望进行的操作。

• 启用和停用操作对应调整该身份源的状态，以控制是否使用该身份源。

• 编辑操作将对身份源的配置信息进行修改。

• 删除操作将删除选定的身份源。

为魔笔应用配置平台登录方式

在完成身份源配置后，您可以前往魔笔应用编辑器中，在左下角点击“应用设置”按钮，在“登录配置 -> 平台登录配置”中，为特定平台或环境选择身份源作为该应用的默认登录方式：

默认身份源

魔笔平台目前内置了两种身份源：阿里云账号登录（关联默认权限组 END_USER ）、测试账号登录（关联默认权限组 TEST_USER ）。默认身份源无法进行操作（创建、编辑、停用和删除）。

• 阿里云账号登录：通过阿里云的 RAM 账号登录，有关 RAM 登录的相关信息，可以参考什么是访问控制。

• 测试账号登录：登录界面选择测试账号后使用测试账号和密码登录。

OIDC/JWT 身份源

OIDC 身份源介绍

魔笔平台目前支持添加一个 OIDC 身份源。添加 OIDC 身份源后，在访问魔笔搭建的应用时会增加对应的 OIDC 身份源的登录选项。有关 OIDC 协议内容，可以参考OIDC 协议。

JWT 身份源介绍

魔笔平台为用户提供基于阿里云 OpenAPI 接口的 JWT 身份源认证方式，开发者可以通过调用魔笔平台的 OpenAPI 完成用户登录及相应的 Token 颁发过程。 JWT 身份源适用于被集成场景（宿主应用已经有登录态，并且希望通过 API 调用同步登录态到魔笔应用）。

Native 宿主应用通过魔笔 SDK 集成的方案可参考 Android SDK 集成 和 iOS SDK 集成。Web 平台宿主应用可通过使用名为 auth_code 的 URL 参数来向 iFrame 注入 JWT Token。此外，Web 平台宿主集成支持 JWT Token 自动保活，您可通过使用名为 refresh_token 和 expires_in 的 URL 参数来向 iFrame 注入令牌刷新凭证和刷新周期。auth_code、 refresh_token 和 expires_in 的具体内容您可以通过GenerateJWTUserToken - 生成 JWT 身份源 Token 接口获取。

JWT 身份认证流程

开发者可以通过魔笔 GenerateJWTUserToken - 生成 JWT 身份源 Token 接口完成 JWT 身份源认证，认证流程如下所示。

在认证过程中，魔笔会根据调用 OpenAPI 接口的阿里云 ID 校验对应的空间权限，校验通过后会进行 JWT 身份源校验。为了正确完成 JWT 身份源认证，开发者需要在魔笔平台正确配置 JWT 身份源信息并启用。

维持 Token 有效性

魔笔为开发者提供了 GenerateJWTUserToken - 生成 JWT 身份源 Token 和 RefreshJWTUserToken - 刷新 JWT 身份源 Token 两个 OpenAPI，分别用于生成访问魔笔服务的 Token 和刷新 Token。开发者在集成过程中，需要定时调用刷新 Token 接口完成刷新，避免 Token 失效。

配置方式

在身份源页，开发者可以添加一个 OIDC 身份源和一个 JWT 身份源。添加后可以对身份源进行启用、停用、编辑和删除操作。新增身份源并进行配置的流程如下：

1. 基础配置：点击添加身份源后，会显示新增身份源的弹窗，在基础配置中需要完成别名、显示名、类型和描述的配置，并选择启用状态。

2. OIDC 配置：如果选择的类型是 OIDC 身份源，那么在点击下一步后，会进行 OIDC 配置，开发者需要根据 OIDC 协议填写这些参数，如果选择的类型是 JWT 身份源，则跳过这一步。

3. 权限映射：如果选择的类型是 OIDC 身份源，在这一步中需要进行属性映射的配置和权限组的配置。此外，在权限组的配置中可以选择增加权限映射的规则。如果选择的类型是 JWT 身份源，则只能配置默认权限组。

钉钉身份源

在身份源页，开发者可以添加一个钉钉身份源。

首先，用户需要根据钉钉三方登录文档前往钉钉开发者平台进行应用创建和必要的配置（完成“步骤一：创建并配置应用”及“步骤二：添加接口权限”即可）。

如果您需要开启钉钉免登功能，需要开启qyapi_get_member权限：

随后在“安全设置”中，将https://accounts.mobiapp.cloud/填写进入“重定向URL（回调域名）”输入框中：

在“服务器出口 IP ”处，需要将您访问此应用的出口 IP 地址填入，否则会产生 IP 地址被拦截的问题。

随后在“凭证与基础信息”菜单项中，可以获取 Client ID、Client Secret、Agent ID和Corp ID 值。

得到上述四个值之后，返回魔笔平台，点击添加身份源：

在类型中选中“钉钉”选项卡。填写必要信息后进入下一步：

将钉钉开发者平台中获取的凭证值填写入上述输入框中，点击下一步：

选择权限组后，点击“确认”，即完成钉钉身份源的添加。

如果您需要开启钉钉免登，您需要返回至应用编辑器中，在应用设置处，将钉钉身份源的免登按钮置于开启状态：

如果您需要从钉钉端内的企业工作台进入魔笔应用，您可以将应用首页填写进入应用首页地址中：

企业微信身份源

在身份源页，开发者可以添加一个企业微信身份源。

首先，前往企业微信开发者平台：

点击上方菜单栏中的“应用管理”，随后在“自建”栏目中选择“创建应用”。填写表单后，进入应用详情页。

在“我的企业”选项卡中获取 Client ID :

回到应用页面，在应用详情中获取 Client Secret 与 Agent ID :

随后在下方“开发者接口”栏目中进行授权。

首先点击“企业微信授权登录”：

在“授权回调域”中填写域名为accounts.mobiapp.cloud。

随后返回，点击“网页授权与SDK”：

将自定义域名填写进入“可信域名”中。然后点击上图中的“下载文件”，将文件名和文件内容保存，随后回到魔笔平台：

在新增身份源表单中，选择“企业微信”选项卡，填写必要信息后点击下一步：

在这个表单中填写在企业微信开发者平台中获取的信息，点击下一步：

配置权限组信息后，即可完成企业微信身份源的添加。

随后回到企业微信控制台，在“设置可信域名”中点击“确定”，下方提示“已验证”，即可配置成功。

随后在“企业可信IP”中，需要配置魔笔鉴权请求服务器IP101.200.211.106，否则无法完成登录流程。

SAML2.0 身份源

在身份源列表页中，开发者可以点击新增身份源按钮唤起身份源新增配置页面，并通过此页面创建 SAML 2.0 身份源。

基础配置

基础配置面板中，开发者可以配置 saml 2.0身份源的别名（空间内唯一标识）、显示名（登录页显示名称）、描述和启用状态。

高级配置

在高级配置面板中，开发者可以选择 SAML IDP （身份提供商）提供的 Metadata 数据导入到魔笔，从 Metadata 中可以提取到 IDP 的 Entity Id（ IDP 唯一标识）、Signing Certificate（签名证书）、Single Sign On Service Url（单点登录 URL）、Single Logout Service Url（单点登出 URL）。

除了上述基础信息外，开发者还可以指定 SAML 2.0协议中的其它配置：

• Post Binding Authn Request/Post Binding Response/Post Binding Logout

在 SAML 2.0 协议中，SP 与 IdP 之间的通信方式分为 HTTP Redirect Binding、HTTP POST Binding、HTTP Artifact Binding（不常用，暂不支持）。每种方式在不同的阶段会用不同类型的 HTTP 与对方通信。如果勾选 Post Binding 选项，魔笔将使用 HTTP POST Binding 方式与 IDP 进行通信，否则使用 HTTP Redirect Binding 方式与 IDP 进行通信。

• Allow Create

当此选项设置为 true 时，表示服务提供者（SP）允许身份提供者（IDP）为用户生成一个新的 Name ID。这意味着 IDP 可以创建一个新的唯一标识符来标识用户，即使该用户在 IdP 中已经有现成的标识符。注意，要使用此参数，Name ID Format 必须设置为 PERSISTENT 。

• Force Authn

在 SAML 2.0 协议中，ForceAuthn 用于指示身份提供者（IDP）是否需要强制用户进行重新认证，即使用户已经在 IDP 上有有效的会话。此属性在魔笔中默认关闭。

• Validate Signature

此选项用于控制是否验证来自身份提供商（IDP）SAML 断言的数字签名。当这个选项设置为 true 时，魔笔会验证从 IDP 发送过来的 SAML 断言的数字签名。如果签名验证失败，魔笔会拒绝该断言。

• Name ID Policy Format

NameID Policy Format 定义了 SAML 断言中 NameID 的格式。SAML 2.0 规范定义了几种标准的 NameID 格式，每种格式适用于不同的场景。Keycloak 支持以下几种常见的 NameID 格式：

TRANSIENT

生成一个临时的、不可重复的标识符。适用于不需要持久性标识符的场景，例如单次会话或匿名访问。

PERSISTENT

生成一个持久的、可重复使用的标识符。适用于需要持久性标识符的场景，例如用户跨多个会话的唯一标识。

EMAIL_ADDRESS

使用用户的电子邮件地址作为 NameID。适用于需要使用电子邮件地址作为标识符的场景。

UNSPECIFIED

不指定具体的 NameID格式，由 IDP 自行决定。适用于对 NameID格式没有特定要求的场景。

• Principal Type

Principal Type 定义了如何确定用户的身份。魔笔提供了几种不同的 Principal Type 选项：

SUBJECT

使用用户的用户名作为 NameID。

ATTRIBUTE

使用用户属性中的值作为 NameID，属性名称由 Principal Type指定。

FRIENDLY_ATTRIBUTE

使用用户属性中的值作为 NameID，属性 friendly 名称由 Principal Type指定。

• Principal Attribute

它指定了用户属性或 friendly 属性的名称，该属性的值将被用作 NameID。

权限映射

基础属性映射

在基础属性映射配置中，开发者可以将 SAML 断言中的用户属性映射到魔笔用户属性中。在属性映射过程中，魔笔支持 Attribute Name和 Friendly Name两种映射方式，优先使用 Attribute Name配置的内容。

Name Format 三种形式

ATTRIBUTE_FORMAT_BASIC

这是最简单的属性名称格式，直接使用属性的名称字符串。如果你有一个属性名为 email，那么它的名称格式就是 email。

ATTRIBUTE_FORMAT_URI

使用统一资源标识符（URI）来表示属性名称。这种格式通常用于需要明确命名空间或特定 URI 的属性。如果你有一个属性名为 email，那么它的格式有可能是 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email。

ATTRIBUTE_FORMAT_UNSPECIFIED

不指定具体的属性名称格式，由发送方自行决定。如果你不确定或不需要特定的格式，可以选择这种类型。

权限组映射

SAML 2.0 身份源支持设置默认权限组，同时可以根据 SAML 断言中的属性映射到魔笔的权限组中。

OAuth 2.0 身份源

您可以通过魔笔身份源系统接入您的 OAuth 2.0 身份源。首先，添加一个身份源，在“类型”中，选择“OAuth 2.0”类型：

随后，您可以填写 OAuth 2.0 的配置信息：

字段解释如下：

• Client Id是您的 OAuth 2.0 系统为魔笔身份源分配的客户端 ID。

• Client Secret是您的 OAuth 2.0 系统为魔笔身份源分配的客户端密钥。

• Authorization Url是您的 OAuth 2.0 系统的鉴权 URL 路径。

• Token Url是您的 OAuth 2.0 系统的令牌 URL 路径。

• Response Type是魔笔请求您的 OAuth 2.0 系统的鉴权 URL 请求参数response_type，默认为code。

• Scope是魔笔请求您的 OAuth 2.0 系统的鉴权 URL 请求参数scope，默认为空，选填。

• Grant Type是魔笔请求您的 OAuth 2.0 系统的令牌 URL 请求参数grant_type，默认为authorization_code。

• User Info Url是您的 OAuth 2.0 系统的用户信息 URL 路径。

• User Info Method是魔笔请求您的 OAuth 2.0 系统的用户信息 URL 路径的方式，可选项为GET、POST。

• Username Json Path是用于定位您的 OAuth 2.0 系统的用户信息 URL 返回值中用户名信息的 JSON Path 语句。

• User Id Json Path是用于定位您的 OAuth 2.0 系统的用户信息 URL 返回值中用户 ID 信息的 JSON Path 语句。

• User Email Json Path是用于定位您的 OAuth 2.0 系统的用户信息 URL 返回值中用户电子邮箱地址信息的 JSON Path 语句，选填。

填写完成后，点击下一步，可以为该身份源的用户指定默认的权限组：

最后，点击“确认”即可完成 OAuth 2.0 身份源的添加。

微信身份源

在身份源页，开发者可以添加一个微信身份源。借助微信身份源，终端用户可以使用微信账号体系登录魔笔运行时应用。在魔笔身份源中，我们同时支持微信公众平台和微信开放平台两种不同登录场景体系的登录业务构建：

  /**
   * 生命周期函数--监听页面初次渲染完成
   */
  onReady() {
    // 获取微信小程序 authCode
    wx.login({
      success: (res) => {
        // 获取微信小程序用户信息
        wx.getUserInfo({
          success: (info) => {
            // 生产环境 / 开发环境魔笔应用定制
            const baseUrl = 'https://{{你的生产环境域名}}/xxxxxxxxx/apps/xxxxxxxxxx/';

            this.setData({
              // webViewSrc 和 webView 显示受控
              webViewSrc: `${baseUrl}?iv=${encodeURIComponent(info.iv)}&encryptedData=${encodeURIComponent(info.encryptedData)}&auth_code=${res.code}`,
              showWebView: true,
            })
          }
        })
      },
      fail: (err) => {
        console.log(err)
      }
    })
  }