以下文档提供了配置和教程信息。 它演示了通用 PowerShell 连接器和可扩展连接 （ECMA） 连接器主机如何用于将 Microsoft Entra ID 与提供基于 Windows PowerShell 的 API 的外部系统集成。
有关详细信息，请参阅 Windows PowerShell 连接器技术参考
通过 PowerShell 预配的先决条件
以下部分详细介绍了本教程的先决条件。
下载 PowerShell 安装文件
从 GitHub 存储库下载 PowerShell 安装文件。 安装程序文件包括配置文件、输入文件、架构文件和使用的脚本。
本地部署先决条件
该连接器提供 ECMA 连接器主机和 Windows PowerShell 功能之间的桥梁。 在使用连接器之前，请确保在托管连接器的服务器上具有以下内容
- Windows Server 2016 或更高版本。
- 至少 3 GB 的 RAM，用于托管预配代理。
- .NET Framework 4.7.2
- Windows PowerShell 2.0、3.0 或 4.0
- 托管服务器、连接器和 PowerShell 脚本与之交互的目标系统之间的连接。
- 必须将服务器上的执行策略配置为允许连接器运行 Windows PowerShell 脚本。 除非连接器要运行的脚本已经过数字签名，否则请运行以下命令来配置执行策略：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned - 部署此连接器需要一个或多个 PowerShell 脚本。 某些 Microsoft 产品可能会提供用于此连接器的脚本，此外还会提供这些脚本的支持声明。 如果要开发自己的脚本以用于此连接器，则需要熟悉 可扩展连接管理代理 API 来开发和维护这些脚本。 如果在生产环境中使用自己的脚本与第三方系统集成，建议与第三方供应商或部署合作伙伴合作，获取此集成的帮助、指导和支持。
云要求
- 使用 Microsoft Entra ID P1 或 Premium P2（或者 EMS E3 或 E5）的 Microsoft Entra 租户。 使用此功能需要 Microsoft Entra ID P1 许可证。 若要查找适合你的要求的许可证，请参阅 Microsoft Entra ID 的通用可用功能比较。
- 用于配置预配代理的混合标识管理员角色，以及用于在 Azure 门户配置预配的应用程序管理员或云应用程序管理员角色。
- 要预配的 Microsoft Entra 用户必须已经填充了架构所需的所有属性。
下载、安装和配置 Microsoft Entra Connect 预配代理包
如果已下载预配代理并将其配置为另一个本地应用程序，请继续阅读下一部分。
请以至少混合身份管理员的身份登录Microsoft Entra 管理中心。
浏览到 Entra ID>Entra Connect>云同步>代理。
选择 “下载本地代理”，查看服务条款，然后选择“ 接受条款”并下载。
注释
请使用不同的预配代理来进行本地应用程序预配以及 Microsoft Entra Connect 云同步/HR 驱动的预配。 不应在同一代理上管理这三种方案。
打开预配代理安装程序，同意服务条款，然后选择“ 安装”。
打开Microsoft Entra 预配代理配置向导时，请继续转到 “选择扩展 ”选项卡，并在系统提示你启用扩展时选择本地 应用程序预配 。
预配代理使用操作系统的 Web 浏览器显示一个弹出窗口，供你向 Microsoft Entra ID 进行身份验证，还可能向组织的标识提供者进行身份验证。 如果使用 Internet Explorer 作为 Windows Server 上的浏览器，则可能需要将Microsoft网站添加到浏览器的受信任站点列表中，以允许 JavaScript 正确运行。
当系统要求你进行授权时，请提供 Microsoft Entra 管理员的凭据。 用户必须至少具有混合标识管理员角色。
选择“确认”以确认设置。 安装成功后，可以选择“退出”，并关闭“预配代理包”安装程序。
配置本地 ECMA 应用
- 至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。
- 浏览到 Entra ID>企业应用。
- 选择新应用程序。
- 搜索“本地 ECMA 应用”应用程序，为该应用命名，然后选择“创建”以将其添加到租户。
- 导航到应用程序的 “预配 ”页。
- 选择开始。
- 在“预配”页上，将模式更改为“自动”。
- 在“本地连接”部分中，选择刚刚部署的代理，然后选择“分配代理”。
- 在使用配置向导完成下一步配置时，请保持此浏览器窗口为打开状态。
将 InputFile.txt 和 Schema.xml 文件置于位置
在为本教程创建 PowerShell 连接器之前，需要将 InputFile.txt 和 Schema.xml 文件复制到正确的位置。 这些文件是下载 PowerShell 安装程序文件部分所需的文件。
| File | 位置 |
|---|---|
| InputFile.txt | C:\Program Files\Microsoft ECMA2Host\Service\ECMA\MAData |
| Schema.xml | C:\Program Files\Microsoft ECMA2Host\Service\ECMA |
配置 Microsoft Entra ECMA 连接器主机证书
- 在安装预配代理的 Windows Server 上，从“开始”菜单中选择 Microsoft ECMA2Host 配置向导，然后以管理员身份运行。 必须以 Windows 管理员身份运行，向导才能创建必要的 Windows 事件日志。
- 在 ECMA 连接器主机配置启动后，如果这是你第一次运行该向导，它将要求你创建证书。 保留默认端口 8585 并选择“生成证书”以生成证书。 自动生成的证书通过自签名来成为信任根证书的一部分。 证书 SAN 与主机名匹配。
- 选择“保存”。
创建 PowerShell 连接器
通用屏幕
从“开始”菜单启动Microsoft ECMA2Host 配置向导。
在顶部，选择“ 导入 ”，然后从步骤 1 中选择 configuration.xml 文件。
应创建新连接器，并显示为红色。 选择 编辑。
生成用于向连接器进行身份验证Microsoft Entra ID 的机密令牌。 它至少应为 12 个字符，并且对于每个应用程序都是唯一的。 如果还没有机密生成器，可以使用 PowerShell 命令来生成示例随机字符串。
-join (((48..90) + (96..122)) * 16 | Get-Random -Count 16 | % {[char]$_})在 “属性” 页上，应填充所有信息。 该表作为引用提供。 选择“下一步”。
财产 价值 名称 为连接器选择的名称，它在环境中的所有连接器中应是唯一的。 例如， PowerShell。自动同步计时器（分钟） 120 机密令牌 在此处输入机密令牌。 它应至少为 12 个字符。 扩展 DLL 对于 PowerShell 连接器，请选择 Microsoft.IAM.Connector.PowerShell.dll。 
连接
“连接”选项卡允许你提供用于连接到远程系统的配置参数。 使用表中提供的信息配置连接选项卡。
- 在 “连接 ”页上，应填充所有信息。 该表作为引用提供。 选择“下一步”。
| 参数 | 价值 | Purpose |
|---|---|---|
| 服务器 | <空白> | 连接器应连接到的服务器名称。 |
| 域名 | <空白> | 要存储的以便在连接器运行时使用的凭据域。 |
| 用户 | <空白> | 要存储的以便在连接器运行时使用的凭据用户名。 |
| 密码 | <空白> | 要存储的以便在连接器运行时使用的凭据密码。 |
| 模拟连接器帐户 | 未选中 | 如果为真，同步服务将在提供的凭据上下文中运行 Windows PowerShell 脚本。 如果可能，建议使用 $Credentials 参数传递给每个脚本，而不是模拟。 |
| 模拟时加载用户配置文件 | 未选中 | 指示 Windows 在模拟期间加载连接器凭据的用户配置文件。 如果模拟用户具有漫游配置文件，连接器不会加载漫游配置文件。 |
| 模拟时的登录类型 | 没有 | 模拟期间的登录类型。 有关详细信息，请参阅 dwLogonType 文档。 |
| 仅限已签名的脚本 | 未选中 | 如果为 true，Windows PowerShell 连接器会验证每个脚本是否具有有效的数字签名。 如果为 false，请确保同步服务服务器的 Windows PowerShell 执行策略是 RemoteSigned 或 Unrestricted。 |
| 通用模块脚本名称（带扩展） | xADSyncPSConnectorModule.psm1 | 连接器允许在配置中存储共享的 Windows PowerShell 模块。 当连接器运行脚本时，它会将 Windows PowerShell 模块提取到文件系统，以便每个脚本都可以导入它。 |
| 通用模块脚本 | AD Sync PowerShell 连接器模块代码 作为值。 连接器运行时，ECMA2Host 会自动创建此模块。 | |
| 验证脚本 | <空白> | 验证脚本是可选的 Windows PowerShell 脚本，可用于确保管理员提供的连接器配置参数有效。 |
| 模式脚本 | GetSchema 代码 作为值。 | |
| 其他配置参数名称 | FileName，Delimiter，Encoding | 除了标准配置设置外，还可以定义连接器实例特定的其他自定义配置设置。 可以在连接器、分区或运行步骤级别指定这些参数，并从相关的 Windows PowerShell 脚本进行访问。 |
| 其他加密配置参数名称 | <空白> |
能力
“功能”选项卡定义连接器的行为和功能。 创建连接器时，无法修改此选项卡上所做的选择。 使用表中提供的信息配置功能选项卡。
- 在 “功能 ”页上，应填充所有信息。 该表作为引用提供。 选择“下一步”。
| 参数 | 价值 | Purpose |
|---|---|---|
| 可分辨名称样式 | 没有 | 指示连接器是否支持可分辨名称，如果支持，其样式为何。 |
| 导出类型 | ObjectReplace | 确定要对导出脚本显示的对象类型。 |
| 数据规范化 | 没有 | 指示同步服务先将定位点属性规范化，再提供给脚本。 |
| 对象确认 | 正常 | 此被忽略。 |
| 使用 DN 作为定位点 | 未选中 | 如果“专有名称样式”设置为 LDAP，则连接器空间的锚定属性也是专有名称。 |
| 多个连接器的并发操作 | 已检查 | 勾选后，可以同时运行多个 Windows PowerShell 连接器。 |
| 分区 | 未选中 | 选中时，连接器可支持多个分区和分区发现。 |
| Hierarchy | 未选中 | 选中时，连接器可支持 LDAP 样式的层次结构。 |
| 启用导入 | 已检查 | 选中时，连接器将通过导入脚本导入数据。 |
| 启用增量导入 | 未选中 | 选中时，连接器可以从导入脚本请求增量。 |
| 启用导出 | 已检查 | 选中时，连接器将通过导出脚本导出数据。 |
| 启用完整导出 | 已检查 | 不支持。 这将被忽略。 |
| 第一个导出阶段没有引用值 | 未选中 | 选中时，会在第二个导出阶段导出引用属性。 |
| 启用对象重命名 | 未选中 | 选中时，可以修改可分辨名称。 |
| 删除-添加用作替换 | 已检查 | 不支持。 这将被忽略。 |
| 在第一个阶段启用导出密码 | 未选中 | 不支持。 这将被忽略。 |
全局参数
使用“全局参数”选项卡可以配置连接器运行的 Windows PowerShell 脚本。 还可以为“连接”选项卡上定义的自定义配置设置配置全局值。使用表中提供的信息配置全局参数选项卡。
- 在 “全局参数 ”页上，应填充所有信息。 该表作为引用提供。 选择“下一步”。
| 参数 | 价值 |
|---|---|
| 分区脚本 | <空白> |
| 层次结构脚本 | <空白> |
| 开始导入脚本 | <空白> |
| 导入脚本 | 将导入脚本粘贴到值中 |
| 结束导入脚本 | <空白> |
| 开始导出脚本 | <空白> |
| 导出脚本 | 将导入脚本粘贴为值 |
| 结束导出脚本 | <空白> |
| 开始密码脚本 | <空白> |
| 密码扩展脚本 | <空白> |
| 结束密码脚本 | <空白> |
| FileName_Global | InputFile.txt |
| Delimiter_Global | ; |
| Encoding_Global | <空白> （默认为 UTF8） |
分区、运行配置文件、导出、完全导入
保留默认值，然后选择 “下一步”。
对象类型
使用表中提供的信息配置对象类型选项卡。
- 在 “对象类型 ”页上，应填充所有信息。 该表作为引用提供。 选择“下一步”。
| 参数 | 价值 |
|---|---|
| 目标对象 | 人员 |
| 锚点 | AzureObjectID |
| 查询属性 | AzureObjectID |
| DN | AzureObjectID |
选择属性
确保已选择以下属性：
在 “选择属性 ”页上，应填充所有信息。 该表作为引用提供。 选择“下一步”。
AzureObjectID
IsActive
显示名称
员工编号
标题
UserName
Email
取消预配
在“取消预配”页上，可以指定在用户离开应用程序范围时是否希望Microsoft Entra ID 从目录中删除用户。 如果是，请在“禁用流程”下选择“删除”，然后在“删除流程”下选择“删除”。 如果选择了“设置属性值”，那么在上一页选定的属性将无法在取消配置页面上选择。
- 在 “取消预配 ”页上，应填充所有信息。 该表作为引用提供。 选择“下一步”。
确保 ECMA2Host 服务正在运行，并且可以通过 PowerShell 从文件读取
按照以下步骤确认连接器主机已启动，并已识别目标系统中的任何现有用户。
- 在运行 Microsoft Entra ECMA 连接器主机的服务器上，选择“启动”。
- 根据需要选择 “运行 ”，然后在框中输入 services.msc 。
- 在“服务”列表，确保“Microsoft ECMA2Host”存在且正在运行。 如果未运行，请选择启动。
- 在运行 Microsoft Entra ECMA 连接器主机的服务器上，启动 PowerShell。
- 更改为安装了 ECMA 主机的文件夹，例如
C:\Program Files\Microsoft ECMA2Host。 - 更改为子目录
Troubleshooting。 - 按如下所示在目录中运行脚本
TestECMA2HostConnection.ps1，并提供连接器名称和ObjectTypePath值cache作为参数。 如果连接器主机未侦听 TCP 端口 8585，则可能还需要提供-Port参数。 出现提示时，键入为该连接器配置的机密令牌。PS C:\Program Files\Microsoft ECMA2Host\Troubleshooting> $cout = .\TestECMA2HostConnection.ps1 -ConnectorName PowerShell -ObjectTypePath cache; $cout.length -gt 9 Supply values for the following parameters: SecretToken: ************ - 如果脚本显示错误或警告消息，请检查服务正在运行，连接器名称和机密令牌与配置向导中配置的这些值匹配。
- 如果脚本显示输出
False，则连接器在源目标系统中没有为现有用户看到任何条目。 如果这是新的目标系统安装，则此行为是预期的，你可以在下一部分继续。 - 但是，如果目标系统已包含一个或多个用户，但显示
False脚本，则此状态表示连接器无法从目标系统读取。 如果尝试预配，则Microsoft Entra ID 可能无法将该源目录中的用户与 Microsoft Entra ID 中的用户正确匹配。 等待几分钟，连接器主机完成从现有目标系统读取对象，然后重新运行脚本。 如果输出仍然是False，请检查您的连接器配置，以及目标系统中的权限是否允许连接器读取现有用户。
测试从 Microsoft Entra ID 到连接器主机的连接
返回到在门户中配置应用程序预配的 Web 浏览器窗口。
注释
如果窗口超时，则需要重新选择代理。
- 至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。
- 浏览到 Entra ID>企业应用。
- 选择“本地 ECMA 应用”应用程序。
- 选择预配。
- 如果出现 “开始” ，请将模式更改为 “自动”，在“ 本地连接 ”部分中，选择刚刚部署的代理，然后选择“ 分配代理”，然后等待 10 分钟。 否则，请转到“编辑预配”。
在“管理员凭据”部分中，输入以下 URL。 将
connectorName部分替换为 ECMA 主机上的连接器名称，例如PowerShell。 如果您为 ECMA 主机提供了来自证书颁发机构的证书，请将localhost替换为安装了 ECMA 主机的服务器的主机名。财产 价值 租户 URL https://localhost:8585/ecma2host_connectorName/scim 输入你在创建连接器时定义的“机密令牌”值。
注释
如果你刚刚将代理分配到应用程序，请等待 10 分钟，以便完成注册。 在注册完成之前，连接性测试将无法正常工作。 通过在服务器上重新启动预配代理来强制完成代理注册，可以加快注册过程。 转到服务器，在 Windows 搜索栏中搜索 服务 ，标识 Microsoft Entra Connect 预配代理 服务，右键单击该服务，然后重启。
单击“测试连接性”并等待一分钟。
连接测试成功，并且显示提供的凭据被授权以启用供应后，选择“保存”。
配置应用程序连接
返回到在其中配置应用程序预配的 Web 浏览器窗口。
注释
如果窗口超时，则需要重新选择代理。
至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。
浏览到 Entra ID>企业应用。
选择“本地 ECMA 应用”应用程序。
选择预配。
如果出现开始，则在本地连接部分将模式更改为自动，选择您部署的代理并选择分配代理。 否则，请转到“编辑预配”。
在“管理员凭据”部分中，输入以下 URL。 将
{connectorName}部分替换为 ECMA 连接器主机上的连接器名称，例如 CSV。 连接器名称区分大小写，并且应该与向导中配置的大小写相同。 也可以将localhost替换为计算机主机名。财产 价值 租户 URL https://localhost:8585/ecma2host_CSV/scim输入你在创建连接器时定义的“机密令牌”值。
注释
如果你刚刚将代理分配到应用程序，请等待 10 分钟，以便完成注册。 在注册完成之前，连接性测试将无法正常工作。 通过在服务器上重新启动预配代理来强制完成代理注册，可以加快注册过程。 转到服务器，在 Windows 搜索栏中搜索 服务，识别 Microsoft Entra Connect 预配代理服务，右键单击该服务，然后重启。
单击“测试连接性”并等待一分钟。
连接测试成功，并且显示提供的凭据被授权以启用供应后，选择“保存”。
配置属性映射
现在，您需要在 Microsoft Entra ID 中用户属性与本地 InputFile.txt 中用户属性之间匹配属性。
你将使用 Azure 门户配置 Microsoft Entra 用户的属性与你之前在 ECMA 主机配置向导中选择的属性之间的映射。
至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。
浏览到 Entra ID>企业应用。
选择“本地 ECMA 应用”应用程序。
选择预配。
选择“编辑预配”，然后等待 10 秒。
展开“映射”，然后选择“预配 Microsoft Entra 用户”。 如果这是首次为此应用程序配置属性映射，则仅有一个用于占位符的映射存在。
若要确认架构在 Microsoft Entra ID 中可用，请选择“ 显示高级选项 ”复选框，然后选择 “编辑 ScimOnPremises”属性列表。 确保列出配置向导中选择的所有属性。 如果没有，请等待几分钟让架构刷新，然后重新加载页面。 看到属性列出后，从此页面取消以返回到映射列表。
现在，在 userPrincipalName 占位符映射上选择。 首次配置本地预配时，默认会添加此映射。 更改值以匹配以下项：
映射类型 源属性 目标属性 直接 userPrincipalName urn：ietf：params：scim：schemas：extension：ECMA2Host：2.0：User：UserName 现在选择“添加新映射”，并为每个映射重复接下来的步骤。
为下表中的每个映射指定源和目标属性。
映射类型 源属性 目标属性 直接 objectId urn：ietf：params：scim：schemas：extension：ECMA2Host：2.0：User：AzureObjectID 直接 userPrincipalName urn：ietf：params：scim：schemas：extension：ECMA2Host：2.0：User：UserName 直接 displayName urn：ietf：params：scim：schemas：extension：ECMA2Host：2.0：User：DisplayName 直接 员工编号 urn：ietf：params：scim：schemas：extension：ECMA2Host：2.0：User：EmployeeId 直接 职位名称 urn：ietf：params：scim：schemas：extension：ECMA2Host：2.0：User：Title 直接 邮件 urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:Email 表达式 Switch（[IsSoftDeleted]，，“False”，“True”，“True”，“False”） urn：ietf：params：scim：schemas：extension：ECMA2Host：2.0：User：IsActive 
添加所有映射后，选择“保存”。
将用户分配到应用程序
让 Microsoft Entra ECMA 连接器主机与 Microsoft Entra ID 通信并配置属性映射后，接下来即可继续配置预配对象的范围。
重要
如果使用混合标识管理员角色登录，则需要注销并重新登录，使用至少是本部分所需的应用程序管理员角色的帐户。 混合标识管理员角色无权将用户分配到应用程序。
如果 InputFile.txt中存在现有用户，则应为这些现有用户创建应用程序角色分配。 若要详细了解如何批量创建应用程序角色分配，请参阅管理 Microsoft Entra ID 中的应用程序现有用户。
否则，如果没有应用程序的当前用户，则从 Microsoft Entra 中选择一个将预配到应用程序的测试用户。
- 确保所选用户具有所有属性，这些属性映射到架构的必需属性。
- 至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。
- 浏览到 Entra ID>企业应用。
- 选择“本地 ECMA 应用”应用程序。
- 在左边的“管理”下，选择“用户和组” 。
- 选择“添加用户/组”。
- 在用户下，选择未选择。
- 在屏幕右侧选择用户，单击“选择”按钮。
- 现在选择“分配”。
测试资源配置
现在属性已经映射，用户也已分配，您可以针对某个用户进行按需预配测试。
- 至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。
- 浏览到 Entra ID>企业应用。
- 选择“本地 ECMA 应用”应用程序。
- 选择预配。
- 选择按需供应。
- 搜索一个测试用户，选择“预配”。
- 几秒钟后，将显示消息 在目标系统中成功创建用户，其中包含用户属性的列表。
开始预配用户
- 按需预配成功后，返回“预配配置”页。 确保将范围设置为“仅限已分配的用户和组”，将预配状态设置为“开启”，单击“保存”。
- 等待几分钟，以便系统开始预配。 该过程可能需要用时 40 分钟以上。 预配作业完成后，如下一部分所述，如果完成测试，可以将预配状态更改为 “关闭”，然后选择“ 保存”。 此操作将停止预配服务在未来的运行。