使用 PowerShell 將使用者布建至應用程式
下列檔提供組態和教學課程資訊,示範一般 PowerShell 連接器和可延伸 連線 ivity(ECMA) 連線 or 主機如何用來整合 Microsoft Entra ID 與提供 Windows PowerShell 型 API 的外部系統。
如需詳細資訊,請參閱 Windows PowerShell 連線 or 技術參考
透過PowerShell布建的必要條件
下列各節詳述本教學課程的必要條件。
下載PowerShell安裝程式檔案
從 GitHub 存放庫下載 PowerShell 安裝程式檔案。 安裝程式檔案包含組態檔、輸入檔、架構檔案和所使用的腳本。
內部部署必要條件
連接器提供ECMA連線 or 主機與 Windows PowerShell 功能之間的橋樑。 使用 連線 or 之前,請確定您在裝載連接器的伺服器上具有下列專案
- 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 產品可能會提供腳本來搭配此連接器使用,而這些產品會提供這些腳本的支持語句。 如果您要開發自己的腳本以搭配此連接器使用,您必須熟悉 Extensible 連線 ivity Management Agent API,才能開發和維護這些腳本。 如果您在生產環境中使用自己的腳本與第三方系統整合,建議您與第三方廠商或部署夥伴合作,以取得此整合的說明、指引和支援。
雲端需求
- 具有 Microsoft Entra ID P1 或 進階版 P2 的 Microsoft Entra 租使用者(或 EMS E3 或 E5)。 使用此功能需要 Microsoft Entra ID P1 授權。 若要尋找適合您需求的授權,請參閱比較 Microsoft Entra ID 正式推出的功能。
- 混合式身分識別 管理員 istrator 角色,用於設定布建代理程式和應用程式 管理員 istrator 或 Cloud Application 管理員 istrator 角色,以在 Azure 入口網站 中設定布建。
- 要布建的 Microsoft Entra 用戶必須已經填入架構所需的任何屬性。
下載、安裝及設定 Microsoft Entra 連線 布建代理程式套件
如果您已經下載布建代理程式,並將其設定為另一個內部部署應用程式,請繼續閱讀下一節。
- 以至少混合式身分識別 管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
- 流覽至身分>識別混合式管理>Microsoft Entra 連線> Cloud 同步>代理程式。
選取 [ 下載內部部署代理程式],檢閱服務條款,然後選取 [ 接受條款及下載]。
注意
請將不同的布建代理程式用於內部部署應用程式佈建和 Microsoft Entra 連線 雲端同步/HR 驅動布建。 這三個案例都不應該在相同的代理程式上管理。
開啟布建代理程式安裝程式、同意服務條款,然後選取 [ 安裝]。
當 Microsoft Entra 布建代理程式設定精靈開啟時,請繼續進行 [ 選取擴充功能 ] 索引標籤,然後在系統提示您啟用擴充功能時選取 [內部部署應用程式佈建 ]。
布建代理程式會使用操作系統的網頁瀏覽器來顯示彈出視窗,讓您向 Microsoft Entra ID 進行驗證,並可能也會顯示組織的識別提供者。 如果您使用 Internet Explorer 做為 Windows Server 上的瀏覽器,您可能需要將 Microsoft 網站新增至瀏覽器的信任網站清單,以允許 JavaScript 正確執行。
當系統提示您授權時,請提供 Microsoft Entra 系統管理員的認證。 使用者至少必須有混合式身分識別 管理員 istrator 角色。
選取 [ 確認 ] 以確認設定。 安裝成功之後,您可以選取 [ 結束],並關閉 [布建代理程式套件安裝程式]。
設定內部部署ECMA應用程式
提示
本文中的步驟可能會根據您從開始的入口網站稍有不同。
- 以至少應用程式 管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
- 流覽至 [身分>識別應用程式企業應用程式]。>
- 選取 [新增應用程式]。
- 搜尋 內部部署 ECMA 應用程式 應用程式、提供應用程式名稱,然後選取 [建立 ] 將它新增至您的租使用者。
- 瀏覽至應用程式的 [ 布建 ] 頁面。
- 選取開始使用。
- 在 [ 布建] 頁面上,將模式變更為 [自動]。
- 在 [內部部署 連線 ivity] 區段中,選取您剛才部署的代理程式,然後選取 [指派代理程式]。
- 當您使用設定精靈完成下一個步驟的設定時,請保持此瀏覽器窗口開啟。
將InputFile.txt和Schema.xml檔案放在位置
您必須先將InputFile.txt和Schema.xml檔案複製到正確的位置,才能建立本教學課程的 PowerShell 連接器。 這些檔案是您在下載 PowerShell 安裝程式檔案一節 中下載所需的檔案。
檔案 | location |
---|---|
InputFile.txt | C:\Program Files\Microsoft ECMA2Host\Service\ECMA\MAData |
Schema.xml | C:\Program Files\Microsoft ECMA2Host\Service\ECMA |
設定 Microsoft Entra ECMA 連線 or 主機憑證
- 在安裝布建代理程式的 Windows Server 上,以滑鼠右鍵按兩下 [開始] 選單中的 [Microsoft ECMA2Host 設定精靈 ],然後以系統管理員身分執行。 精靈必須以 Windows 系統管理員身分執行,才能建立必要的 Windows 事件記錄檔。
- ECMA 連線 or 主機組態啟動之後,如果這是您第一次執行精靈,則會要求您建立憑證。 保留預設埠 8585 ,然後選取 [產生憑證 ] 以產生憑證。 自動產生的憑證將會自我簽署為受信任根目錄的一部分。 憑證 SAN 符合主機名。
- 選取 [儲存]。
建立 PowerShell 連線 or
一般畫面
從 [開始] 功能表啟動 [Microsoft ECMA2Host 設定精靈]。
在頂端,選取 [ 匯 入],然後從步驟 1 選取configuration.xml檔案。
應該建立新的連接器,並以紅色顯示。 按一下 [編輯] 。
產生用來向連接器驗證 Microsoft Entra 識別碼的秘密令牌。 每個應用程式至少應為 12 個字元且是唯一的。 如果您還沒有秘密產生器,您可以使用 PowerShell 命令,例如下列命令來產生範例隨機字串。
-join (((48..90) + (96..122)) * 16 | Get-Random -Count 16 | % {[char]$_})
在 [ 屬性] 頁面上,應該填入所有資訊。 數據表會以參考的形式提供。 按一下 [下一步] 。
屬性 值 名稱 您為連接器選擇的名稱,在環境中的所有連接器中都應該是唯一的。 例如: PowerShell
。自動同步定時器 (分鐘) 120 秘密令牌 在這裡輸入您的秘密令牌。 至少應為 12 個字元。 擴充功能 DLL 針對 PowerShell 連接器,選取 [Microsoft.IAM.連線或。PowerShell.dll。
連線性
[連線] 索引標籤可讓您提供組態參數,以連線到遠端系統。 使用數據表中提供的資訊來設定連線索引標籤。
- 在 [連線 ivity] 頁面上,應該填入所有資訊。 數據表會以參考的形式提供。 按一下 [下一步] 。
參數 | 值 | 目的 |
---|---|---|
伺服器 | <Blank> | 連接器應該連接的伺服器名稱。 |
網域 | <Blank> | 要儲存在連接器執行時使用的認證網域。 |
User | <Blank> | 執行連接器時要儲存以供使用的認證用戶名稱。 |
密碼 | <Blank> | 執行連接器時,要儲存以供使用的認證密碼。 |
模擬 連線 or 帳戶 | 未選取 | 當為 true 時,同步處理服務會在提供的認證內容中執行 Windows PowerShell 腳本。 可能的話,建議 使用 $Credentials 參數到每個腳本,而不是模擬。 |
模擬時載入使用者配置檔 | 未選取 | 指示 Windows 在模擬期間載入連接器認證的使用者配置檔。 如果仿真的使用者有漫遊配置檔,連接器不會載入漫遊配置檔。 |
模擬時登入類型 | 無 | 模擬期間的登入類型。 如需詳細資訊,請參閱 dwLogonType 檔。 |
僅限已簽署的腳本 | 未選取 | 如果為 true,Windows PowerShell 連接器會驗證每個腳本是否有有效的數字簽名。 如果為 false,請確定同步處理服務伺服器的 Windows PowerShell 執行原則為 RemoteSigned 或 Unrestricted。 |
通用模組文稿名稱 (副檔名稱 ) | xADSyncPS 連線 orModule.psm1 | 連接器可讓您在設定中儲存共用的 Windows PowerShell 模組。 當連接器執行腳本時,Windows PowerShell 模組會擷取至文件系統,讓每個腳本可以匯入它。 |
通用模組腳本 | AD 同步 PowerShell 連線 or 模組程式代碼作為值。 當連接器執行時,ECMA2Host 會自動建立此模組。 | |
驗證腳本 | <Blank> | 驗證腳本是選用的 Windows PowerShell 腳本,可用來確保系統管理員提供的連接器組態參數有效。 |
架構腳本 | GetSchema 程式代碼 作為值。 | |
其他 Config 參數名稱 | FileName,Delimiter,Encoding | 除了標準組態設定之外,您還可以定義 連線 or 實例特有的其他自定義組態設定。 這些參數可以在連接器、分割區或執行步驟層級上指定,並從相關的 Windows PowerShell 腳本存取。 |
其他加密組態參數名稱 | <Blank> |
功能
[功能] 索引標籤會定義連接器的行為和功能。 建立連接器時,無法修改此索引標籤上所做的選取專案。 使用數據表中提供的資訊來設定功能索引標籤。
- 在 [ 功能] 頁面上,應該填入所有資訊。 數據表會以參考的形式提供。 按一下 [下一步] 。
參數 | 值 | 目的 |
---|---|---|
辨別名稱樣式 | 無 | 指出連接器是否支持辨別名稱,如果是,則表示樣式為何。 |
匯出類型 | ObjectReplace | 決定呈現給導出腳本的物件類型。 |
數據正規化 | 無 | 指示同步處理服務將錨點屬性正規化,再提供給腳本。 |
物件確認 | 一般 | 這會忽略。 |
使用 DN 作為錨點 | 未選取 | 如果辨別名稱樣式設定為LDAP,連接器空間的錨點屬性也是辨別名稱。 |
數個 連線器的並行作業 | 已選取 | 核取時,可以同時執行多個 Windows PowerShell 連接器。 |
資料分割 | 未選取 | 核取時,連接器支援多個分割區和分割區探索。 |
階層 | 未選取 | 核取時,連接器支援LDAP樣式階層式結構。 |
啟用匯入 | 已選取 | 核取時,連接器會透過匯入腳本匯入數據。 |
啟用差異匯入 | 未選取 | 核取時,連接器可以從匯入腳本要求差異。 |
啟用匯出 | 已選取 | 核取時,連接器會透過匯出腳本匯出數據。 |
啟用完整匯出 | 已選取 | 不支援。 這會忽略。 |
第一次匯出階段中沒有參考值 | 未選取 | 核取時,參考屬性會在第二個導出階段中匯出。 |
啟用物件重新命名 | 未選取 | 核取時,可以修改辨別名稱。 |
Delete-Add As Replace | 已選取 | 不支援。 這會忽略。 |
在第一次傳遞中啟用匯出密碼 | 未選取 | 不支援。 這會忽略。 |
全域參數
[全域參數] 索引標籤可讓您設定連接器所執行的 Windows PowerShell 腳本。 您也可以為在 [連線 ivity] 索引標籤上定義的自訂組態設定全域值。使用表格中提供的資訊設定全域參數索引標籤。
- 在 [ 全局參數] 頁面上,應該填入所有資訊。 數據表會以參考的形式提供。 按一下 [下一步] 。
參數 | 值 |
---|---|
數據分割腳本 | <Blank> |
階層腳本 | <Blank> |
開始匯入腳本 | <Blank> |
匯入腳本 | 將匯入文本貼上為值 |
結束匯入腳本 | <Blank> |
開始匯出腳本 | <Blank> |
匯出腳本 | 將匯入文本貼上為值 |
結束匯出腳本 | <Blank> |
開始密碼文本 | <Blank> |
密碼延伸模組腳本 | <Blank> |
結束密碼文本 | <Blank> |
FileName_Global | InputFile.txt |
Delimiter_Global | ; |
Encoding_Global | <空白> (預設為 UTF8) |
數據分割、執行配置檔、匯出、FullImport
保留預設值,然後按 [下一步]。
物件類型
使用數據表中提供的資訊來設定物件類型索引標籤。
- 在 [ 物件類型 ] 頁面上,應該填入所有資訊。 數據表會以參考的形式提供。 按一下 [下一步] 。
參數 | 值 |
---|---|
目標物件 | 個人 |
錨點 | AzureObjectID |
查詢屬性 | AzureObjectID |
DN | AzureObjectID |
選取屬性
確定已選取下列屬性:
在 [ 選取屬性] 頁面上,應該填入所有資訊。 數據表會以參考的形式提供。 按一下 [下一步] 。
AzureObjectID
IsActive
DisplayName
EmployeeId
標題
UserName
電子郵件
解除佈建
在 [取消布建] 頁面上,您可以指定當使用者離開應用程式範圍時,是否要讓 Microsoft Entra ID 從目錄中移除使用者。 如果是,請在 [停用流程] 底下選取 [刪除],然後在 [刪除流程] 底下,選取 [刪除]。 如果已選擇 [設定屬性值],將無法在取消布建頁面上選取上一個頁面上選取的屬性。
- 在 [ 取消布建 ] 頁面上,應該填入所有資訊。 數據表會以參考的形式提供。 按一下 [下一步] 。
確定 ECMA2Host 服務正在執行中,並可透過 PowerShell 從檔案讀取
請遵循下列步驟來確認連接器主機已啟動,並已從目標系統識別任何現有的使用者。
- 在執行 Microsoft Entra ECMA 連線 or Host 的伺服器上,選取 [啟動]。
- 視需要選取 [ 執行 ],然後在方塊中輸入 services.msc 。
- 在 [ 服務 ] 清單中,確定 Microsoft ECMA2Host 存在且正在執行。 如果未執行,請選取 [ 啟動]。
- 在執行 Microsoft Entra ECMA 連線 or Host 的伺服器上,啟動 PowerShell。
- 變更為已安裝 ECMA 主機的資料夾,例如
C:\Program Files\Microsoft ECMA2Host
。 - 變更為子目錄
Troubleshooting
。 - 如所示在目錄中執行腳本
TestECMA2HostConnection.ps1
,並提供 作為連接器名稱和值cache
的ObjectTypePath
自變數。 如果您的連接器主機未接聽 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 識別碼到連接器主機的連線
返回您在入口網站中設定應用程式布建的網頁瀏覽器視窗。
注意
如果視窗逾時,則您必須重新選取代理程式。
- 以至少應用程式 管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
- 流覽至 [身分>識別應用程式企業應用程式]。>
- 選取內部 部署 ECMA 應用程式應用程式 。
- 選取 [ 布建]。
- 如果 [開始使用] 出現,請將模式變更為 [自動],請在 [內部部署 連線 ivity] 區段上,選取您剛才部署的代理程式,然後選取 [指派代理程式],然後等候 10 分鐘。 否則,請移至 [ 編輯布建]。
在 [管理員 認證] 區段底下,輸入下列 URL。 將
connectorName
部份取代為 ECMA 主機上的連接器名稱,例如PowerShell
。 如果您從 ECMA 主機的證書頒發機構單位提供憑證,請將 取代localhost
為安裝 ECMA 主機之伺服器的主機名。屬性 值 租使用者 URL https://localhost:8585/ecma2host_connectorName/scim 輸入您在建立連接器時定義的秘密令牌值。
注意
如果您剛將代理程式指派給應用程式,請等候 10 分鐘才能完成註冊。 在註冊完成之前,連線測試將無法運作。 藉由重新啟動伺服器上的布建代理程式,強制代理程序註冊完成,可以加速註冊程式。 移至您的伺服器,在 Windows 搜尋列中搜尋服務、識別 Microsoft Entra 連線 布建代理程式服務、以滑鼠右鍵按兩下服務,然後重新啟動。
選取 [測試 連線,然後等候一分鐘。
線上測試成功並指出提供的認證已獲授權啟用布建之後,請選取 [ 儲存]。
設定應用程式連線
返回您設定應用程式布建所在的網頁瀏覽器視窗。
注意
如果視窗逾時,則您必須重新選取代理程式。
以至少應用程式 管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
流覽至 [身分>識別應用程式企業應用程式]。>
選取內部 部署 ECMA 應用程式應用程式 。
選取 [ 布建]。
如果 [開始使用] 出現,請將模式變更為 [自動],請在 [內部部署 連線 ivity] 區段上,選取您部署的代理程式,然後選取 [指派代理程式]。 否則,請移至 [ 編輯布建]。
在 [管理員 認證] 區段底下,輸入下列 URL。 將
{connectorName}
部分取代為 ECMA 連接器主機上的連接器名稱,例如 CSV。 連接器名稱區分大小寫,且大小寫應與精靈中設定的相同大小寫。 您也可以將 取代localhost
為您的電腦主機名。屬性 值 租使用者 URL https://localhost:8585/ecma2host_CSV/scim
輸入您在建立連接器時定義的秘密令牌值。
注意
如果您剛將代理程式指派給應用程式,請等候 10 分鐘才能完成註冊。 在註冊完成之前,連線測試將無法運作。 藉由重新啟動伺服器上的布建代理程式,強制代理程序註冊完成,可以加速註冊程式。 移至您的伺服器,在 Windows 搜尋列中搜尋服務、識別 Microsoft Entra 連線 布建代理程式服務、以滑鼠右鍵按兩下服務,然後重新啟動。
選取 [測試 連線,然後等候一分鐘。
線上測試成功並指出提供的認證已獲授權啟用布建之後,請選取 [ 儲存]。
設定屬性對應
現在,您必須在 Microsoft Entra ID 中代表使用者與內部部署InputFile.txt中的使用者表示法之間對應屬性。
您將使用 Azure 入口網站 來設定 Microsoft Entra 使用者屬性與先前在 ECMA 主機設定精靈中選取的屬性之間的對應。
以至少應用程式 管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
流覽至 [身分>識別應用程式企業應用程式]。>
選取內部 部署 ECMA 應用程式應用程式 。
選取 [ 布建]。
選取 [ 編輯布建],然後等候 10 秒。
展開 [對應] ,然後選取 [ 布建 Microsoft Entra 使用者]。 如果這是您第一次設定此應用程式的屬性對應,則佔位元元只會有一個對應存在。
若要確認架構可在 Microsoft Entra ID 中使用,請選取 [顯示進階選項 ] 複選框,然後選取 [編輯 ScimOnPremises 的屬性清單]。 確定已列出組態精靈中選取的所有屬性。 如果沒有,請等候數分鐘讓架構重新整理,然後重載頁面。 一旦您看到列出的屬性,然後從此頁面取消以返回對應清單。
現在,按兩下 userPrincipalName PLACEHOLDER 對應。 當您第一次設定內部部署布建時,預設會新增此對應。 變更 值以符合下列專案:
對應類型 來源屬性 目標屬性 直接 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 直接 郵件 urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:Email 運算式 Switch([IsSoftDeleted],, “False”, “True”, “True”, “False”) urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:IsActive 新增所有對應之後,請選取 [ 儲存]。
將使用者指派給應用程式
既然您已擁有與 Microsoft Entra ID 交談的 Microsoft Entra ECMA 連線 or Host,而且已設定屬性對應,您可以繼續設定布建範圍中的人員。
重要
如果您使用混合式身分識別 管理員 istrator 角色登入,則必須使用至少具有本節應用程式 管理員 istrator 角色的帳戶註銷和登入。 混合式身分識別 管理員 istrator 角色沒有將使用者指派給應用程式的許可權。
如果InputFile.txt中有現有的使用者,則您應該為這些現有使用者建立應用程式角色指派。 若要深入瞭解如何大量建立應用程式角色指派,請參閱 在 Microsoft Entra ID 中控管應用程式的現有使用者。
否則,如果沒有應用程式的目前使用者,請從將布建至應用程式的 Microsoft Entra 中選取測試使用者。
- 確定選取的使用者具有所有屬性,並對應至架構的必要屬性。
- 以至少應用程式 管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
- 流覽至 [身分>識別應用程式企業應用程式]。>
- 選取內部 部署 ECMA 應用程式應用程式 。
- 在左側的 [管理] 底下,選取 [使用者和群組]。
- 選取 [新增使用者/群組]。
- 在 [使用者] 底下,選取 [未選取]。
- 從右側選取使用者,然後選取 [ 選取 ] 按鈕。
- 現在選取 [ 指派]。
測試布建
現在已對應您的屬性並指派使用者,您可以測試隨選布建與其中一位使用者。
- 以至少應用程式 管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
- 流覽至 [身分>識別應用程式企業應用程式]。>
- 選取內部 部署 ECMA 應用程式應用程式 。
- 選取 [ 布建]。
- 選取 [ 隨選布建]。
- 搜尋其中一個測試用戶,然後選取 [ 布建]。
- 幾秒鐘之後,目標系統中成功建立的使用者會出現訊息,其中包含使用者屬性的清單。
開始布建使用者
- 在隨選布建成功之後,請變更回 [布建組態] 頁面。 確定範圍設定為僅指派的使用者和群組、開啟布建,然後選取 [儲存]。
- 等候數分鐘才能開始布建。 最多可能需要 40 分鐘的時間。 布建作業完成之後,如下一節所述,如果您完成測試,您可以將布建狀態變更為 [關閉],然後選取 [ 儲存]。 此動作會停止布建服務在未來執行。