本地应用程序预配疑难解答

项目
12/13/2024

测试连接问题故障排除

配置预配代理和 ECMA 主机后，可以测试 Microsoft Entra 预配服务与预配代理、可扩展连接 (ECMA) 主机和应用程序之间的连接性。要执行此端到端测试，请在 Azure 门户的应用程序中选择“测试连接”。请务必在分配初始代理或更改代理后等待 10 到 20 分钟，然后再测试连接。如果在此时间之后测试连接失败，请尝试以下故障排除步骤：

检查代理和 ECMA 主机是否正在运行：
1. 在安装有代理的服务器上，转到开始>> 来打开服务。
2. 确保“Microsoft Entra Connect 预配代理”和“Microsoft ECMA2Host”服务包含在“服务”列表中，并且其状态为“正在运行”。
检查 ECMA 连接器主机服务是否响应请求。
1. 在安装了代理的服务器上，启动 PowerShell。
2. 更改为安装 ECMA 主机的文件夹，例如 C:\Program Files\Microsoft ECMA2Host。
3. 更改为子目录 Troubleshooting。
4. 在该目录中运行脚本 TestECMA2HostConnection.ps1。出现提示时，以参数的形式提供连接器名称和机密令牌。
```
PS C:\Program Files\Microsoft ECMA2Host\Troubleshooting> .\TestECMA2HostConnection.ps1
Supply values for the following parameters:
ConnectorName: CORPDB1
SecretToken: ************
```
5. 此脚本发送 SCIM GET 或 POST 请求，以验证 ECMA 连接器主机是否正在运行并响应请求。如果输出未显示 HTTP 连接成功，请检查服务是否正在运行，以及是否提供了正确的机密令牌。
转到 Azure 门户中的应用程序，选择“管理员连接性”，选择代理下拉列表，确保代理处于活动状态。
检查提供的机密令牌是否与本地机密令牌相同。转到本地，再次提供机密令牌，并将其复制到 Azure 门户。
确保已将一个或多个代理分配给 Azure 门户中的应用程序。
分配代理后，需要等待 10 到 20 分钟才能完成注册。在注册完成之前，连接性测试将无法正常工作。
确保使用的是未过期的有效证书。转到 ECMA 主机的“设置”选项卡，查看证书到期日期。如果证书已过期，请单击 Generate certificate 以生成新证书。
在虚拟机中转至任务栏，搜索“Microsoft Entra Connect 预配代理”，从而重新启动预配代理。右键单击“停止”，然后选择“启动”。
如果在重启 ECMA 连接器主机和预配代理并等待初始导入完成之后仍然看到 The ECMA host is currently importing data from the target application，则可能需要取消并重新开始在 Azure 门户中配置对应用程序的预配。
在 Azure 门户中预配租户 URL 时，请确保该 URL 遵循以下模式。可将 localhost 替换为主机名，但这并非必要操作。将 connectorName 替换为在 ECMA 主机中指定的连接器名称。错误消息“资源无效”通常指示 URL 不符合预期格式。
```
https://localhost:8585/ecma2host_connectorName/scim
```
导航到以下文件夹以查看预配代理日志：C：\ProgramData\Microsoft\Azure AD Connect 预配代理\跟踪
1. 如果看到以下错误，请将服务帐户“NT SERVICE\AADConnectProvisioningAgent”添加到名为“Performance Log Users”的本地组。这可以通过允许帐户访问所需的注册表项来消除“无法初始化指标收集器”异常错误：HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib

Unable to initialize metrics collector, exception: 'System.UnauthorizedAccessException: Access to the registry key 'Global' is denied.

配置 ECMA 主机时，请确保提供一个主题与 Windows 服务器的主机名匹配的证书。 ECMA 主机生成的证书会自动执行此操作，但只应用于测试目的。

Error code: SystemForCrossDomainIdentityManagementCredentialValidationUnavailable

Details: We received this unexpected response from your application: Received response from Web resource. Resource: https://localhost/Users?filter=PLACEHOLDER+eq+"8646d011-1693-4cd3-9ee6-0d7482ca2219" Operation: GET Response Status Code: InternalServerError Response Headers: Response Content: An error occurred while sending the request. Please check the service and try again.

如果无法配置 ECMA 主机，请在事件查看器中查看日志，或启动 ECMA 主机服务

要解决以下问题，请以管理员身份运行 ECMA 主机配置向导：

打开 ECMA 主机向导时发生错误。
可以配置 ECMA 主机向导，但无法看到 ECMA 主机日志。在此情况下，你需要以管理员身份打开 ECMA 主机配置向导，并端到端设置连接器。可通过以下方式简化此步骤：导出现有连接器，然后再次导入。
可以配置 ECMA 主机向导，但无法启动 ECMA 主机日志。

启用详细日志记录

默认情况下，ECMA 连接器主机的 switchValue 设置为 Verbose。此设置将发出详细的日志记录，帮助你排除故障问题。如果要将发出的日志数限制为仅出现错误的日志，则可以将详细级别更改为 Error。使用不支持 Windows 集成身份验证的 SQL 连接器时，我们建议将 switchValue 设置为 Error，因为它将确保不在日志中发出连接字符串。要将详细程度更改为“错误”，请将两个位置中的 switchValue 更新为“错误”，如下所示。

详细服务日志记录的文件位置：C:\Program Files\Microsoft ECMA2Host\Service\Microsoft.ECMA2Host.Service.exe.config。

<?xml version="1.0" encoding="utf-8"?> 
<configuration> 
    <startup>  
        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.6" /> 
    </startup> 
    <appSettings> 
      <add key="Debug" value="true" /> 
    </appSettings> 
    <system.diagnostics> 
      <sources> 
    <source name="ConnectorsLog" switchValue="Error"> 
          <listeners> 
            <add initializeData="ConnectorsLog" type="System.Diagnostics.EventLogTraceListener, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" name="ConnectorsLog" traceOutputOptions="LogicalOperationStack, DateTime, Timestamp, Callstack"> 
              <filter type=""/> 
            </add> 
          </listeners> 
        </source> 
        <!-- Choose one of the following switchTrace:  Off, Error, Warning, Information, Verbose --> 
        <source name="ECMA2Host" switchValue="Error"> 
          <listeners>  
            <add initializeData="ECMA2Host" type="System.Diagnos

向导记录的文件位置为 C:\Program Files\Microsoft ECMA2Host\Wizard\Microsoft.ECMA2Host.ConfigWizard.exe.config。

      <source name="ConnectorsLog" switchValue="Error"> 
        <listeners> 
          <add initializeData="ConnectorsLog" type="System.Diagnostics.EventLogTraceListener, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" name="ConnectorsLog" traceOutputOptions="LogicalOperationStack, DateTime, Timestamp, Callstack"> 
            <filter type=""/> 
          </add> 
        </listeners> 
      </source> 
      <!-- Choose one of the following switchTrace:  Off, Error, Warning, Information, Verbose --> 
      <source name="ECMA2Host" switchValue="Error"> 
        <listeners> 
          <add initializeData="ECMA2Host" type="System.Diagnostics.EventLogTraceListener, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" name="ECMA2HostListener" traceOutputOptions="LogicalOperationStack, DateTime, Timestamp, Callstack" />

查询 ECMA 主机缓存

ECMA 主机在应用程序中有一个用户缓存，该缓存根据在 ECMA 主机向导的属性页中指定的计划进行更新。要查询缓存，请执行以下步骤：

将调试标志设置为 true。

请注意，将调试标志设置为 true 会禁用 ECMA 主机上的身份验证。你需要将其设置回 false，并在查询缓存后重启 ECMA 主机服务。

详细服务日志记录的文件位置为 C:\Program Files\Microsoft ECMA2Host\Service\Microsoft.ECMA2Host.Service.exe.config。
```
<?xml version="1.0" encoding="utf-8"?>
<configuration>
   <startup>  
       <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.6" /> 
   </startup> 
   <appSettings> 
     <add key="Debug" value="true" /> 
   </appSettings> 
```
重新启动 Microsoft ECMA2Host 服务。
等待 ECMA 主机连接到目标系统，并从每个连接的系统重新读取其缓存。如果这些连接的系统中有许多用户，则此导入过程可能需要几分钟时间。
从安装了 ECMA 主机的服务器查询此终结点，将 {connector name} 替换为连接器的名称，该名称在 ECMA 主机的属性页中指定：https://localhost:8585/ecma2host_{connectorName}/scim/cache。
1. 在安装了代理的服务器上，启动 PowerShell。
2. 更改为安装 ECMA 主机的文件夹，例如 C:\Program Files\Microsoft ECMA2Host。
3. 更改为子目录 Troubleshooting。
4. 在该目录中运行脚本 TestECMA2HostConnection.ps1，并提供连接器名称和 ObjectTypePath 值 cache 作为参数。出现提示时，键入为该连接器配置的机密令牌。
```
PS C:\Program Files\Microsoft ECMA2Host\Troubleshooting> .\TestECMA2HostConnection.ps1 -ConnectorName CORPDB1 -ObjectTypePath cache
Supply values for the following parameters:
SecretToken: ************
```
5. 此脚本发送 SCIM GET 请求，以验证 ECMA 连接器主机是否正在运行并响应请求。如果输出未显示 HTTP 连接成功，请检查服务是否正在运行，以及是否提供了正确的机密令牌。
在查询完缓存后，将调试标志重新设置为 false 或删除该设置。
重新启动 Microsoft ECMA2Host 服务。

缺少目标属性

预配服务会自动发现目标应用程序中的属性。如果发现 Azure 门户中的目标属性列表中缺少目标属性，请执行以下故障排除步骤：

查看 ECMA 主机配置的“选择属性”页，检查是否已选择该属性，以便将其公开给 Azure 门户。
确保 ECMA 主机服务正在运行。
将代理分配给企业应用程序后，完成测试连接步骤，保存管理员凭证，然后刷新浏览器。这会强制配置服务发出/架构请求并发现目标属性。
查看 ECMA 主机日志，检查是否发出了 /schemas 请求，并查看响应中的属性。此信息对于支持问题的解决很有价值。

从事件查看器中以 zip 文件格式收集日志

可以使用包含的脚本以 zip 文件格式捕获事件日志并将其导出。

在安装了代理的服务器上，右键单击“开始”菜单中的 PowerShell，然后选择 Run as administrator。
更改为安装 ECMA 主机的文件夹，例如 C:\Program Files\Microsoft ECMA2Host。
更改为子目录 Troubleshooting。
在该目录中运行脚本 CollectTroubleshootingInfo.ps1。
该脚本将在包含事件日志的目录中创建一个 ZIP 文件。

查看事件查看器中的事件

配置 ECMA 连接器主机架构映射后，请启动该服务，以便其侦听传入连接。然后，监视传入请求。

选择“开始”菜单，输入“事件查看器”并选择事件查看器。
在“事件查看器”中，展开“应用程序和服务”日志，然后选择“Microsoft ECMA2Host 日志”。
在连接器主机收到更改时，事件会写入应用程序日志。

常见错误

错误	解决方法
无法加载文件或程序集“file:///C:\Program Files\Microsoft ECMA2Host\Service\ECMA\Cache\8b514472-c18a-4641-9a44-732c296534e8\Microsoft.IAM.Connector.GenericSql.dll”或其依赖项之一。访问被拒绝。	确保网络服务帐户对缓存文件夹具有“完全控制”权限。如果帐户具有权限，但 .NET 尝试创建连接器 DLL 的副本，则可能需要将 DLL 添加到全局程序集缓存。
对象 DN 的 LDAP 样式无效。 DN：username@domain.com 或 `Target Site: ValidByLdapStyle`	确保未在 ECMA 主机的“连接”页中选中“DN 是定位点”复选框。确保在 ECMA 主机的“对象类型”页中选中了“自动生成”复选框。有关详细信息，请参阅关于定位点属性和可分辨名称。
ExportErrorCustomContinueRun。 objectClass：根据语法，数字值无效	请确保映射到 `objectClass` 属性的预配属性仅包含目录服务器识别的对象类的名称。

了解传入的 SCIM 请求

由 Microsoft Entra ID 向预配代理和连接器主机发出的请求将使用 SCIM 协议。从主机向应用发送的请求使用应用支持的协议。从主机发送到代理再发送到 Microsoft Entra ID 的请求依赖于 SCIM。有关 SCIM 实现的更多信息，请参阅教程：开发和计划 Microsoft Entra ID 中 SCIM 终结点的预配。

Microsoft Entra 预配服务通常会在以下三种情况下发出 get-user 调用来检查虚拟用户：在每个预配周期开始时、在执行按需预配之前以及在选择测试连接时。此检查可确保目标终结点可用，并将符合 SCIM 的响应返回到 Microsoft Entra 预配服务。

如何对预配代理进行故障排除？

你可能会遇到以下错误情况。

代理无法启动

你可能会收到以下错误消息：

服务“Microsoft Entra Connect 预配代理”无法启动。请检查有足够的特权启动系统服务。”

出现此问题的原因通常是组策略阻止将权限应用于安装程序创建的本地 NT 服务登录帐户 (NT Service\AADConnectProvisioningAgent)。这些权限是启动服务所必需的。

若要解决此问题，请执行以下操作:

使用管理员帐户登录到服务器。
导航到“服务”或者转到“开始”“运行”“Services.msc”来打开“服务”。
在“服务”下，双击“Microsoft Entra Connect 预配代理”。
在“登录”选项卡上，将此帐户更改为域管理员。然后重启服务。

此测试验证代理是否可以通过端口 443 与 Azure 通信。打开浏览器，然后通过安装有代理的服务器转到上一个 URL。

代理超时或证书无效

尝试注册代理时，可能会收到以下错误消息。

显示代理已超时的屏幕截图。

此问题通常是由于代理无法连接到混合标识服务所导致，并且需要你配置 HTTP 代理。若要解决此问题，请配置出站代理。

预配代理支持使用出站代理。可通过编辑代理配置文件“C:\Program Files\Microsoft Azure AD Connect Provisioning Agent\AADConnectProvisioningAgent.exe.config”对其进行配置。在文件的末尾添加以下行，恰好添加在尾随的标记前面。将变量 [proxy-server] 和 [proxy-port] 替换为代理服务器名称和端口值。

    <system.net>
        <defaultProxy enabled="true" useDefaultCredentials="true">
            <proxy
                usesystemdefault="true"
                proxyaddress="http://[proxy-server]:[proxy-port]"
                bypassonlocal="true"
            />
        </defaultProxy>
    </system.net>

代理注册失败，出现安全错误

安装云预配代理时可能会收到错误消息。

出现此问题的原因通常是由于本地 PowerShell 执行策略，代理无法执行 PowerShell 注册脚本。

若要解决此问题，请更改服务器上的 PowerShell 执行策略。需要将“计算机和用户策略”设置为“Undefined”或“RemoteSigned”。如果设置为“Unrestricted”，则会看到此错误。有关详细信息，请参阅 PowerShell 执行策略。

日志文件

默认情况下，代理发出最少的错误消息和堆栈跟踪信息。可以在 C:\ProgramData\Microsoft\Azure AD Connect Provisioning Agent\Trace 文件夹中找到这些跟踪日志。

要收集有关代理相关问题故障排除的更多信息，请执行以下操作：

按照 AADCloudSyncTools中所述安装 PowerShell 模块。
使用 Export-AADCloudSyncToolsLogs PowerShell cmdlet 捕获信息。使用以下开关微调数据收集。使用：
- “SkipVerboseTrace”用于仅导出当前日志而不捕获详细日志（默认值 = false）。
- “TracingDurationMins”用于指定不同的捕获持续时间（默认值 = 3 分钟）。
- “OutputPath”用于指定不同的输出路径（默认值 = 用户的文档）。

使用 Microsoft Entra ID，可以在云端监控预配服务、收集本地日志。预配服务针对在同步过程中评估的每个用户记录日志。可以通过 Azure 门户 UI、API 和日志分析来使用这些日志。 ECMA 主机还会生成本地日志。显示收到的每个预配请求，以及发送到 Microsoft Entra ID 的响应。

代理安装失败

System.ComponentModel.Win32Exception: The specified service already exists 错误表示以前的 ECMA 主机没有成功卸载。请卸载主机应用程序。转到程序文件，删除 ECMA 主机文件夹。你可能想要存储用于备份的配置文件。

以下错误表明未满足先决条件。确保你已经安装了 .NET 4.7.1。

  Method Name : <>c__DisplayClass0_1 : 
  RegisterNotLoadedAssemblies Error during load assembly: System.Management.Automation.resources.dll
  --------- Outer Exception Data ---------
  Message: Could not load file or assembly 'file:///C:\Program Files\Microsoft ECMA2Host\Service\ECMA\System.Management.Automation.resources.dll' or one of its dependencies. The system cannot find the file specified.

尝试使用 SQL 配置 ECMA 连接器主机时，收到了 LDAP 样式 DN 无效错误

默认情况下，泛型 SQL 连接器要求使用 LDAP 样式填充 DN（在第一个连接页中未选中“DN 是定位点”属性时）。在错误消息 Invalid LDAP style DN 或 Target Site: ValidByLdapStyle 中，你可能看到 DN 字段包含用户主体名称 (UPN)，而不是连接器所需的 LDAP 样式 DN。

若要解决此错误消息，请确保配置连接器时在“对象类型”页上选择“自动生成”。

有关详细信息，请参阅关于定位点属性和可分辨名称。

后续步骤

教程：ECMA 连接器主机泛型 SQL 连接器

通过