自訂 SAML 權杖宣告

Microsoft 身分識別平台已針對應用程式庫中大部分預先整合的應用程式及自訂應用程式支援單一登入 (SSO)。 當使用者使用 SAML 2.0 通訊協定向 Microsoft 身分識別平台驗證應用程式時，會將權杖傳送到應用程式。 應用程式會驗證並使用權杖將使用者登入，而不會提示輸入使用者名稱和密碼。

這些 SAML 權杖包含使用者相關的一些資訊 (稱為「宣告」)。 宣告是識別提供者在發給使用者的權杖內用以描述使用者的資訊。 在 SAML 權杖中，宣告資料通常包含在 SAML 屬性陳述式中。 使用者的唯一識別碼通常在 SAML 主體中表示，也稱為名稱識別碼 (nameID)。

根據預設，Microsoft 身分識別平台會將 SAML 權杖核發給應用程式，該權杖包含宣告，其中具有使用者的使用者名稱 (亦稱為使用者主體名稱) 值，可唯一識別該使用者。 SAML 權杖也包含其他宣告，包括使用者的電子郵件地址、名字和姓氏。

檢視或編輯宣告

若要檢視或編輯在 SAML 權杖中對應用程式發出的宣告:

1. 以至少 雲端應用程式系統管理員 的身分登入 Microsoft Entra 系統管理中心。
2. 瀏覽至 [身分識別]>[應用程式]>[企業應用程式]>[所有應用程式]。
3. 選取應用程式，選取左側功能表中的 [單一登入]，然後在 [屬性與宣告] 區段中選取 [編輯]。

您可能基於下列原因，需要編輯在 SAML 權杖中發出的宣告:

• 應用程式要求 NameIdentifier 或 nameID 宣告必須是使用者名稱 (或使用者主體名稱) 以外的項目。
• 應用程式是設計為要求不同的宣告 URI 組或宣告值。

編輯 nameID

若要編輯名稱識別碼值宣告:

1. 開啟 [名稱識別碼值] 頁面。
2. 選取您想要套用到該屬性的屬性或轉換。 您也可以選擇性地針對 nameID 宣告指定所需的格式。

NameID 格式

如果 SAML 要求包含具有特定格式的 NameIDPolicy 元素，Microsoft 身分識別平台便會在要求中接受該格式。

如果 SAML 要求未包含 NameIDPolicy 的元素，Microsoft 身分識別平台會以您指定的格式發出 nameID。 如果未指定任何格式，Microsoft 身分識別平台會使用與所選取宣告來源相關聯的預設來源格式。 如果轉換產生 null 或不合法的值，Microsoft Entra ID 會在 nameID 中傳送持續成對的識別碼。

從 [選擇名稱識別碼格式] 下拉式清單中，選取下表中的其中一個選項。

nameID format	描述
Default	Microsoft 身分識別平台使用預設來源格式。
持續	Microsoft 身分識別平台使用 Persistent 作為 nameID 格式。
電子郵件地址	Microsoft 身分識別平台使用 EmailAddress 作為 nameID 格式。
未指定	Microsoft 身分識別平台使用 Unspecified 作為 nameID 格式。
Windows 網域限定名稱	Microsoft 身分識別平台使用 WindowsDomainQualifiedName 格式。

也支援暫時性 nameID，但其並未在下拉式清單中提供，也無法在 Azure 端設定。 若要深入了解 NameIDPolicy 屬性，請參閱單一登入 SAML 通訊協定。

屬性

提示

根據您從中開始的入口網站，本文中的步驟可能會略有不同。

選取 NameIdentifier (或 nameID) 宣告的所需來源。 您可以從下表中的選項選取。

名稱	描述
Email	使用者的電子郵件地址。
userprincipalName	使用者的使用者主要名稱 (UPN)。
onpremisessamaccountname	已從內部部署 Microsoft Entra ID 同步的 SAM 帳戶名稱。
objectid	Microsoft Entra ID 中使用者的物件識別碼。
employeeid	使用者的員工識別碼。
Directory extensions	使用 Microsoft Entra Connect 同步從內部部署 Active Directory 同步的目錄擴充。
Extension Attributes 1-15	內部部署擴充屬性，用來擴充 Microsoft Entra 架構。
pairwiseid	使用者識別碼的持續性形式。

如需識別碼值的詳細資訊，請參閱本頁稍後的表格，其中列出每個來源的有效識別碼值。

您可以將任何常數 (靜態) 值指派給任何宣告。 請使用下列步驟來指派常數值:

1. 在 [屬性與宣告] 刀鋒視窗上，選取您想要修改的必要宣告。
2. 依據您的組織，在 [來源屬性] 中輸入不含引號的常數值，然後選取 [儲存]。 常數值隨即顯示。

目錄架構擴充 (預覽)

您也可以將目錄架構擴充屬性設定為非條件式/條件式屬性。 請使用下列步驟，將單一或多重值目錄架構擴充屬性設定為宣告:

1. 在 [屬性與宣告] 刀鋒視窗上，選取 [新增宣告] 或編輯現有的宣告。
2. 從應用程式選擇器，選取從中定義擴充屬性的來源應用程式。
3. 選取 [新增]，將選取項目新增至宣告。
4. 按一下 [儲存] 以認可變更。

特殊宣告轉換

您可以使用下列特殊宣告轉換函式。

函式	描述
ExtractMailPrefix()	從電子郵件地址或使用者主體名稱中移除網域尾碼。 此函式只會擷取所傳遞使用者名稱的第一個部分 (例如 "joe_smith" 而不是 joe_smith@contoso.com)。
ToLower()	將所選取屬性中的字元轉換成小寫字元。
ToUpper()	將所選取屬性中的字元轉換成大寫字元。

新增應用程式特定宣告

若要新增應用程式特定宣告：

1. 在 [屬性與宣告] 刀鋒視窗上，選取 [新增宣告] 以開啟 [管理使用者宣告] 窗格。
2. 輸入宣告的 [名稱]。 根據 SAML 規格，該值並不一定需要遵循 URI 模式。如果您需要 URI 模式，請將其置於 [命名空間] 欄位。
3. 選取宣告要擷取其值的來源。 您可以使用來源屬性下拉式選單中的屬性，或對使用者屬性套用轉換再發出為宣告。

宣告轉換

若要將轉換套用到使用者屬性：

1. 在 [管理宣告] 中，選取 [轉換] 作為宣告來源以開啟 [管理轉換] 頁面。
2. 從轉換下拉式清單選取函式。 視所選取的函式而定，提供參數與常數值以在轉換中進行評估。
3. 按一下適當的選項按鈕，以選取屬性的來源。 目錄架構擴充來源目前為預覽狀態。
4. 從下拉式清單選取屬性名稱。
5. [將來源視為多重值] 是一個核取方塊，指出是否應將轉換套用至所有值或只套用到第一個值。 根據預設，轉換只會套用至多重值宣告中的第一個元素，核取此方塊會確保轉換套用至所有元素。 這個核取方塊只會針對多重值屬性啟用，例如 user.proxyaddresses。
6. 若要套用多個轉換，請選取 [新增轉換]。 您最多可以將兩個轉換套用至宣告。 例如，您可以先擷取 user.mail 的電子郵件前置詞。 接著將字串設定為大寫。

您可以使用下列函式來轉換宣告。

函式	描述
ExtractMailPrefix()	從電子郵件地址或使用者主體名稱中移除網域尾碼。 此函式只會擷取所傳遞使用者名稱的第一個部分。 例如，joe_smith 而不是 joe_smith@contoso.com。
Join()	透過聯結兩個屬性來建立新值。 您也可以選擇性地在兩個屬性之間使用分隔符號。 針對 nameID 宣告轉換，在轉換輸入具有網域部分時，Join() 函式會有特定行為。 該函式會先從輸入中移除網域部分，再將其與分隔符號和選取的參數聯結。 例如，如果轉換的輸入是 joe_smith@contoso.com，分隔符號是 @，而參數是 fabrikam.com，則此輸入組合會產生 joe_smith@fabrikam.com。
ToLowercase()	將所選取屬性中的字元轉換成小寫字元。
ToUppercase()	將所選取屬性中的字元轉換成大寫字元。
Contains()	如果輸入符合指定的值，則輸出屬性或常數。 否則，您可以在沒有相符結果時指定另一個輸出。 例如，假設您想要發出宣告，其中如果值包含網域 @contoso.com，便代表其為使用者的電子郵件地址，否則您便想要輸出使用者主體名稱。 若要執行此函式，請設定下列值: Parameter 1(input): user.email、Value: "@contoso.com"、Parameter 2 (output): user.email 和 Parameter 3 (output if there's no match): user.userprincipalname。
EndWith()	如果輸入的結尾是指定的值，則輸出屬性或常數。 否則，您可以在沒有相符結果時指定另一個輸出。 例如，假設您想要發出宣告，其中如果員工識別碼是以 000 作為結尾，便代表值為使用者的員工識別碼，否則您便想要輸出擴充屬性。 若要執行此函式，請設定下列值: Parameter 1(input): user.employeeid、Value: "000"、Parameter 2 (output): user.employeeid 和 Parameter 3 (output if there's no match): user.extensionattribute1。
StartWith()	如果輸入的開頭是指定的值，則輸出屬性或常數。 否則，您可以在沒有相符結果時指定另一個輸出。 例如，假設您想要發出宣告，其中如果國家/地區是以 US 作為開頭，便代表值為使用者的員工識別碼，否則您便想要輸出擴充屬性。 若要執行此函式，請設定下列值: Parameter 1(input): user.country、Value: "US"、Parameter 2 (output): user.employeeid 和 Parameter 3 (output if there's no match): user.extensionattribute1
Extract() - 比對之後	在子字串符合指定值之後加以傳回。 例如，假設輸入的值是 Finance_BSimon，相符的值是 Finance_，則宣告的輸出便是 BSimon。
Extract() - 比對之前	傳回子字串，直到其符合指定值為止。 例如，假設輸入的值是 BSimon_US，相符的值是 _US，則宣告的輸出便是 BSimon。
Extract() - 比對之間	傳回子字串，直到其符合指定值為止。 例如，假設輸入的值是 Finance_BSimon_US，第一個相符的值是 Finance_，第二個相符的值是 _US，則宣告的輸出便是 BSimon。
ExtractAlpha() - 前置詞	傳回字串的前置詞字母部分。 例如，假設輸入的值是 BSimon_123，其便會傳回 BSimon。
ExtractAlpha() - 後置詞	傳回字串的後置詞字母部分。 例如，假設輸入的值是 123_Simon，其便會傳回 Simon。
ExtractNumeric() - 前置詞	傳回字串的前置詞數值部分。 例如，假設輸入的值是 123_BSimon，其便會傳回 123。
ExtractNumeric() - 後置詞	傳回字串的後置詞數值部分。 例如，假設輸入的值是 BSimon_123，其便會傳回 123。
IfEmpty()	如果輸入為 Null 或空白，則輸出屬性或常數。 例如，假設您想要在使用者的員工識別碼為空白時，輸出儲存在擴充屬性中的屬性。 若要執行此函式，請設定下列值: Parameter 1(input): user.employeeid、Parameter 2 (output): user.extensionattribute1 和 Parameter 3 (output if there's no match): user.employeeid。
IfNotEmpty()	如果輸入為 Null 或空白，則輸出屬性或常數。 例如，假設您想要在使用者的員工識別碼不是空白時，輸出儲存在擴充屬性中的屬性。 若要執行此函式，請設定下列值: Parameter 1(input): user.employeeid 和 Parameter 2 (output): user.extensionattribute1。
Substring() - 固定長度 (預覽)	從指定位置的字元開始擷取部分的字串宣告類型，並傳回指定數目的字元。 sourceClaim 是應執行轉換的宣告來源。 StartIndex 是這個執行個體中子字串之以零為起始的起始字元位置。 Length 是子字串的長度 (以字元為單位)。 例如，sourceClaim - PleaseExtractThisNow、StartIndex - 6 和 Length - 11 會產生 ExtractThis 的輸出。
Substring() - EndOfString (預覽)	從指定位置的字元開始擷取部分的字串宣告類型，並從指定的起始索引傳回其餘的宣告部分。 sourceClaim 是應執行轉換的宣告來源。 StartIndex 是這個執行個體中子字串之以零為起始的起始字元位置。 例如，sourceClaim - PleaseExtractThisNow 和 StartIndex - 6 會產生 ExtractThisNow 的輸出。
RegexReplace() (預覽)	如需 RegEx 型宣告轉換的詳細資訊，請參閱下一節。

RegEx 型宣告轉換

下圖顯示第一層轉換的範例:

下表中所列的動作提供有關第一層轉換的資訊，並對應至上圖中的標籤。 選取 [編輯] 以開啟宣告轉換刀鋒視窗。

動作	欄位	描述
1	Transformation	從 [轉換] 選項中選取 [RegexReplace()] 選項，以使用 RegEx 型宣告轉換方法進行宣告轉換。
2	Parameter 1	規則運算式轉換的輸入。 例如，具有 admin@fabrikam.com 等使用者電子郵件地址的 user.mail。
3	Treat source as multivalued	某些輸入使用者屬性可以是多重值使用者屬性。 如果選取的使用者屬性支援多個值，而且使用者想要使用多個值進行轉換，則必須選取 [將來源視為多重值]。 如果已選取，則會使用所有值進行 RegEx 比對，否則只會使用第一個值。
4	Regex pattern	根據選取為 [參數 1] 的使用者屬性值進行評估的規則運算式。 例如，從使用者的電子郵件地址擷取使用者別名的規則運算式會以 (?'domain'^.*?)(?i)(\@fabrikam\.com)$ 表示。
5	Add additional parameter	可使用多個使用者屬性進行轉換。 屬性的值則會與 RegEx 轉換輸出合併。 最多支援五個參數。
6	Replacement pattern	取代模式是文字範本，其中包含 RegEx 結果的預留位置。 所有群組名稱都必須以大括弧括住，例如 {group-name}。 假設系統管理員想要一併使用使用者別名及某些其他網域名稱 (例如 xyz.com)，並與國家/地區名稱加以合併。 在本案例中，取代模式會是 {country}.{domain}@xyz.com，其中 {country} 是輸入參數的值，而 {domain} 是規則運算式評估中的群組輸出。 在這種情況下，預期的結果是 US.swmal@xyz.com。

下圖顯示第二層轉換的範例:

下表提供有關第二層轉換的資訊。 下表中所列的動作會對應至上圖中的標籤。

動作	欄位	描述
1	Transformation	RegEx 型宣告轉換不限制於第一層轉換，也可以用來作為第二層轉換。 任何其他轉換方法都可以作為第一層轉換。
2	Parameter 1	如果選取 RegexReplace() 作為第二層轉換，則第一層轉換的輸出會作為第二層轉換的輸入。 若要套用轉換，第二層 RegEx 運算式應該符合第一層轉換的輸出。
3	Regex pattern	[RegEx 模式] 是第二層轉換的規則運算式。
4	Parameter input	第二層轉換的使用者屬性輸入。
5	Parameter input	如果系統管理員不再需要選取的輸入參數，則可以將其刪除。
6	Replacement pattern	取代模式是文字範本，其中包含 RegEx 結果群組名稱的預留位置、輸入參數群組名稱的預留位置和靜態文字值的預留位置。 所有群組名稱都必須以大括弧括住，例如 {group-name}。 假設系統管理員想要一併使用使用者別名及某些其他網域名稱 (例如 xyz.com)，並與國家/地區名稱加以合併。 在本案例中，取代模式會是 {country}.{domain}@xyz.com，其中 {country} 是輸入參數的值，而 {domain} 是規則運算式評估中的群組輸出。 在這種情況下，預期的結果是 US.swmal@xyz.com。
7	Test transformation	只有在 [參數 1] 的選取使用者屬性值符合 [RegEx 模式] 文字方塊中提供的規則運算式時，才會評估 RegexReplace() 轉換。 如果不符合，預設宣告值會新增至權杖。 若要根據輸入參數值驗證規則運算式，則可在 [轉換] 刀鋒視窗中使用測試體驗。 此測試體驗僅適用於虛擬值。 使用更多輸入參數時，參數的名稱會新增至測試結果，而不是實際值。 若要存取測試區段，請選擇 [測試轉換]。

下圖顯示測試轉換的範例:

下表提供有關測試轉換的資訊。 下表中所列的動作會對應至上圖中的標籤。

動作	欄位	描述
1	Test transformation	選取 [關閉] 或 (X) 按鈕以隱藏測試區段，再次於刀鋒視窗上重新顯示 [測試轉換] 按鈕。
2	Test regex input	接受用於規則運算式測試評估的輸入。 如果 RegEx 型宣告轉換設定為第二層轉換，請提供第一層轉換的預期輸出值。
3	Run test	提供測試 RegEx 輸入並設定 [RegEx 模式]、[取代模式] 和 [輸入參數] 之後，即可選取 [執行測試] 來評估運算式。
4	Test transformation result	如果評估成功，則會根據 [測試轉換結果] 標籤轉譯測試轉換的輸出。
5	Remove transformation	選取 [移除轉換] 可移除第二層轉換。
6	Specify output if no match	如果已根據 [參數 1] 設定 RegEx 輸入值，但與 [規則運算式] 不符，則會略過轉換。 在這種情況下，可設定替代使用者屬性，這會藉由核取 [如果沒有相符項目，則指定輸出]，將其新增至宣告的權杖。
7	Parameter 3	當沒有相符項目且核取了 [如果沒有相符項目，則指定輸出] 時，如果必須傳回替代使用者屬性，則可以使用此下拉式清單選取替代使用者屬性。 此下拉式清單是針對 [參數 3 (如果沒有相符項目的輸出)] 所提供。
8	Summary	在刀鋒視窗底部，會顯示格式的完整摘要，簡單說明轉換的意義。
9	Add	驗證轉換的組態設定之後，即可選取 [新增]，將其儲存至宣告原則。 在 [管理宣告] 刀鋒視窗上選取 [儲存]，以儲存變更。

RegexReplace() 轉換也適用於群組宣告轉換。

RegexReplace() 轉換驗證

如果在選取 [新增] 或 [執行測試] 之後發生下列情況，則會顯示一則訊息，提供問題的詳細資訊:

• 不允許具有重複使用者屬性的輸入參數。
• 找到未使用的輸入參數。 已定義的輸入參數應該具有取代模式文字的個別用法。
• 提供的測試 RegEx 輸入與提供的規則運算式不符。
• 在 [取代模式] 中找不到群組的來源。

將 UPN 宣告新增至 SAML 權杖

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn 宣告屬於 SAML 受限制的宣告集。 如果您已設定自訂簽署金鑰，您可以在 [屬性與宣告] 區段中新增該金鑰。

如果未設定任何自訂簽署金鑰，請參閱 SAML 受限制的宣告集。 您可以透過 Azure 入口網站中的 [應用程式註冊]，將其新增為選擇性宣告。

在 [應用程式註冊] 中開啟應用程式，選取 [權杖設定]，然後選取 [新增選擇性宣告]。 選取 [SAML] 權杖類型，從清單中選擇 [UPN]，然後按一下 [新增]，將宣告新增至權杖。

在 [屬性與宣告] 區段中完成的自訂，可以覆寫 [應用程式註冊] 中的選擇性宣告。

根據條件發出宣告

您可以根據使用者類型和使用者所屬的群組來指定宣告的來源。

使用者類型可以是：

• 任何 - 所有使用者都可以存取應用程式。
• 成員: 租用戶的原生成員
• 所有來賓: 使用者來自具有或沒有 Microsoft Entra ID 的外部組織。
• Microsoft Entra 來賓: 來賓使用者屬於使用 Microsoft Entra ID 的另一個組織。
• 外部來賓: 來賓使用者屬於沒有 Microsoft Entra ID 的外部組織。

例如，當宣告的來源對於存取應用程式的來賓和員工而言不同時，使用者類型會很有幫助。 您可以指定如果使用者是員工，則 NameID 的來源為 user.email。 如果使用者是來賓，則 NameID 的來源為 user.extensionattribute1。

若要新增宣告條件：

1. 在 [管理宣告] 中，展開 [宣告條件]。
2. 選取使用者類型。
3. 選取該使用者應隸屬的群組。 針對指定應用程式，您在所有宣告上最多可以選取 50 個唯一群組。
4. 選取宣告要擷取其值的來源。 您可以從來源屬性的下拉式清單中選取使用者屬性，或將轉換套用至使用者屬性。 您也可以先選取目錄架構擴充 (預覽)，再發出作為宣告。

您新增條件的順序很重要。 Microsoft Entra 會先以來源 Attribute 評估所有條件，然後以來源 Transformation 評估所有條件，以決定要在宣告中發出哪個值。 具有相同來源的條件會從上到下進行評估。 符合運算式的最後一個值會在宣告中發出。 轉換 (例如 IsNotEmpty 和 Contains) 的行為類似於限制。

例如，Britta Simon 是 Contoso 租用戶中的來賓使用者。 Britta 隸屬同樣也使用 Microsoft Entra ID 的另一個組織。 在針對 Fabrikam 應用程式套用下列設定的情況下，當 Britta 嘗試登入 Fabrikam 時，Microsoft 身分識別平台會評估條件。

首先，Microsoft 身分識別平台會驗證 Britta 的使用者類型是否為 [所有來賓]。 因為類型為 [所有來賓]，Microsoft 身分識別平台會將宣告的來源指派給 user.extensionattribute1。 其次，Microsoft 身分識別平台會驗證 Britta 的使用者類型是否為 [Microsoft Entra 來賓]。 因為類型為 [所有來賓]，Microsoft 身分識別平台會將宣告的來源指派給 user.mail。 最後，系統會針對 Britta 使用 user.mail 值發出宣告。

另舉一個範例，請考慮 Britta Simon 何時嘗試登入，並使用下列設定。 首先，會使用 Attribute 的來源評估所有條件。 因為 Britta 的使用者類型為 [Microsoft Entra 來賓]，user.mail 會指派為宣告的來源。 接下來，會評估轉換。 因為 Britta 是來賓，user.extensionattribute1 現在是宣告的新來源。 因為 Britta 是 [Microsoft Entra 來賓]，user.othermail 現在是此宣告的來源。 最後，系統會針對 Britta 使用 user.othermail 值發出宣告。

最後一個範例是，考慮假設 Britta 尚未設定 user.othermail 或其為空白時，會發生什麼事。 在這兩種情況下，會忽略條件項目，而宣告會改回 user.extensionattribute1。

進階 SAML 宣告選項

您可以為 SAML2.0 應用程式設定進階宣告選項，以對 OIDC 權杖公開相同的宣告，也可以為想要針對 SAML2.0 和 OIDC 回應權杖使用相同宣告的應用程式進行設定。

在 [管理宣告] 刀鋒視窗中核取 [進階 SAML 宣告選項] 底下的方塊，即可設定進階宣告選項。

下表列出可為應用程式設定的其他進階選項。

選項	描述
將應用程式識別碼附加到簽發者	自動將應用程式識別碼新增至簽發者宣告。 當同一應用程式有多個執行個體時，此選項可確保每個執行個體的唯一宣告值。 如果未為應用程式設定自訂簽署金鑰，則會忽略此設定。
覆寫對象宣告	允許覆寫傳送至應用程式的對象宣告。 提供的值必須為有效的絕對 URI。 如果未為應用程式設定自訂簽署金鑰，則會忽略此設定。
包含屬性名稱格式	如果已選取，Microsoft Entra ID 會新增名為 NameFormat 的屬性，以描述此應用程式受限、核心及選擇性宣告的名稱格式。 如需詳細資訊，請參閱宣告對應原則類型

相關內容

• 對不存在於 Microsoft Entra 應用程式庫的應用程式設定單一登入