docs-web-logo
使用指南

配置Microsoft Entra ID数据源

Microsoft Entra ID（原AAD，以下简称：AAD）是微软推出的云端身份与访问管理核心服务，整合了原Azure Active Directory功能。它提供多重身份验证（MFA）、无密码登录、单点登录（SSO）及条件访问策略，可统一管理云/本地应用权限，覆盖员工、客户及合作伙伴的访问需求。在 One ID 中配置并开启 Microsoft Entra ID 数据源，即可实现通过 One ID 快速获取 AAD 基本开放的用户信息功能。

本文档将指导您如何配置AAD数据源，完成配置之后，通过自动同步与手动同步您可以将AAD用户数据同步至本系统的组织架构中。

第一步：Microsoft Entra ID侧应用创建及配置

1. 应用注册

1）登录微软Entra ID Global（全球版）或微软Entra ID 世纪互联（21Vianet，中国版）。在「管理Microsoft Entra ID」处点击「查看」。 img

2）在管理目录中找到「应用注册」。 img

3）进入「应用注册」中点击「新注册」。注意：如果已经有注册完成的应用，此步骤可省略 img

4）填写应用名称，选择账号类型为：单一组织，进行注册。 img

5）注册完成，返回「应用注册」列表页，选择刚才创建的应用。 img

2. 查看应用相关ID信息

进入应用详情页面，查看「应用程序(客户端) ID」和「目录(租户) ID」。注意：请记录这两个数据，便于后续配置数据源使用。 img

3. 配置应用密钥或证书

1）进入应用详情页面中，查看「管理-证书和密码」。 img

2）进入「证书和密码」页。证书和密码配置是连通AAD的关键，为此AAD提供多种配置方式。具体如下：

----密钥配置方式----

在「证书和密码」页，选择「客户端密码」，点击「新客户端密码」 img

填写客户端密码说明，新建「新客户端密码」 img

选择新建的客户端密码，在「值」一列中点击复制图标。注意：复制的内容是AAD提供的用于连通鉴权使用的私钥，AAD出于安全设计复制后会进行脱敏并无法再次复制。所以复制后请妥善保存； img

----证书配置方式----

注意：此方式需要上传证书，证书既可以腾讯统一身份提供（具体可见第二步：创建Microsoft Entra ID数据源），也可以是第三方CA机构颁发。

在「证书和密码」页，选择「证书」，点击「上传证书」 img 把证书进行上传。再次说明：如果是没有第三方CA机构统一提供证书情况下，可以使用OneID中Microsoft Entra ID数据源提供的自建证书，可以等创建Microsoft Entra ID数据源完成后在进行此处配置。

4. 配置应用API接口权限

1）进入应用详情页面中，查看「管理-API权限」。选择「添加权限」。 img

2）在请求获取API权限，点击「Microsoft Garph」。 img

3）然后选择「应用程序权限」。 img

4）在下方搜索框中分别搜索并添加以下权限：

-----必选------

同步用户数据：User.Read.All（读取所有用户）；

同步组数据：Group.Read.All（读取所有组）；

同步组成员关系：GroupMember.Read.All（读取所有组的成员）；

-----可选-----

若需写入数据（如同步反向写入AAD）：需添加写入权限（如User.ReadWrite.All、Group.ReadWrite.All） img

5）选择后权限可能呈现状态是「未为....授权」，需要点击「代表.....授予管理员同意」。 img

6）最终权限状态是「已为....授权」。 img

第二步：配置Microsoft Entra ID数据源

1. 创建Microsoft Entra ID数据源

登录One ID管理后台，在导航栏通讯录模块点击「数据源」，在数据源选择页面中，选择「Microsoft Entra ID」数据源。

img

2. 配置Microsoft Entra ID凭证信息

1）进入AAD应用凭证配置页面，选择AAD部署环境（取决于您购买AAD的版本）。填写相关配置信息，在配置项中依次填写：Application (client) ID【应用程序(客户端) ID】、Directory (tenant) ID【目录(租户) ID】； img

2）凭证配置方面主要有三种方式：客户端密钥、自建证书以及第三方证书。

----客户端密钥配置方式----

凭证配置选择「客户端密钥」时，此时需要填写第一步骤复制的AAD侧「客户端密码」方式。 img

----自建证书配置方式----

凭证配置选择「自建证书」时，需要下载自建证书，并将证书配置到AAD创建的应用「管理-证书和密码」中证书选项中。具体位置可参考第一步中：配置应用密钥或证书

注意：自建证书需在数据源配置完成保存时才会生效，未在数据源配置最后一步中点击「保存」，证书虽然可以下载但并不会生效。 img

----第三方证书配置方式----

凭证配置选择「第三方证书」时，需要将第三方CA颁发的证书和私钥文件进行上传。注意：第三方证书文件中需要包含证书和私钥。文件中包含需要鉴权的证书即可，无需上传证书链上其他证书。 img

**【不推荐】**如果没有现成的ca证书和合作的CA机构，又希望使用第三方证书。您也可以自行生成自签名证书，生成方式如下：

生成 2048 位 RSA 私钥（不加密）和自签名证书（有效期 365 天）

  1openssl req -x509 -newkey rsa:2048 -nodes -keyout private.key -out cert.pem -days 365

合并 私钥 和 证书

  1cat private.key cert.pem > private_and_cert.pem

img

选择“第三方证书”形式凭证，上传private_and_cert.pem。注意：“第三方证书”上传的文件，秘钥不能使用加密模式，如以下文件不支持 img

3）凭证信息填写完毕，点击「下一步」进入字段映射配置。注意：如果您选择「客户端密钥」方式，点击「下一步」时会校验和AAD连通性。如果选择「自建证书」或「第三方证书」时，考虑到还需AAD侧同步进行配置证书，为了不阻塞您后续配置，此时不会校验AAD联通性。后续可在配置完成页面手动进行连通性校验。

3. 配置Microsoft Entra ID数据源同步范围及字段映射信息

1）进入字段映射配置页面；首先「获取数据范围」，AAD提供按用户组数据选择同步范围。

----获取全部用户组数据----

选择全部用户组数据时，OneID将会把AAD中全部用户同步至OneID中。另外选择全部数据时AAD提供全量同步和增量同步两种方式。具体可见下一步骤：设置同步策略。 img

----获取部分用户组数据----

选择部分用户组数据时，OneID仅同步您指定用户组下用户至OneID中。选择部分用户组时，仅提供全量同步，不支持增量同步两种方式。具体可见下一步骤：设置同步策略。注意：获取用户列表前提是已经通过和AAD的连通性校验，当您在凭证信息中选择「自建证书」或「第三方证书」时，可能会由于AAD侧未配置证书，导致连通失败，此时会显示：获取用户组失败.....。您可先暂时先选择「获取全部用户组」，待AAD侧配置证书后，再次修改同步范围。 img img 另外，AAD用户组提供嵌套能力，你可以通过是否勾选「同步子用户组的用户数据」，来配置同步当前用户组直属用户数据还是同步用户组直属和子组用户数据。

2）配置AAD成员映射；字段映射可以将AAD中人员的字段信息和腾讯统一身份中人员的字段信息对应起来，在同步时会按照这种对应关系进行数据写入，对该配置项的具体说明可以参考文档字段映射。系统预置了常见的AAD的字段映射，如有调整，可以根据具体使用情况进行字段映射调整。 img

3）配置新建用户归属主部门。由于AAD中没有部门树概念，OneID在同步AAD用户时，需要帮AAD的用户默认选择一个部门。注意：如选择的部门后续在管理过程中被删除，请及时在数据源处更改默认部门，如未指定，用户将默认归属到根部门下。 img

3. 配置Microsoft Entra ID同步策略

1）配置同步策略。自动同步可以让同步任务定时触发，以保证AAD中的组织架构的变更能周期性地同步到腾讯统一身份中，对该配置项的具体说明可以参考文档同步方式。

AAD的自动同步支持全量同步和增量同步。自动同步可以通过设置触发时间和触发间隔来制定自动同步规则。 注意：当您在「获取数据范围」处选择「部分用户组」时，仅支持全量同步，不支持增量同步。全量同步在较大数据量时会同步周期时间较长。所以建议管理员根据业务需求组合设计同步规则。如同时设置了自动增量同步和自动全量同步，同步触发时间尽量错开，如果触发时间冲突，则会自动忽略后一次触发任务。

自动增量同步 img

自动全量同步 img

2）配置删除保护。

此处为了防止您误删除操作，我们设置了删除保护条件，系统执行同步任务之前将识别本次操作是否会触发保护条件，若满足保护条件，则本次同步任务将不会进行，我们会给您留下的联系方式发送通知，删除保护条件可支持修改（为了避免误删除操作带来的影响，若非频繁触发导致日常同步难以进行，不建议修改保护条件）。 注意：触发删除保护时，仅会自动停止您的删除操作请求，如果同一次同步中同时发起了新建、修改请求，新增、修改等请求会继续执行，不会受到影响。

img

第三步：启动Microsoft Entra ID数据源同步

1. 连通性校验

检查AAD连通性校验。配置完成，进入同步页面。在页面上查看校验结果。注意：如果提示校验失败，重点检查凭证信息是否填写正确以及AAD侧证书是否配置。具体情况可参考文末FAQ img

2. 手动同步

1）为您提供了两种导入/同步的执行方式方式：手动同步、定时同步。

当您配置好AAD作为数据源后，您会在「数据源」页面下，看到「手动同步」按钮。手动同步也分为手动全量同步和手动增量同步。

首次同步时，仅支持手动全量同步，当进行过首次过同步任务后，管理员可自由选择手动全量同步和手动增量同步。通过点击「手动同步」按钮，系统会立即执行一次导入/同步任务，手动同步的特点是即点即执行。 注意：上游数据源大数据量时，全量同步同步时间会较长，建议谨慎点击。

手动增量同步 img

手动全量同步 img

2）同步时，如您开启了「删除保护」为了方便您进行调试，手动同步支持忽略删除保护执行删除动作。即：手动执行时，即使有大批量删除，达到了删除保护阈值，也不会触发删除保护机制。注意：此能力建议仅在调试过程中使用，日常管理过程尽量不要使用，不然可能会造成误删除用户数据无法恢复情况。 img

2. 查看同步日志

在同步运行完毕后，可进入账号同步的页面查看同步日志，展示了在什么时间，以手动或者自动的方式进行了同步，并且可以查看同步的成功数据和失败数据。

img

点击具体某条同步日志，可以查看具体同步详情。

img

FAQ

1）Q：配置数据源时或者同步时，提示：缺少***权限：.....。

A：未在AAD中按要求配置应用API接口权限。请参考第一步中：4. 配置应用API接口权限；

2）Q：配置数据源时或者同步时，提示：凭据不正确......。

A：请检查凭证配置信息。请参考第一步中：3. 配置Microsoft Entra ID凭证信息；检查点如下：1）如果您选择的是「客户端密钥」请检查密钥是否复制正确。2）如果您选择的是「自建证书」，请检查证书是否已经下载并配置到AAD侧。另外一定要确保配置证书一致性。OneID侧证书是在配置数据源完成时才会生效。点击刷新证书但未保存时，证书不会生效。3）如果您选择的是「第三方证书」，请确保证书和私钥都上传至OneID，并且AAD侧也需要上传证书。还需确保证书有效性，比如证书是否过期。

3）Q：配置获取数据范围时，需选择部分用户组，却拉取不到用户组列表，提示：获取用户组失败....。

A：未和AAD连通，主要原因同问题2，凭证配置信息可能有误，请检查信息是否都已配置正确。如果确定没有问题，保存后重新编辑再次查看。