使用 Web 服務連接器來佈建

  • 發行項

下列文件提供一般 Web 服務連接器的相關資訊。 Microsoft Entra ID Governance 支援將帳戶佈建到各種應用程式中，例如 SAP ECC、Oracle eBusiness Suite，以及公開 REST 或 SOAP API 的企業營運應用程式。 以前部署過 MIM 連線到這些應用程式的客戶，可以輕鬆地切換至使用輕量型 Microsoft Entra 佈建代理程式，同時重複使用針對 MIM 建置的相同 Web 服務連接器。

支援的功能

  • 在應用程式中建立使用者。
  • 當使用者不再需要存取權時，將其從應用程式中移除。
  • 讓使用者屬性在 Microsoft Entra ID 與應用程式之間保持同步。
  • 探索應用程式的結構描述。

Web 服務連接器會實作下列函式：

  • SOAP 探索：可讓系統管理員輸入目標 Web 服務公開的 WSDL 路徑。 探索會產生應用程式託管 Web 服務的樹狀結構，其中包含其內部端點或作業，以及作業的中繼資料描述。 完成探索作業的數目沒有限制 (逐步進行)。 稍後會使用探索到的作業來設定資料來源，實作連接器作業的作業流程 (如匯入/匯出)。

  • REST 探索：可讓系統管理員輸入 REST 服務詳細資料，包括服務端點、資源路徑、方法和參數詳細資料。 REST 服務資訊會儲存在 wsconfig 專案的 discovery.xml 檔案中。 之後供系統管理員使用，在工作流程中設定 Rest Web 服務活動。

  • 結構描述設定：可讓系統管理員設定結構描述。 結構描述設定會包含特定應用程式的物件類型和屬性清單。 系統管理員可以選擇屬性，該屬性將成為結構描述的一部分。

  • 作業流程設定：工作流程設計工具 UI，可透過公開的 Web 服務作業函式來設定每個物件類型的匯入和匯出作業實作，包括佈建至 Web 服務函式的使用者指派參數。

佈建的必要條件

內部部署必要條件

執行佈建代理程式的電腦應該具備：

  • 應用程式 REST 或 SOAP 端點的連線能力，以及 login.microsoftonline.com、其他 Microsoft Online Services 和 Azure 網域的輸出連線能力。 例如，裝載於 Azure IaaS 或 Proxy 後方的 Windows Server 2016 虛擬機器。
  • 具備至少 3 GB RAM，用於託管佈建代理程式。
  • .NET Framework 4.7.2
  • Windows Server 2016 或更新版本。

設定佈建之前，請確定您：

  • 在您的應用程式中公開必要的 SOAP 或 REST 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 佈建代理程式

  1. 登入 Azure 入口網站。
  2. 移至企業應用程式，然後選取 [新的應用程式]。
  3. 搜尋 [內部部署 ECMA 應用程式] 的應用程式，提供應用程式名稱，然後選取建立以將其新增至您的租用戶。
  4. 從功能表瀏覽至應用程式的[佈建]頁面。
  5. 選取開始使用。
  6. 在 [佈建] 頁面上，將模式變更為 [自動]。

顯示選取 [自動] 的螢幕擷取畫面。

  1. 在 [內部部署連線能力] 下，選取 [下載並安裝]，然後選取 [接受條款並下載]。

  2. 離開入口網站並執行佈建代理程式安裝程式，同意服務條款，然後選取 [安裝]。

  3. 等待 Microsoft Entra 佈建代理程式設定精靈，然後選取 [下一步]。

  4. 在 [選擇延伸模組] 步驟中，選取 [內部應用程式佈建]，然後選取 [下一步]。

  5. 佈建代理程式會使用作業系統的網頁瀏覽器來顯示彈出視窗，讓您驗證 Microsoft Entra ID，並且可能會顯示您組織的識別提供者。 如果您使用 Internet Explorer 作為 Windows Server 上的瀏覽器，您可能需要將 Microsoft 網站新增至瀏覽器的受信任網站清單，以允許 JavaScript 正確執行。

  6. 當系統提示您授權時，請提供 Microsoft Entra 系統管理員的認證。 使用者必須至少有混合式身分識別系統管理員角色。

  7. 選取 [確認] 來確認設定。 安裝成功之後，您可以選取 [離開]，同時關閉 [佈建代理程式套件] 安裝程式。

4. 設定內部部署 ECMA 應用程式

  1. 在入口網站中，從 [內部部署連線能力] 區段，選取您已部署的代理程式，然後選取 [指派代理程式]。

    顯示如何選取並指派代理程式的螢幕擷取畫面。

  2. 在您使用設定精靈完成下個步驟的設定時，請讓此瀏覽器視窗保持開啟。

設定 Microsoft Entra ECMA Connector Host 憑證

  1. 在已安裝佈建代理程式的 Windows Server 上，從 [開始] 功能表以滑鼠右鍵按一下 [Microsoft ECMA2Host Configuration Wizard]，然後以系統管理員身分執行。 精靈必須以 Windows 系統管理員身分執行，才能建立必要的 Windows 事件記錄檔。

  2. 啟動 [ECMA Connector Host Configuration] 之後，如果這是您第一次執行精靈，系統會要求您建立憑證。 保留預設連接埠 8585 並選取 [產生憑證] 來產生憑證。 自動產生的憑證將會自我簽署成為可信任根的一部分。 憑證 SAN 符合主機名稱。

    顯示進行設定的螢幕擷取畫面。

  3. 選取 [儲存]。

建立 Web 服務連接器範本

建立 Web 服務連接器設定之前，您必須建立 Web 服務連接器範本，並自訂範本以符合特定環境的需求。 請確定 ServiceName、EndpointName 和 OperationName 正確無誤。

您可以在連接器下載套件中找到範例範本和指導，了解如何與熱門應用程式整合，例如 SAP ECC 7.0 和 Oracle eBusiness Suite。 您可以使用 SOAP 的工作流程指南，了解如何在 Web 服務設定工具中為您的資料來源建立新專案。

如需如何設定範本以連線至您自己應用程式的 REST 或 SOAP API 的詳細資訊，請參閱 MIM 程式庫中的一般 Web 服務連接器概觀。

設定一般 Web 服務連接器

在本節中，您將建立應用程式的連接器設定。

將佈建代理程式連接至您的應用程式

若要將 Microsoft Entra 佈建代理程式與您的應用程式連線，請遵循下列步驟：

  1. 將 Web 服務連接器範本 .wsconfig 檔案複製到 C:\Program Files\Microsoft ECMA2Host\Service\ECMA 資料夾。

  2. 產生用來向連接器驗證 Microsoft Entra ID 的秘密權杖。 每個應用程式至少應為 12 個字元且是唯一的。

  3. 如果您尚未這麼做，請從 Windows 的 [開始] 功能表啟動 [Microsoft ECMA2Host Configuration Wizard]。

  4. 選取新增連接器。

    顯示選擇 [新增連接器] 的螢幕擷取畫面。

  5. 在 [屬性] 頁面上，在方塊中填入影像後面表格中所指定的值，然後選取 [下一步]。

    顯示輸入屬性的螢幕擷取畫面。

    屬性 值
    名稱 您為連接器選擇的名稱，該名稱在環境中的所有連接器中應都是唯一的。
    自動同步計時器 (分鐘) 120
    祕密權杖 輸入您為此連接器產生的秘密權杖。 金鑰應至少有 12 個字元。
    延伸模組 DLL 針對 Web 服務連接器，選取 Microsoft.IdentityManagement.MA.WebServices.dll。

  6. 在 [連線能力] 頁面上，在方塊中填入影像後面表格中所指定的值，然後選取 [下一步]。

    顯示 [連線能力] 頁面的螢幕擷取畫面。

    屬性 說明
    Web 服務專案 您的 Web 服務範本名稱。
    Host 應用程式的 SOAP 端點主機名稱，例如 vhcalnplci.dummy.nodomain
    連接埠 應用程式的 SOAP 端點連接埠，例如 8000

  7. 在 [功能] 頁面上，在方塊中填入下列表格中所指定的值，然後選取 [下一步]。

    屬性 值
    辨別名稱樣式 泛型
    匯出類型 ObjectReplace
    資料正規化 無
    物件確認 Normal
    啟用匯入 已選取
    啟用差異匯入 未選取
    啟用匯出 已選取
    啟用完整匯出 未選取
    在第一個階段啟用匯出密碼 已選取
    第一個匯出階段沒有參考值 未選取
    啟用物件重新命名 未選取
    以刪除新增做為取代 未選取

注意

如果您的 Web 服務連接器範本已開啟，用於 Web 服務設定工具編輯，則會收到錯誤。

  1. 在 [全域] 頁面上，填寫方塊，然後選取 [下一步]。

  2. 在 [資料分割] 頁面上，選取 [下一步]。

  3. 在 [執行設定檔] 頁面上，保持選取 [匯出] 核取方塊。 選取 [完整匯入] 核取方塊，然後選取 [下一步]。 ECMA Connector 主機需要將變更從 Microsoft Entra ID 傳送至您的應用程式時，將會使用 [匯出]執行設定檔以插入、更新和刪除記錄。 ECMA Connector 主機服務啟動時，將會使用[完整匯入]執行設定檔，以讀取目前應用程式的內容。

    屬性 值
    Export 執行匯出資料至應用程式的設定檔。必須執行此設定檔。
    完整匯入 執行設定檔，從您的應用程式匯入所有資料。
    差異匯入 執行設定檔，此設定檔只會匯入自上次完整或差異匯入之後應用程式的變更。

  4. 在 [物件類型] 頁面上，填寫方塊，然後選取 [下一步]。 使用影像後面的表格來取得個別方塊的指引。

    • 錨點：此屬性的值對於目標系統中的每個物件而言應該是唯一的。 Microsoft Entra 佈建服務會在初始週期之後使用此屬性查詢 ECMA Connector 主機。 此值定義於 Web 服務連接器範本中。

    • DN：在大部分情況下，應該選取 [自動產生] 選項。 如果未選取此選項，請確定 DN 屬性對應至 Microsoft Entra ID 中的屬性，該屬性會以下列格式儲存 DN：CN = anchorValue, Object = objectType。 如需錨點和 DN 的詳細資訊，請參閱關於錨點屬性和辨別名稱。

      屬性 值
      目標物件 User
      錨點 userName
      DN userName
      自動產生 已選取

  5. ECMA Connector 主機會探索目標應用程式所支援的屬性。 然後，您可以選擇要公開給 Microsoft Entra ID 的已探索屬性。 接著即可在 Azure 入口網站中設定這些屬性，以供佈建。 在 [選取屬性] 頁面中，將所有屬性新增至下拉式清單，逐一進行。 [屬性] 下拉式清單會顯示在您的應用程式中探索到、但在先前 [選取屬性] 頁面上「未」選取的任何屬性。 所有相關屬性都新增完成後，請選取 [下一步]。

    顯示 [選取屬性] 頁面的螢幕擷取畫面。

  6. 在 [取消佈建] 頁面的 [停用流程] 下，選取 [刪除]。 在前一頁選取的屬性將無法在 [取消佈建] 頁面上選取。 選取 [完成]。

注意

如果您使用設定屬性值，請注意屬性值只允許布林值。

如果您要使用 expirationTime 等屬性控制使用者帳戶狀態，請在 [取消佈建] 頁面上的 [停用流程] 底下選取 [無]。 如果您不想要從應用程式刪除使用者，請在 [刪除流程] 底下選取 [無]，如果想要刪除，請選取 [刪除]。 選取 [完成]。

確定 ECMA2Host 服務正在執行

  1. 在執行 Microsoft Entra ECMA Connector 主機的伺服器上，選取 [啟動]。

  2. 輸入 [執行]，然後在方塊中輸入 services.msc。

  3. 在 [服務] 清單中，確定 Microsoft ECMA2Host 存在且正在執行。 如果沒有，請選取 [啟動]。

    顯示正在執行服務的螢幕擷取畫面。

  4. 如果您最近已啟動服務，且您的應用程式中有許多使用者物件，則請等候數分鐘，讓您的應用程式建立連線並執行初始完全導入。

在 Azure 入口網站中設定應用程式連線

  1. 返回您設定應用程式佈建的網頁瀏覽器視窗。

    注意

    如果視窗逾時，您則必須重新選取代理程式。

    1. 登入 Azure 入口網站。
    2. 移至 [企業應用程式] 和 [內部部署 ECMA 應用程式] 應用程式。
    3. 選取 [佈建]
    4. 選取 [開始使用]，並將模式變更為 [自動]，在 [內部部署連線能力] 區段中，選取您已部署的代理程式，然後選取 [指派代理程式]。 否則，請移至 [編輯佈建]。

  2. 在 [管理員認證] 區段底下，輸入下列 URL。 將 {connectorName} 部分取代為 ECMA Connector 主機上的連接器名稱。 連接器名稱有區分大小寫，且大小寫應該與精靈中所設定的大小寫相同。 您也可以將 localhost 取代為您的電腦主機名稱。

    屬性 值
    租用戶 URL https://localhost:8585/ecma2host_APP1/scim

  3. 輸入您在建立連接器時定義的 [秘密權杖] 值。

    注意

    如果您只是將代理程式指派給應用程式，請等候 10 分鐘讓註冊完成。 在註冊完成之前，連線測試將無法運作。 在您的伺服器上重新啟動佈建代理程式來強制完成代理程式註冊，可以加速註冊程式。 移至您的伺服器、在 Windows 搜尋列中搜尋 [服務]、找出 [Microsoft Entra Connect 佈建代理程式服務]、以滑鼠右鍵按一下服務，然後重新啟動。

  4. 選取 [測試連線]，然後等待一分鐘。

  5. 連線測試成功，並顯示提供的認證已獲授權啟用佈建後，請選擇 [儲存]。

    顯示測試代理程式的螢幕擷取畫面。

設定屬性對應

現在，您將在 Microsoft Entra ID 中的使用者標記法與應用程式中的使用者標記法之間對應屬性。

您將使用 Azure 入口網站來設定 Microsoft Entra 使用者屬性與先前在 ECMA 主機設定精靈中所選屬性之間的對應。

  1. 請確定 Microsoft Entra 結構描述包含應用程式所需的屬性。 如果需要使用者具有屬性，而且該屬性尚未成為使用者 Microsoft Entra 結構描述的一部分，則您必須使用目錄擴充功能，將該屬性新增為延伸模組。

  2. 在 Microsoft Entra 系統管理中心的 [企業應用程式] 底下，選取 [內部部署 ECMA 應用程式] 應用程式，然後選取 [佈建] 頁面。

  3. 選取 [編輯佈建]，然後等候 10 秒。

  4. 擴展 [對應] 區段然後選取 [佈建 Microsoft Entra 使用者]。 如果這是您第一次設定此應用程式的屬性對應，則這對於預留位置來說，將只會有一個對應。

    顯示佈建使用者的螢幕擷取畫面。

  5. 若要確認應用程式結構描述可在 Microsoft Entra ID 中使用，請選取 [顯示進階選項] 核取方塊，然後選取 [編輯 ScimOnPremises 的屬性列表]。 確定已列出設定精靈中選取的所有屬性。 如果沒有，請等候數分鐘讓結構描述重新整理，然後重新載入頁面。 一旦您看到列出的屬性，請取消此頁面以返回對應清單。

  6. 現在，按一下 [userPrincipalName] [PLACEHOLDER] 對應。 當您第一次設定內部部署佈建時，預設情況下會新增此對應。

顯示預留位置的螢幕擷取畫面。

將值變更以對應下列：

對應類型 來源屬性 目標屬性
直接 userPrincipalName urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:userName

  1. 現在選取 [新增對應]，然後針對每個對應重複下一個步驟。

  2. 針對應用程式所需的每個屬性指定來源和目標屬性。 例如，

    Microsoft Entra 屬性 ScimOnPremises 屬性 比對優先順序 套用此對應
    ToUpper(Word([userPrincipalName], 1, "@"), ) urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:userName 1 僅限物件建立期間
    Redact("Pass@w0rd1") urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:export_password 僅限物件建立期間
    市/鎮 urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:city 永遠
    companyName urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:company 永遠
    部門 urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:department 永遠
    mail urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:email 永遠
    Switch([IsSoftDeleted], , "False", "9999-12-31", "True", "1990-01-01") urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:expirationTime 永遠
    givenName urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:firstName 永遠
    surname urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:lastName 永遠
    telephoneNumber urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:telephoneNumber 永遠
    jobTitle urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:jobTitle 永遠

  3. 新增所有對應之後，請選取 [儲存]。

將使用者指派給應用程式

現在您已有 Microsoft Entra ECMA Connector 主機與 Microsoft Entra ID 進行通訊，屬性對應也已設定完成，接下來您可以設定要佈建的範圍。

重要

如果您已使用混合式身分識別管理員角色登入，則必須先登出，然後使用至少具有應用程式系統管理員角色帳戶登入，才能使用此區段。 混合式身分識別管理員角色沒有將使用者指派給應用程式的權限。

如果應用程式中有現有的使用者，則您應為這些現有的使用者建立應用程式角色指派。 若要深入了解如何大量建立應用程式角色指派，請參閱在 Microsoft Entra ID 中管理應用程式現有使用者。

如果應用程式目前沒有使用者，請從 Microsoft Entra 中選取將佈建至應用程式的測試使用者。

  1. 請確定您將選取的使用者具有將對應至應用程式所需屬性的所有屬性。

  2. 在 Azure 入口網站中，選取 [企業應用程式]。

  3. 選取 [內部部署 ECMA 應用程式] 應用程式。

  4. 在左側選取 [管理] 之下的 [使用者和群組]。

  5. 選取 [新增使用者/群組]。

    顯示新增使用者的螢幕擷取畫面。

  6. 在 [使用者] 底下，選取 [未選取]。

    顯示未選取任何項目的螢幕擷取畫面。

  7. 從右側選取使用者，然後選取 [選取] 按鈕。

    顯示 [選取使用者] 的螢幕擷取畫面。

  8. 現在請選取 [指派]。

    顯示指派使用者的螢幕擷取畫面。

測試佈建

現在您已對應您的屬性，使用者也指派完成，可以使用其中一個使用者來測試隨需佈建。

  1. 在 Azure 入口網站中，選取 [企業應用程式]。

  2. 選取 [內部部署 ECMA 應用程式] 應用程式。

  3. 選取左側的 [佈建]。

  4. 選取 [隨需佈建]。

  5. 搜尋您的其中一個測試使用者，然後選取 [佈建]。

    顯示測試佈建的螢幕擷取畫面。

  6. 幾秒鐘之後，「已成功在目標系統中建立使用者」的訊息即會出現，包含使用者屬性清單。

開始佈建使用者

  1. 隨需佈建成功之後，請返回佈建設定頁面。 確定範圍設定為 [僅限指派的使用者和群組]、[開啟] 佈建，然後選取 [儲存]。

    顯示開始佈建的螢幕擷取畫面。

  2. 最多等候 40 分鐘，讓佈建服務啟動。 完成佈建作業之後 (如下一節所述)，如果您已完成測試，則可以將佈建狀態變更為 [關閉]，然後選取 [儲存]。 此動作會使佈建服務在未來停止執行。

針對佈建錯誤進行疑難排解

如果顯示錯誤，請選取 [檢視佈建記錄]。 查看記錄檔中是否有 [狀態] 為「失敗」的資料列，然後選取該資料列。

如需詳細資訊，請變更為 [疑難排解與建議] 索引標籤。

下一步