使用 PowerShell 将用户预配到应用程序中
以下文档提供了配置和教程信息，演示如何使用通用 PowerShell 连接器和 Extensible Connectivity (ECMA) Connector 主机将 Microsoft Entra ID 与提供基于 Windows PowerShell 的 API 的外部系统相集成。
有关其他信息，请参阅 Windows PowerShell 连接器技术参考
通过 PowerShell 进行预配的先决条件
以下部分详细介绍了本教程的先决条件。
下载 PowerShell 安装文件
从 GitHub 存储库中下载 PowerShell 安装程序文件。 安装文件包含配置文件、输入文件、架构文件和使用的脚本。
本地先决条件
连接器在 ECMA Connector Host 和 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 管理中心。
- 浏览到“标识”>“混合管理”>“Microsoft Entra Connet”>“云同步”>“代理”。
选择“下载本地代理”，查看服务条款，然后选择“接受条款并下载”。
注意
请使用不同的预配代理进行本地应用程序预配和 Microsoft Entra Connect 云同步/HR 驱动的预配。 不应在同一代理上管理所有三种方案。
打开预配代理安装程序，同意服务条款，然后选择“安装”。
Microsoft Entra 预配代理配置向导打开后，继续转到“选择扩展”选项卡，并在系统提示时为要启用的扩展选择“本地应用程序预配”。
预配代理使用操作系统的 Web 浏览器显示一个弹出窗口，供你向 Microsoft Entra ID 进行身份验证，还可能向组织的标识提供者进行身份验证。 如果使用 Internet Explorer 作为 Windows Server 上的浏览器，那么可能需要将 Microsoft 网站添加到浏览器的受信任站点列表中，以允许 JavaScript 正常运行。
当系统提示你授权时，请提供 Microsoft Entra 管理员的凭据。 用户必须至少具有混合标识管理员角色。
选择“确认”以确认设置。 安装成功后，可以选择“退出”，并关闭“预配代理包”安装程序。
配置本地 ECMA 应用
提示
本文中的步骤可能因开始使用的门户而略有不同。
- 至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。
- 浏览到“标识”>“应用程序”>“企业应用程序”。
- 选择“新建应用程序” 。
- 搜索“本地 ECMA 应用”应用程序，为该应用命名，然后选择“创建”以将其添加到租户。
- 导航到应用程序的预配页。
- 选择“开始”。
- 在“预配”页上，将模式更改为“自动”。
- 在“本地连接”部分上，选择刚刚部署的代理，然后单击“分配代理” 。
- 在使用配置向导完成下一步配置时，请保持此浏览器窗口为打开状态。
将 InputFile.txt 和 Schema.xml 文件放在正确位置
在为本教程创建 PowerShell 连接器之前，需要将 InputFile.txt 和 Schema.xml 文件复制到正确的位置。 这些文件是下载 PowerShell 安装文件部分中需要下载的。
| 文件 | location |
|---|---|
| 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”。
连接
“连接”选项卡允许你提供用于连接到远程系统的配置参数。 使用表中提供的信息配置连接选项卡。
- 在“连接”页上，应填充所有信息。 该表仅供参考。 单击“下一步”。
| 参数 | 值 | 目的 |
|---|---|---|
| 服务器 | <空白> | 连接器应连接到的服务器名称。 |
| Domain | <空白> | 要存储的以便在连接器运行时使用的凭据域。 |
| 用户 | <空白> | 要存储的以便在连接器运行时使用的凭据用户名。 |
| 密码 | <空白> | 要存储的以便在连接器运行时使用的凭据密码。 |
| 模拟连接器帐户 | 未选中 | 如果为 true，同步服务将对提供的凭据上下文中运行 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 脚本进行访问。 |
| 其他加密配置参数名称 | <空白> |
功能
功能选项卡定义连接器的行为和功能。 在创建连接器后，无法修改在此选项卡上所做的选择。 使用表中提供的信息配置“连接”选项卡。
- 在“功能”页上，应填充所有信息。 该表仅供参考。 单击“下一步”。
| 参数 | 值 | 目的 |
|---|---|---|
| 可分辨名称样式 | 无 | 指示连接器是否支持可分辨名称，如果支持，其样式为何。 |
| 导出类型 | ObjectReplace | 确定要对导出脚本显示的对象类型。 |
| 数据规范化 | 无 | 指示同步服务先将定位点属性规范化，再提供给脚本。 |
| 对象确认 | 普通 | 这会被忽略。 |
| 使用 DN 作为定位点 | 未选中 | 如果“可分辨名称样式”设置为 LDAP，则连接器空间的定位点属性也是可分辨名称。 |
| 多个连接器的并发操作 | 已选中 | 选中时，可以同时运行多个 Windows PowerShell 连接器。 |
| 分区 | 未选中 | 选中时，连接器可支持多个分区和分区发现。 |
| 层次结构 | 未选中 | 选中时，连接器可支持 LDAP 样式的层次结构。 |
| 启用导入 | 已选中 | 选中时，连接器将通过导入脚本导入数据。 |
| 启用增量导入 | 未选中 | 选中时，连接器可以从导入脚本请求增量。 |
| 启用导出 | 已选中 | 选中时，连接器将通过导出脚本导出数据。 |
| 启用完整导出 | 已选中 | 不支持。 这将被忽略。 |
| 第一个导出阶段没有引用值 | 未选中 | 选中时，会在第二个导出阶段导出引用属性。 |
| 启用对象重命名 | 未选中 | 选中时，可以修改可分辨名称。 |
| 删除-添加用作替换 | 已选中 | 不支持。 这将被忽略。 |
| 在第一个阶段启用导出密码 | 未选中 | 不支持。 这将被忽略。 |
全局参数
“全局参数”选项卡让你可以配置连接器运行的 Windows PowerShell 脚本。 还可以为“连接”选项卡上定义的自定义配置设置配置全局值。使用表中提供的信息配置“全局参数”选项卡。
- 在“全局参数”页上，应填充所有信息。 该表仅供参考。 单击“下一步”。
| 参数 | 值 |
|---|---|
| 分区脚本 | <空白> |
| 层次结构脚本 | <空白> |
| 开始导入脚本 | <空白> |
| 导入脚本 | 将导入脚本粘贴为值 |
| 结束导入脚本 | <空白> |
| 开始导出脚本 | <空白> |
| 导出脚本 | 将导入脚本粘贴为值 |
| 结束导出脚本 | <空白> |
| 开始密码脚本 | <空白> |
| 密码扩展脚本 | <空白> |
| 结束密码脚本 | <空白> |
| FileName_Global | InputFile.txt |
| Delimiter_Global | ; |
| Encoding_Global | <空白>（默认值为 UTF8） |
分区、运行配置文件、导出、完全导入
接受默认值，然后单击“下一步”。
对象类型
使用表中提供的信息配置“对象类型”选项卡。
- 在“对象类型”页上，应填充所有信息。 该表仅供参考。 单击“下一步”。
| 参数 | 值 |
|---|---|
| 目标对象 | 人员 |
| 定位点 | AzureObjectID |
| 查询属性 | AzureObjectID |
| DN | AzureObjectID |
选择属性
确保选择了以下特性：
在“选择特性”页上，应填充所有信息。 该表仅供参考。 单击“下一步”。
AzureObjectID
IsActive
DisplayName
EmployeeId
标题
UserName
电子邮件
取消设置
在“取消预配”页上，可以指定是否希望 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 管理中心。
- 浏览到“标识”>“应用程序”>“企业应用程序”。
- 选择“本地 ECMA 应用”应用程序。
- 选择预配。
- 如果出现“开始”，则将模式更改为“自动”，在“本地连接”部分，选择刚刚部署的代理并选择“分配代理”，并等待 10 秒钟。 否则，请转到“编辑预配”。
在“管理员凭据”部分中，输入以下 URL。 将
connectorName替换为在 ECMA 主机中指定的连接器的名称，例如PowerShell。 如果为 ECMA 主机提供了证书颁发机构提供的证书，请将localhost替换为安装了 ECMA 主机的服务器的主机名。属性 Value 租户 URL https://localhost:8585/ecma2host_connectorName/scim 输入你在创建连接器时定义的“机密令牌”值。
注意
如果你刚刚将代理分配到应用程序，请等待 10 分钟，以便完成注册。 在注册完成之前，连接性测试将无法正常工作。 通过在服务器上重新启动预配代理来强制完成代理注册，可以加快注册过程。 转到你的服务器，在 Windows 搜索栏中搜索“服务”，找到“Microsoft Entra Connect 预配代理服务”，右键单击该服务并重启。
单击“测试连接性”并等待一分钟。
连接测试成功并表明提供的凭据有权启用预配后，选择“保存”。
配置应用程序连接
返回到在其中配置应用程序预配的 Web 浏览器窗口。
注意
如果窗口已超时，则需要重新选择代理。
至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。
浏览到“标识”>“应用程序”>“企业应用程序”。
选择“本地 ECMA 应用”应用程序。
选择预配。
如果出现“开始”，则将模式更改为“自动”，在“本地连接”部分，选择部署的代理并选择“分配代理”。 否则，请转到“编辑预配”。
在“管理员凭据”部分中，输入以下 URL。 将
{connectorName}部分替换为 ECMA 连接器主机上的连接器名称，例如“CSV”。 连接器名称区分大小写，并且应该与向导中配置的大小写相同。 也可以将localhost替换为计算机主机名。属性 Value 租户 URL https://localhost:8585/ecma2host_CSV/scim输入你在创建连接器时定义的“机密令牌”值。
注意
如果你刚刚将代理分配到应用程序，请等待 10 分钟，以便完成注册。 在注册完成之前，连接性测试将无法正常工作。 通过在服务器上重新启动预配代理来强制完成代理注册，可以加快注册过程。 转到你的服务器，在 Windows 搜索栏中搜索“服务”，找到“Microsoft Entra Connect 预配代理服务”，右键单击该服务并重启。
单击“测试连接性”并等待一分钟。
连接测试成功并表明提供的凭据有权启用预配后，选择“保存”。
配置属性映射
现在，需要在 Microsoft Entra ID 中的用户表示形式与本地 InputFile.txt 中的用户表示形式之间映射特性。
你将使用 Azure 门户配置 Microsoft Entra 用户的属性与你之前在 ECMA 主机配置向导中选择的属性之间的映射。
至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。
浏览到“标识”>“应用程序”>“企业应用程序”。
选择“本地 ECMA 应用”应用程序。
选择预配。
选择“编辑预配”，然后等待 10 秒。
展开“映射”，然后选择“预配 Microsoft Entra 用户”。 如果这是首次为此应用程序配置属性映射，则仅有一个用于占位符的映射存在。
要确认架构在 Microsoft Entra 中可用，请选中“显示高级选项”复选框并选择“编辑 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 直接 employeeId urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:EmployeeId 直接 jobTitle urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:Title 直接 mail urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:Email Expression 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 管理中心。
- 浏览到“标识”>“应用程序”>“企业应用程序”。
- 选择“本地 ECMA 应用”应用程序。
- 在左边的“管理”下，选择“用户和组” 。
- 选择“添加用户/组”。
- 在“用户”下，单击“未选择”。
- 在屏幕右侧选择用户，单击“选择”按钮。
- 单击“分配”。
Test provisioning
属性已映射完毕并且已分配用户，接下来可通过一个用户测试按需预配。
- 至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。
- 浏览到“标识”>“应用程序”>“企业应用程序”。
- 选择“本地 ECMA 应用”应用程序。
- 选择预配。
- 选择“按需预配”。
- 搜索一个测试用户，选择“预配”。
- 几秒钟后，出现消息“已在目标系统中成功创建用户”，其中包含用户特性的列表。
开始预配用户
- 按需预配成功后，返回“预配配置”页。 确保将范围设置为“仅限已分配的用户和组”，将预配状态设置为“开启”，单击“保存”。
- 等待几分钟，以便系统开始预配。 该过程可能需要用时 40 分钟以上。 预配作业完成后，如果已完成测试，可以按照下一部分所述，将预配状态更改为“关”，然后选择“保存”。 此操作将停止预配服务的运行。