針對內部部署應用程式佈建進行疑難排解

發行項
07/03/2024

針對測試連線問題進行疑難排解

設定佈建代理程式和可延伸連線能力 (ECMA) 主機之後，就可以開始測試從 Microsoft Entra 佈建服務到佈建代理程式、ECMA 主機和應用程式的連線。若要執行此端對端測試，請在 Azure 入口網站中，選取應用程式中的 [測試連線]。在指派初始代理程式或變更代理程式之後，請務必等候 10 到 20 分鐘之後再測試連線。如果測試連線在這段時間之後失敗，請嘗試執行下列疑難排解步驟：

檢查代理程式和 ECMA 主機是否正在執行：
1. 在安裝代理程式的伺服器上，前往 [開始]>[執行]>[Services.msc] 以開啟 [服務]。
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 入口網站中，前往您的應用程式，選取 [admin connectivity] \(系統管理連線\)，選取 [代理程式] 下拉式清單，然後確定您的代理程式為使用中。
檢查提供的祕密權杖是否與內部部署祕密權杖相同。前往內部部署環境，再次提供祕密權杖，然後將其複製到 Azure 入口網站。
確定您已將一或多個代理程式指派給 Azure 入口網站中的應用程式。
指派代理程式之後，您必須等候 10 到 20 分鐘，註冊才能完成。在註冊完成之前，連線測試將無法運作。
確定您使用未過期的有效憑證。前往 ECMA 主機的 [設定] 索引標籤檢視憑證的到期日。如果憑證已過期，請按一下 Generate certificate，以產生新的憑證。
前往您 VM 上的工作列，透過搜尋 Microsoft Entra AD Connect 佈建代理程式來重新啟動佈建代理程式。以滑鼠右鍵按一下 [停止]，然後選取 [啟動]。
如果您即使在重新啟動 ECMA 連接器主機和佈建代理程式並等候初始匯入完成之後仍繼續看到 The ECMA host is currently importing data from the target application，則您可能需要取消並重新開始設定佈建至 Azure 入口網站中的應用程式。
當您在 Azure 入口網站中提供租用戶 URL 時，請確定其遵循下列模式。您可以將 localhost 取代為您的主機名稱，但並非必要。將 connectorName 取代為您在 ECMA 主機中指定的連接器名稱。錯誤訊息「資源無效」通常表示 URL 未遵循預期的格式。
```
https://localhost:8585/ecma2host_connectorName/scim
```
瀏覽至下列資料夾以檢閱佈建代理程式記錄：C:\ProgramData\Microsoft\Azure AD Connect Provisioning Agent\Trace
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 is Anchor] \(DN 是錨點\) 核取方塊。確定已在 ECMA 主機的 [物件類型] 頁面中選取 [自動產生] 核取方塊。如需詳細資訊，請參閱關於錨點屬性和辨別名稱。
ExportErrorCustomContinueRun. objectClass：每個語法的值號碼無效	確定佈建屬性對應至 `objectClass` 屬性只包含目錄伺服器所識別的物件類別名稱。

了解傳入的 SCIM 要求

Microsoft Entra ID 對佈建代理程式和連接器主機提出的要求會使用 SCIM 通訊協定。從主機對應用程式提出的要求會使用應用程式支援的通訊協定。從主機對代理程式再對 Microsoft Entra ID 提出的要求會依賴 SCIM。您可以在教學課程：在 Microsoft Entra ID 中開發和規劃 SCIM 端點的佈建中深入了解 SCIM 實作。

Microsoft Entra 佈建服務通常會在三種情況下，呼叫 get-user 來檢查虛擬使用者：每個佈建週期的開頭、執行隨選佈建之前，以及選取測試連線時。這項檢查可確保目標端點可供使用，並將符合 SCIM 規範的回應傳回至 Microsoft Entra 佈建服務。

如何針對佈建代理程式進行疑難排解？

您可能會遇到下列錯誤情況。

代理程式無法啟動

您可能會收到錯誤訊息，指出：

「Microsoft Entra Connect 佈建代理程式」服務無法啟動。請確認您有足夠的權限可以啟動系統服務。」

此問題通常是因為群組原則，導致無法將權限套用至安裝程式建立的本機 NT 服務登入帳戶 (NT SERVICE\AADConnectProvisioningAgent)。需要有這些權限，才能啟動服務。

若要解決此問題：

使用管理員帳戶登入伺服器。
瀏覽至 [服務]，或前往 [開始]>[執行]>[Services.msc]，以開啟 [服務]。
在 [服務] 底下，按兩下 [Microsoft Entra Connect 佈建代理程式]。
在 [登入] 索引標籤上，將 [這個帳戶] 變更為網域管理員。然後重新啟動服務。

此測試會確認您的代理程式可以透過連接埠 443 與 Azure 進行通訊。開啟瀏覽器，然後從代理程式安裝所在的伺服器前往先前的 URL。

代理程式逾時或憑證無效

當您嘗試註冊代理程式時，可能會收到下列錯誤訊息。

顯示代理程式逾時的螢幕擷取畫面。

此問題通常是因為代理程式無法連線到混合式識別服務所造成的，而需要您設定 HTTP Proxy。若要解決此問題，請設定輸出 Proxy。

佈建代理程式支援使用連出 Proxy。您可以透過編輯代理程式設定檔 C:\Program Files\Microsoft Azure AD Connect 佈建代理程式\AADConnectProvisioningAgent.exe.config 來設定它。請將下列各行新增至該檔案中靠近檔案結尾處的 </configuration> 結尾標記之前。將變數 [proxy-server] 和 [proxy-port] 更換成您的 Proxy 伺服器名稱和連接埠值。

    <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 資料夾中找到追蹤記錄檔。

若要收集詳細資訊來對代理程式相關問題進行疑難排解：

安裝 AADCloudSyncToolsPowerShell 模組，如 AADCloudSyncTools 適用於 Microsoft Entra Connect 雲端同步的 PowerShell 模組所述。
使用 Export-AADCloudSyncToolsLogs PowerShell Cmdlet 來擷取資訊。使用下列參數來微調您的資料收集。使用：
- SkipVerboseTrace，僅匯出目前的記錄，而不會擷取詳細資訊記錄 (預設值 = false)。
- TracingDurationMins，以指定不同的擷取期間 (預設值 = 3 分鐘)。
- OutputPath，以指定不同的輸出路徑 (預設值 = 使用者的文件)。

藉由使用 Microsoft Entra ID，您可以監視雲端中的佈建服務，並在內部部署收集記錄。佈建服務會針對在同步處理過程中評估的每個使用者發出記錄。您可以透過 Azure 入口網站 UI、API 和 Log Analytics 來取用這些記錄。 ECMA 主機也會在內部部署產生記錄。它會顯示每個收到的佈建要求，以及傳送給 Microsoft Entra ID 的回應。

代理程式安裝失敗

錯誤 System.ComponentModel.Win32Exception: The specified service already exists 指出無法解除安裝先前的 ECMA 主機。解除安裝主應用程式。前往 [program files]，並移除 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 is anchor] \(DN 是錨點\) 屬性保持未核取時)。在錯誤訊息 Invalid LDAP style DN 或 Target Site: ValidByLdapStyle 中，您可能會看到 DN 欄位包含使用者主體名稱 (UPN)，而不是連接器預期的 LDAP 樣式 DN。

若要解決此錯誤訊息，請確定在設定連接器時，已在 [物件類型] 頁面上選取 [自動產生]。

如需詳細資訊，請參閱關於錨點屬性和辨別名稱。

下一步

教學課程：ECMA 連接器主機一般 SQL 連接器

共用方式為