自訂 SAML 令牌宣告
Microsoft 身分識別平台 支援單一登錄（SSO），其中包含應用連結庫中大部分預先整合的應用程式和自定義應用程式。 當使用者使用 SAML 2.0 通訊協定透過 Microsoft 身分識別平台 向應用程式進行驗證時，會將令牌傳送至應用程式。 應用程式會驗證並使用令牌來登入使用者，而不是提示輸入使用者名稱和密碼。
這些 SAML 權杖包含使用者相關的一些資訊 (稱為「宣告」)。 宣告是識別提供者在發給使用者的權杖內用以描述使用者的資訊。 在 SAML 令牌中，宣告數據通常會包含在 SAML 屬性語句中。 使用者的唯一標識碼通常以 SAML 主體來表示，這也稱為名稱識別碼 （nameID）。
根據預設，Microsoft 身分識別平台 向應用程式發出 SAML 令牌，該應用程式包含使用者使用者名稱值（也稱為使用者主體名稱）的宣告，此名稱可以唯一識別使用者。 SAML 令牌也包含其他宣告，其中包含使用者的電子郵件位址、名字和姓氏。
檢視或編輯宣告
若要檢視或編輯在 SAML 令牌中對應用程式發出的宣告：
- 以至少雲端應用程式 管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
- 流覽至 [身分>識別應用程式>企業應用程式>] [所有應用程式]。
- 選取應用程式，在左側功能表中選取 [單一登錄]，然後選取 [屬性與宣告] 區段中的 [編輯]。
您可能需要編輯 SAML 令牌中發出的宣告，原因如下：
- 應用程式需要
NameIdentifier或nameID宣告為用戶名稱以外的專案（或用戶主體名稱）。 - 應用程式是設計為要求不同的宣告 URI 組或宣告值。
編輯 nameID
若要編輯名稱識別碼值宣告：
- 開啟 [ 名稱識別碼值 ] 頁面。
- 選取您要套用至屬性的屬性或轉換。 您可以選擇性地指定您希望
nameID宣告擁有的格式。
NameID 格式
如果 SAML 要求包含具有特定格式的專案NameIDPolicy，則 Microsoft 身分識別平台 會接受要求中的格式。
如果 SAML 要求不包含的NameIDPolicy元素，則 Microsoft 身分識別平台 會以您指定的格式發出 nameID 。 如果未指定任何格式，Microsoft 身分識別平台 會使用與所選取宣告來源相關聯的預設來源格式。 如果轉換產生 Null 或非法值，Microsoft Entra ID 會在 中 nameID傳送永續性成對標識符。
從 [ 選擇名稱識別符格式] 下拉式清單中，選取下表中的其中一個選項。
nameID 格式 |
描述 |
|---|---|
| Default | Microsoft 身分識別平台 會使用預設來源格式。 |
| 持續 | Microsoft 身分識別平台 使用 Persistent 做為nameID格式。 |
| 電子郵件地址 | Microsoft 身分識別平台 使用 EmailAddress 做為nameID格式。 |
| 未指定 | Microsoft 身分識別平台 使用 Unspecified 做為nameID格式。 |
| Windows 網域限定名稱 | Microsoft 身分識別平台 會使用 WindowsDomainQualifiedName 格式。 |
也支持暫時性 nameID ，但無法在下拉式清單中使用，且無法在 Azure 端設定。 若要深入瞭解 NameIDPolicy 屬性，請參閱 單一登錄 SAML 通訊協定。
屬性
提示
本文中的步驟可能會根據您從開始的入口網站稍有不同。
選取 （或nameID） 宣告所需的來源NameIdentifier。 您可以從下表中的選項中選取。
| 名稱 | 描述 |
|---|---|
Email |
使用者的電子郵件地址。 |
userprincipalName |
使用者的使用者主要名稱 (UPN)。 |
onpremisessamaccountname |
已從內部部署 Microsoft Entra 識別碼同步的 SAM 帳戶名稱。 |
objectid |
Microsoft Entra ID 中用戶的物件識別碼。 |
employeeid |
用戶的員工標識碼。 |
Directory extensions |
使用 Microsoft Entra 連線 Sync 從 內部部署的 Active Directory 同步的目錄延伸模組。 |
Extension Attributes 1-15 |
用來擴充 Microsoft Entra 架構的內部部署擴充屬性。 |
pairwiseid |
使用者標識碼的持續性形式。 |
如需標識碼值的詳細資訊，請參閱本頁稍後列出每個來源的有效標識符值表格。
任何常數 （static） 值都可以指派給任何宣告。 使用下列步驟來指派常數值：
- 在 [ 屬性與宣告] 刀鋒視窗上，選取您想要修改的必要宣告。
- 根據您的組織輸入Source屬性中不含引號的常數值，然後選取 [儲存]。 常數值隨即顯示。
目錄架構延伸模組 （預覽）
您也可以將目錄架構擴充屬性設定為非條件式/條件屬性。 使用下列步驟，將單一或多重值目錄架構擴充屬性設定為宣告：
- 在 [ 屬性與宣告] 刀鋒視窗上，選取 [新增宣告 ] 或編輯現有的宣告。
- 從定義擴充屬性的應用程式選擇器選取來源應用程式。
- 選取 [新增 ] 以將選取專案新增至宣告。
- 按兩下 [ 儲存 ] 認可變更。
特殊宣告轉換
您可以使用下列特殊宣告轉換函式。
| 函式 | 描述 |
|---|---|
| ExtractMailPrefix（） | 從電子郵件地址或用戶主體名稱中移除網域後綴。 此函式只會擷取傳遞的用戶名稱第一個部分（例如，“joe_smith”， joe_smith@contoso.com而不是 ）。 |
| ToLower（） | 將選取屬性的字元轉換成小寫字元。 |
| ToUpper（） | 將選取屬性的字元轉換成大寫字元。 |
新增應用程式特定的宣告
若要新增應用程式特定的宣告：
- 在 [ 屬性與宣告] 刀鋒視窗上，選取 [新增宣告 ] 以開啟 [ 管理使用者宣告 ] 頁面。
- 輸入宣告的名稱。 根據 SAML 規格，此值不需要遵循 URI 模式。如果您需要 URI 模式，您可以將該 模式放在 [命名空間 ] 字段中。
- 選取宣告要擷取其值的來源。 您可以使用來源屬性下拉式選單中的屬性，或對使用者屬性套用轉換再發出為宣告。
宣告轉換
若要將轉換套用至使用者屬性：
- 在 [管理宣告] 中，選取 [轉換] 作為宣告來源，以開啟 [管理轉換] 頁面。
- 從轉換下拉式清單中選取函式。 根據選取的函式，提供參數和常數值，以在轉換中進行評估。
- 按兩下適當的單選按鈕，以選取屬性的來源。 目錄架構延伸模組來源目前為預覽狀態。
- 從下拉式清單中選取屬性名稱。
- 將來源視為多重值 是一個複選框，指出轉換是否應套用至所有值或只套用第一個值。 根據預設，轉換只會套用至多重值宣告中的第一個專案，方法是核取此方塊，以確保它已套用至所有專案。 只針對多重值屬性啟用此複選框， 例如
user.proxyaddresses。 - 若要套用多個轉換，請選取 [ 新增轉換]。 您可以將最多兩個轉換套用至宣告。 例如，您可以先擷取 的電子郵件前置詞
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。 |
| 子字串（） - 固定長度 （預覽） | 擷取字串宣告類型的部分，從指定位置的字元開始，並傳回指定的字元數。 sourceClaim是應該執行的轉換宣告來源。 StartIndex是這個實例中子字串以零起始的起始字元位置。 Length是子字串的字元長度。 例如， sourceClaim - PleaseExtractThisNowStartIndex - 6與 Length - 11 會產生的ExtractThis輸出。 |
| Substring（） - EndOfString （預覽） | 擷取字串宣告類型的部分，從指定位置的字元開始，並從指定的開始索引傳回宣告的其餘部分。 sourceClaim是應該執行的轉換宣告來源。 StartIndex是這個實例中子字串以零起始的起始字元位置。 例如， sourceClaim - PleaseExtractThisNow 和 StartIndex - 6 會產生的 ExtractThisNow輸出。 |
| RegexReplace（） （預覽） | 如需以 regex 為基礎的宣告轉換的詳細資訊，請參閱下一節。 |
以 Regex 為基礎的宣告轉換
下圖顯示第一層轉換的範例：
下表所列的動作提供第一層轉換的相關信息，並對應至上一個影像中的標籤。 選取 [編輯 ] 以開啟宣告轉換刀鋒視窗。
| 動作 | 欄位 | 描述 |
|---|---|---|
1 |
Transformation |
從 [轉換] 選項中選取 RegexReplace（） 選項，以針對宣告轉換使用以 regex 為基礎的宣告轉換方法。 |
2 |
Parameter 1 |
正則表達式轉換的輸入。 例如，具有使用者電子郵件位址的user.mail，例如 admin@fabrikam.com。 |
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 |
如果選取的輸入參數不再需要，管理員 istrators 可以刪除它。 |
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 標識符的另一個組織。
- 外部來賓：來賓用戶屬於沒有 Microsoft Entra 標識碼的外部組織。
其中一個使用者類型很有説明的案例，就是當來賓和存取應用程式的員工宣告來源不同時。 您可以指定如果使用者是員工，則 NameID 的來源為 user.email。 如果使用者是來賓，則 NameID 的來源為 user.extensionattribute1。
若要新增宣告條件：
- 在 [管理宣告] 中，展開 [宣告條件]。
- 選取用戶類型。
- 選取用戶應該所屬的群組。。 您可以在指定應用程式的所有宣告中選取最多 50 個唯一群組。
- 選取宣告要擷取其值的來源。 您可以從來源屬性的下拉式清單中選取使用者屬性，或將轉換套用至用戶屬性。 您也可以先選取目錄架構延伸模組（預覽），再發出目錄架構延伸模組作為宣告。
您新增條件的順序很重要。 Microsoft Entra 會先評估來源的所有條件，然後使用來源AttributeTransformation評估所有條件，以決定要在宣告中發出的值。 具有相同來源的條件會從上到下進行評估。 符合宣告中發出表達式的最後一個值。 和 之類的IsNotEmptyContains轉換會像限制一樣。
例如，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 的屬性，其描述名稱格式為應用程式的限制、核心和選擇性宣告。 如需詳細資訊，請參閱 宣告對應原則類型 |