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

發行項
02/13/2024

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

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

檢查代理程式和 ECMA 主機是否正在執行：
1. 在已安裝代理程式的伺服器上，移至 [啟動>執行>Services.msc] 以開啟 [服務]。
2. 在 [服務] 下，確定 [Microsoft Entra 連線布建代理程式] 和 [Microsoft ECMA2Host] 服務存在，且其狀態為 [正在執行]。
檢查 ECMA 連線 or 主機服務是否正在回應要求。
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 連線 or 主機正在操作和回應要求。如果輸出未顯示 HTTP 連線成功，請檢查服務是否正在執行，並提供正確的秘密令牌。
請前往 Azure 入口網站中的應用程式、選取系統管理員連線、選取代理程式下拉式清單，並確定代理程式為作用中，以確保代理程式為作用中。
檢查提供的秘密令牌是否與內部部署秘密令牌相同。移至內部部署，再次提供秘密令牌，然後將它複製到 Azure 入口網站。
請確定您已將一或多個代理程式指派給 Azure 入口網站中的應用程式。
指派代理程序之後，您必須等候 10 到 20 分鐘，註冊才能完成。在註冊完成之前，連線測試將無法運作。
請確定您使用的有效憑證尚未過期。移至 ECMA 主機的 [設定] 索引標籤，以檢視憑證到期日。如果憑證已過期，請按兩下 Generate certificate 以產生新的憑證。
藉由搜尋 Microsoft Entra 連線布建代理程式，以前往 VM 上的任務列，以重新啟動布建代理程式。以滑鼠右鍵按兩下 [ 停止]，然後選取 [ 啟動]。
如果您在重新啟動 ECMA 連線 or 主機和布建代理程式，並等候初始匯入完成之後仍繼續看到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 連線布建代理程式\追蹤
1. 如果您看到下列錯誤，請將服務帳戶「NT SERVICE\AAD 連線 ProvisioningAgent」新增至名為 “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主機服務。

開啟詳細信息記錄

根據預設， switchValue ECMA 連線 or 主機會設定為 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，並提供作為連接器名稱和值cache的ObjectTypePath自變數。出現提示時，輸入為該連接器設定的秘密令牌。
```
PS C:\Program Files\Microsoft ECMA2Host\Troubleshooting> .\TestECMA2HostConnection.ps1 -ConnectorName CORPDB1 -ObjectTypePath cache
Supply values for the following parameters:
SecretToken: ************
```
5. 此腳本會傳送 SCIM GET 要求，以驗證 ECMA 連線 or 主機是否運作並回應要求。如果輸出未顯示 HTTP 連線成功，請檢查服務是否正在執行，並提供正確的秘密令牌。
當您完成查詢快取之後，請將 [偵錯] 旗標設定回 false 或移除設定。
重新啟動 Microsoft ECMA2Host 服務。

遺漏目標屬性

布建服務會自動探索目標應用程式中的屬性。如果您在 Azure 入口網站的目標屬性清單中看到目標屬性遺失，請執行下列疑難解答步驟：

檢閱 ECMA 主機組態的 [選取屬性] 頁面，檢查是否已選取屬性，使其公開至 Azure 入口網站。
確定 ECMA 主機服務正在執行。
將代理程式指派給企業應用程式之後，完成測試連線步驟，然後儲存系統管理員認證，重新整理瀏覽器。這會強制布建服務提出 /schemas 要求，並探索目標屬性。
檢閱 ECMA 主機記錄，以檢查已提出 /schemas 要求，並檢閱回應中的屬性。這項資訊對於針對問題進行疑難解答的支援而言十分有用。

從事件檢視器收集記錄作為 zip 檔案

您可以使用包含的腳本來擷取 zip 檔案中的事件記錄，並加以匯出。

在已安裝代理程式的伺服器上，以滑鼠右鍵按兩下 [開始] 功能表中的 PowerShell，然後選取至 Run as administrator。
變更為已安裝 ECMA 主機的資料夾，例如 C:\Program Files\Microsoft ECMA2Host。
變更為子目錄 Troubleshooting。
在該目錄中執行腳本 CollectTroubleshootingInfo.ps1 。
腳本將會在該目錄中建立包含事件記錄檔的 ZIP 檔案。

在事件檢視器中檢閱事件

設定 ECMA 連線 or 主機架構對應之後，請啟動服務，以便接聽連入連線。然後，監視連入要求。

選取 [開始] 功能表，輸入事件查看器，然後選取 [事件檢視器]。
在 [事件檢視器] 中，展開 [應用程式和服務記錄]，然後選取 [Microsoft ECMA2Host 記錄]。
連接器主機收到變更時，事件會寫入應用程式記錄檔。

常見錯誤

錯誤	解決方法
無法載入檔案或元件 'file:///C：\Program Files\Microsoft ECMA2Host\Service\ECMA\Cache\8b514472-c18a-4641-9a44-732c296534e8\Microsoft.IAM。連線 or。GenericSql.dll 或其其中一個相依性。存取遭到拒絕。	確定網路服務帳戶具有快取資料夾的「完全控制」許可權。
物件的 DN LDAP 樣式無效。 DN： username@domain.com“ 或 `Target Site: ValidByLdapStyle`	確定 ECMA 主機的 [連線能力] 頁面中未核取 [DN 為錨點] 複選框。確定在 ECMA 主機的 [物件類型] 頁面中選取 [自動產生] 複選框。如需詳細資訊，請參閱關於錨點屬性和辨別名稱。
ExportErrorCustomContinueRun。 objectClass：每個語法的值號碼無效	確定與屬性的布建屬性對應 `objectClass` 只包含目錄伺服器所辨識的物件類別名稱。

了解傳入 SCIM 要求

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

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

如何? 針對布建代理程序進行疑難解答？

您可能會遇到下列錯誤案例。

代理程式無法啟動

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

「服務 'Microsoft Entra 連線布建代理程式」無法啟動。請檢查您有足夠的許可權可啟動系統服務。」

此問題通常是由組策略所造成，導致許可權無法套用至安裝程式所建立的本機 NT 服務登入帳戶（NT SERVICE\AAD 連線 ProvisioningAgent）。啟動服務需要這些許可權。

若要解決此問題：

使用系統管理員帳戶登入伺服器。
流覽至服務，或移至 [啟動>執行>服務.msc] 來開啟服務。
在 [服務] 底下，按兩下 [Microsoft Entra 連線布建代理程式]。
在 [登入] 索引標籤上，將 [此帳戶] 變更為網域管理員。然後重新啟動服務。

此測試會驗證您的代理程式可以透過埠 443 與 Azure 通訊。開啟瀏覽器，然後從安裝代理程式的伺服器移至先前的 URL。

代理程式逾時或憑證無效

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

Screenshot that shows that the agent timed out.

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

布建代理程式支援使用輸出 Proxy。您可以編輯代理程式配置檔 C：\Program Files\Microsoft Azure AD 連線 Provisioning Agent\AAD 連線ProvisioningAgent.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執行原則。您必須將 [計算機] 和 [用戶原則] 設定為 [未定義 ] 或 [遠端簽署]。如果它們設定為 [不受限制]，您會看到此錯誤。如需詳細資訊，請參閱 PowerShell 執行原則。

記錄檔

根據預設，代理程式會發出最少的錯誤訊息和堆疊追蹤資訊。您可以在 C：\ProgramData\Microsoft\Azure AD 連線 Provisioning Agent\Trace 資料夾中找到追蹤記錄。

若要收集疑難解答代理程序相關問題的詳細資訊：

如 AADCloudSyncTools Microsoft Entra 連線雲端同步的 AADCloudSyncTools PowerShell 模組中所述，安裝 PowerShell 模組。
Export-AADCloudSyncToolsLogs使用 PowerShell Cmdlet 來擷取資訊。使用下列參數來微調數據收集。使用：
- SkipVerboseTrace 僅導出目前的記錄，而不擷取詳細信息記錄（預設值 = false）。
- TracingDurationMins 指定不同的擷取持續時間（預設值 = 3 分鐘）。
- OutputPath 可指定不同的輸出路徑（預設值 = 使用者的檔）。

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

代理程式安裝失敗

錯誤 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 連線 or 主機時，我收到無效的 LDAP 樣式 DN 錯誤

根據預設，一般 SQL 連接器會預期 DN 會使用 LDAP 樣式填入（當第一個連線頁面中未核取 'DN is anchor' 屬性時）。在錯誤訊息 Invalid LDAP style DN 或 Target Site: ValidByLdapStyle中，您可能會看到 DN 字段包含使用者主體名稱（UPN），而不是連接器預期的 LDAP 樣式 DN。

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

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

下一步

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