共用方式為

使用原則的宣告自定義

  • 發行項

原則物件代表在個別應用程式或組織中所有應用程式上強制執行的一組規則。 每種原則類型都有唯一的結構，並具有一組屬性，然後套用至指派物件。

Microsoft Entra ID 支援兩種方式，針對您的應用程式使用 Microsoft Graph/PowerShell 來自定義宣告：

自定義宣告原則和宣告對應原則是兩種不同類型的原則物件，可修改令牌中包含的宣告。

自定義宣告原則（預覽版） 可讓系統管理員自定義其應用程式的其他宣告。 它可以與 透過 Microsoft Entra 系統管理中心所提供的宣告自定義 來交換使用，讓系統管理員可以透過 Microsoft Entra 系統管理中心或 MS Graph/PowerShell 來管理宣告。 透過 Microsoft Entra 系統管理中心提供的自定義宣告原則和 宣告自定義 ，都會使用相同的基礎原則來設定服務主體的其他宣告。 不過，系統管理員只能為每個服務主體設定一個自定義宣告原則（預覽）。 PUT方法可讓系統管理員建立或取代現有的原則物件，並將它取代為在要求本文中傳遞的值，而 PATCH 方法可讓系統管理員將原則物件更新為要求本文中傳遞的值。 在這裡 瞭解如何使用自定義宣告原則來設定和管理 其他宣告。

宣告對應原則 也允許系統管理員為其應用程式自定義其他宣告。 系統管理員可以設定一個宣告對應原則，並將其指派給其租使用者中的多個應用程式。 如果系統管理員選擇使用宣告對應原則來管理應用程式的其他宣告，他們將無法編輯或更新 這些應用程式的宣告自定義 刀鋒視窗中的宣告，Microsoft Entra 系統管理中心。 在這裡瞭解如何使用宣告對應原則來設定和管理其他宣告。

注意

宣告對應原則會取代自定義宣告原則，以及 透過 Microsoft Entra 系統管理中心提供的宣告自定義 。 使用宣告對應原則自定義應用程式的宣告，表示針對該應用程式發出的令牌會忽略 [自定義宣告原則] 中的設定，或 Microsoft Entra 系統管理中心上 宣告自定義 刀鋒視窗中的設定。 如需宣告自定義的詳細資訊，請參閱 自定義企業應用程式令牌中發出的宣告。

宣告集

下表列出定義令牌中使用方式和時機的宣告集。

宣告集 描述
核心宣告集 不論原則為何，都會出現在每個令牌中。 這些宣告也會被視為受限制，且無法修改。
基本宣告集 除了核心宣告集之外，也包含令牌預設包含的宣告。 您可以使用自定義宣告原則和宣告對應原則來省略或修改基本宣告。
限制宣告集 無法使用原則進行修改。 資料來源無法變更，且在產生這些宣告時不會套用任何轉換。

JSON Web 令牌 （JWT） 受限制的宣告集

下列宣告位於 JWT 的限制宣告集中。

  • .
  • _claim_names
  • _claim_sources
  • aai
  • access_token
  • account_type
  • acct
  • acr
  • acrs
  • actor
  • actortoken
  • ageGroup
  • aio
  • altsecid
  • amr
  • app_chain
  • app_displayname
  • app_res
  • appctx
  • appctxsender
  • appid
  • appidacr
  • assertion
  • at_hash
  • aud
  • auth_data
  • auth_time
  • authorization_code
  • azp
  • azpacr
  • bk_claim
  • bk_enclave
  • bk_pub
  • brk_client_id
  • brk_redirect_uri
  • c_hash
  • ca_enf
  • ca_policy_result
  • capolids
  • capolids_latebind
  • cc
  • cert_token_use
  • child_client_id
  • child_redirect_uri
  • client_id
  • client_ip
  • cloud_graph_host_name
  • cloud_instance_host_name
  • cloud_instance_name
  • CloudAssignedMdmId
  • cnf
  • code
  • controls
  • controls_auds
  • credential_keys
  • csr
  • csr_type
  • ctry
  • deviceid
  • dns_names
  • domain_dns_name
  • domain_netbios_name
  • e_exp
  • email
  • endpoint
  • enfpolids
  • exp
  • expires_on
  • extn. as prefix
  • fido_auth_data
  • fido_ver
  • fwd
  • fwd_appidacr
  • grant_type
  • graph
  • group_sids
  • groups
  • hasgroups
  • hash_alg
  • haswids
  • home_oid
  • home_puid
  • home_tid
  • iat
  • identityprovider
  • idp
  • idtyp
  • in_corp
  • instance
  • inviteTicket
  • ipaddr
  • isbrowserhostedapp
  • iss
  • isViral
  • jwk
  • key_id
  • key_type
  • login_hint
  • mam_compliance_url
  • mam_enrollment_url
  • mam_terms_of_use_url
  • mdm_compliance_url
  • mdm_enrollment_url
  • mdm_terms_of_use_url
  • msgraph_host
  • msproxy
  • nameid
  • nbf
  • netbios_name
  • nickname
  • nonce
  • oid
  • on_prem_id
  • onprem_sam_account_name
  • onprem_sid
  • openid2_id
  • origin_header
  • password
  • platf
  • polids
  • pop_jwk
  • preferred_username
  • previous_refresh_token
  • primary_sid
  • prov_data
  • puid
  • pwd_exp
  • pwd_url
  • rdp_bt
  • redirect_uri
  • refresh_token
  • refresh_token_issued_on
  • refreshtoken
  • request_nonce
  • resource
  • rh
  • role
  • roles
  • rp_id
  • rt_type
  • scope
  • scp
  • secaud
  • sid
  • sid
  • signature
  • signin_state
  • source_anchor
  • src1
  • src2
  • sub
  • target_deviceid
  • tbid
  • tbidv2
  • tenant_ctry
  • tenant_display_name
  • tenant_id
  • tenant_region_scope
  • tenant_region_sub_scope
  • thumbnail_photo
  • tid
  • tokenAutologonEnabled
  • trustedfordelegation
  • ttr
  • unique_name
  • upn
  • user_agent
  • user_setting_sync_url
  • username
  • uti
  • ver
  • verified_primary_email
  • verified_secondary_email
  • vnet
  • vsm_binding_key
  • wamcompat_client_info
  • wamcompat_id_token
  • wamcompat_scopes
  • wids
  • win_ver
  • x5c_ca
  • xcb2b_rclient
  • xcb2b_rcloud
  • xcb2b_rtenant
  • ztdid

注意

開頭 xms_ 的任何宣告都受到限制。

SAML 限制宣告集

下表列出限制宣告集中的SAML宣告。

限制宣告類型 （URI）：

  • http://schemas.microsoft.com/2012/01/devicecontext/claims/ismanaged
  • http://schemas.microsoft.com/2014/02/devicecontext/claims/isknown
  • http://schemas.microsoft.com/2014/03/psso
  • http://schemas.microsoft.com/2014/09/devicecontext/claims/iscompliant
  • http://schemas.microsoft.com/claims/authnmethodsreferences
  • http://schemas.microsoft.com/claims/groups.link
  • http://schemas.microsoft.com/identity/claims/accesstoken
  • http://schemas.microsoft.com/identity/claims/acct
  • http://schemas.microsoft.com/identity/claims/agegroup
  • http://schemas.microsoft.com/identity/claims/aio
  • http://schemas.microsoft.com/identity/claims/identityprovider
  • http://schemas.microsoft.com/identity/claims/objectidentifier
  • http://schemas.microsoft.com/identity/claims/openid2_id
  • http://schemas.microsoft.com/identity/claims/puid
  • http://schemas.microsoft.com/identity/claims/scope
  • http://schemas.microsoft.com/identity/claims/tenantid
  • http://schemas.microsoft.com/identity/claims/xms_et
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationinstant
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/confirmationkey
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlyprimarygroupsid
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlyprimarysid
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlywindowsdevicegroup
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/expiration
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/expired
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/ispersistent
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/role
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/role
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/samlissuername
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/wids
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsdeviceclaim
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsdevicegroup
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsfqbnversion
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/windowssubauthority
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsuserclaim
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/authentication
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/authorizationdecision
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/denyonlysid
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/spn
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
  • http://schemas.xmlsoap.org/ws/2009/09/identity/claims/actor

這些宣告預設會受到限制，但如果您有 自定義簽署密鑰，則不會受到限制。 避免在應用程式指令清單中設定 acceptMappedClaims 。

  • http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/primarygroupsid
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/sid
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/x500distinguishedname

這些宣告預設會受到限制，但如果您有 自定義簽署密鑰，則不會受到限制：

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
  • http://schemas.microsoft.com/ws/2008/06/identity/claims/role

用於宣告自定義的原則屬性

若要控制包含的宣告，以及數據的來源，請使用原則的屬性進行宣告自定義。 如果沒有原則，系統就會發出具有下列宣告的令牌：

  • 核心宣告集。
  • 基本宣告集。
  • 應用程式選擇接收的任何 選擇性宣告 。

注意

核心宣告集中的宣告存在於每個令牌中，不論此屬性設定為什麼。

String 資料類型 摘要
IncludeBasicClaimSet 布林值 （True 或 False） 判斷基本宣告集是否包含在受此原則影響的令牌中。 如果設定為 True，則基本宣告集中的所有宣告都會在受原則影響的令牌中發出。 如果設定為 False，則基本宣告集中的宣告不在令牌中，除非這些宣告是在相同原則的宣告架構屬性中個別新增。
ClaimsSchema 具有一或多個宣告架構專案的 JSON Blob 除了基本宣告集和核心宣告集之外，定義受原則影響之令牌中的宣告。 針對此屬性中定義的每個宣告架構專案，需要特定資訊。 指定數據來自何處（Value、Source/ID pair 或 Source/ExtensionID pair），以及發出為 （JWTClaimType 或 SamlClaimType） 的宣告類型。

宣告架構專案專案

  • Value - 將靜態值定義為宣告中要發出的數據。
  • SAMLNameForm - 定義此宣告之 NameFormat 屬性的值。 如果存在，允許的值為：
    • urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified
    • urn:oasis:names:tc:SAML:2.0:attrname-format:uri
    • urn:oasis:names:tc:SAML:2.0:attrname-format:basic
  • 來源/標識元組 - 定義宣告中的數據來源位置。
  • Source/ExtensionID 配對 - 定義宣告中數據的來源目錄延伸模組屬性。 如需詳細資訊，請參閱 在宣告中使用目錄擴充屬性。
  • 宣告類型 - JwtClaimType 和 SamlClaimType 元素會定義此宣告架構專案所參考的宣告。
    • JwtClaimType 必須包含 JWT 中要發出的宣告名稱。
    • SamlClaimType 必須包含 SAML 令牌中要發出之宣告的 URI。

將 Source 元素設定為下表中的其中一個值。

來源值 宣告中的數據
user User 物件上的 屬性。
application 應用程式 （用戶端） 服務主體上的屬性。
resource 資源服務主體上的屬性。
audience 服務主體上的 屬性，這是令牌的物件（用戶端或資源服務主體）。
company 資源租使用者的 Company 物件上的 屬性。
transformation 宣告轉換。 當您使用此宣告時， TransformationID 元素必須包含在宣告定義中。 TransformationID 元素必須符合 ClaimsTransformation 屬性中轉換專案的 ID 元素，以定義如何產生宣告的數據。

ID 元素會識別來源上的 屬性，該屬性會提供宣告的值。 下表列出Source每個值的ID元素值。

來源 識別碼 描述
user surname 使用者的系列名稱。
user givenname 使用者的名字。
user displayname 用戶的顯示名稱。
user objectid 使用者的物件識別碼。
user mail 使用者的電子郵件地址。
user userprincipalname 用戶的用戶主體名稱。
user department 使用者的部門。
user onpremisessamaccountname 用戶的內部部署 SAM 帳戶名稱。
user netbiosname 使用者的 NetBios 名稱。
user dnsdomainname 使用者的 DNS 功能變數名稱。
user onpremisesecurityidentifier 用戶的內部部署安全性標識碼。
user companyname 用戶的組織名稱。
user streetaddress 使用者的街道位址。
user postalcode 使用者的郵遞區號。
user preferredlanguage 使用者慣用的語言。
user onpremisesuserprincipalname 用戶的內部部署UPN。 當您使用替代識別碼時，內部部署屬性 userPrincipalName 會與 onPremisesUserPrincipalName 屬性同步處理。 只有在設定替代識別碼時，才能使用這個屬性。
user mailnickname 用戶的郵件暱稱。
user extensionattribute1 擴充屬性 1。
user extensionattribute2 擴充屬性 2。
user extensionattribute3 擴充屬性 3。
user extensionattribute4 擴充屬性 4。
user extensionattribute5 擴充屬性 5。
user extensionattribute6 擴充屬性 6。
user extensionattribute7 擴充屬性 7。
user extensionattribute8 擴充屬性 8。
user extensionattribute9 擴充屬性 9。
user extensionattribute10 擴充屬性 10。
user extensionattribute11 擴充屬性 11。
user extensionattribute12 擴充屬性 12。
user extensionattribute13 擴充屬性 13。
user extensionattribute14 擴充屬性 14。
user extensionattribute15 擴充屬性 15。
user othermail 使用者的其他郵件。
user country 用戶的國家/地區。
user city 使用者的城市。
user state 使用者的縣/市。
user jobtitle 用戶的職稱。
user employeeid 使用者的員工識別碼。
user facsimiletelephonenumber 使用者的 facsimile 電話號碼。
user assignedroles 指派給使用者的應用程式角色清單。
user accountEnabled 指出是否啟用用戶帳戶。
user consentprovidedforminor 指出是否為未成年人提供同意。
user createddatetime 用戶帳戶建立的日期和時間。
user creationtype 指出用戶帳戶的建立方式。
user lastpasswordchangedatetime 密碼變更的最後日期和時間。
user mobilephone 用戶的行動電話。
user officelocation 用戶的辦公室位置。
user onpremisesdomainname 用戶的內部部署功能變數名稱。
user onpremisesimmutableid 用戶的內部部署不可變標識碼。
user onpremisessyncenabled 指出是否啟用內部部署同步處理。
user preferreddatalocation 定義使用者慣用的數據位置。
user proxyaddresses 使用者的 Proxy 位址。
user usertype 用戶帳戶的類型。
user telephonenumber 用戶的商務或辦公室電話。
application、 、 resourceaudience displayname 對象的顯示名稱。
application、 、 resourceaudience objectid 對象的識別碼。
application、 、 resourceaudience tags 對象的服務主體標記。
company tenantcountry 租用戶的國家/地區。

用戶物件上唯一可用的多重值宣告來源是已從 Active Directory Connect 同步處理的多重值擴充屬性。 其他屬性，例如 othermails 和 tags，都是多重值，但在選取為來源時，只會發出一個值。

限制宣告集中宣告的名稱和 URI 無法用於宣告類型專案。

群組篩選

  • 字串 - GroupFilter
  • 數據類型： - JSON Blob
  • 摘要 - 使用此屬性對要包含在群組宣告中的使用者群組套用篩選。 這個屬性可以是減少令牌大小的實用方法。
  • MatchOn： - 識別要套用篩選的群組屬性。 將 MatchOn 屬性設定為下列其中一個值：
    • displayname - 群組顯示名稱。
    • samaccountname - 內部部署 SAM 帳戶名稱。
  • 類型 - 定義套用至 MatchOn 屬性所選取屬性的篩選條件類型。 將 Type 屬性設定為下列其中一個值：
    • prefix- 包含 MatchOn 屬性開頭為所提供 Value 屬性的群組。
    • suffix包含 MatchOn 屬性結尾為所提供 Value 屬性的群組。
    • contains- 包含 MatchOn 屬性包含與所提供 Value 屬性的群組。

宣告轉換

  • 字串 - ClaimsTransformation
  • 數據類型 - 具有一或多個轉換專案的 JSON Blob
  • 摘要 - 使用此屬性將一般轉換套用至源數據，以產生宣告架構中所指定宣告的輸出數據。
  • 標識碼 - 參考 TransformationID 宣告架構專案中的轉換專案。 對於此原則中的每個轉換項目，這個值必須是唯一的。
  • TransformationMethod - 識別執行以產生宣告數據的作業。

根據所選擇的方法，預期會有一組輸入和輸出。 使用 InputClaims、 InputParameters 和 OutputClaims 元素來定義輸入和輸出。

TransformationMethod 預期的輸入 預期的輸出 描述
聯結 string1， string2， separator 輸出宣告 在之間使用分隔符聯結輸入字串。 例如，string1：、string2：foo@bar.comsandbox、分隔符：.會產生輸出宣告：foo@bar.com.sandbox。
ExtractMailPrefix 電子郵件或UPN 擷取的字串 擴充屬性 1-15 或任何其他目錄延伸模組，其會儲存使用者的 UPN 或電子郵件位址值。 例如： johndoe@contoso.com 。 擷取電子郵件位址的本機部分。 例如，郵件：foo@bar.com 會產生輸出宣告：foo。 如果沒有 @ 符號，則會傳回原始輸入字串。
ToLowercase() 字串 輸出字串 將所選取屬性中的字元轉換成小寫字元。
ToUppercase() 字串 輸出字串 將所選取屬性中的字元轉換成大寫字元。
RegexReplace（） RegexReplace（） 轉換接受做為輸入參數：
- 參數 1：使用者屬性作為 regex 輸入
- 信任來源為多重值的選項
- Regex 模式
- 取代模式。 取代模式可能包含靜態文字格式，以及指向 regex 輸出群組和更多輸入參數的參考。
  • InputClaims - 用來將數據從宣告架構專案傳遞至轉換。 它有三個屬性：ClaimTypeReferenceId、TransformationClaimType 和 TreatAsMultiValue。
    • ClaimTypeReferenceId - 與宣告架構專案的 ID 元素聯結，以尋找適當的輸入宣告。
    • TransformationClaimType 提供此輸入的唯一名稱。 此名稱必須符合轉換方法的其中一個預期輸入。
    • TreatAsMultiValue 是布爾值旗標，指出轉換應套用至所有值，還是只套用第一個值。 根據預設，轉換只會套用至多重值宣告中的第一個專案。 將此值設定為 true 可確保其全部套用。 ProxyAddresses 和 groups 是輸入宣告的兩個範例，您可能想要視為多重值宣告。
  • InputParameters - 將常數值傳遞至轉換。 它有兩個屬性： 值 和 標識碼。
    • Value 是要傳遞的實際常數值。
    • 標識碼 是用來為輸入提供唯一的名稱。 名稱必須符合轉換方法的其中一個預期輸入。
  • OutputClaims - 保存轉換所產生的數據，並將它系結至宣告架構專案。 它有兩個屬性： ClaimTypeReferenceId 和 TransformationClaimType。
    • ClaimTypeReferenceId 會聯結宣告架構專案的標識碼，以尋找適當的輸出宣告。
    • TransformationClaimType 可用來為輸出提供唯一的名稱。 名稱必須符合轉換方法的其中一個預期輸出。

例外狀況和限制

SAML NameID 和 UPN - 來源 NameID 和 UPN 值的屬性，以及允許的宣告轉換會受到限制。

來源 識別碼 描述
user mail 使用者的電子郵件地址。
user userprincipalname 用戶的用戶主體名稱。
user onpremisessamaccountname 內部部署 Sam 帳戶名稱
user employeeid 使用者的員工識別碼。
user telephonenumber 用戶的商務或辦公室電話。
user extensionattribute1 擴充屬性 1。
user extensionattribute2 擴充屬性 2。
user extensionattribute3 擴充屬性 3。
user extensionattribute4 擴充屬性 4。
user extensionattribute5 擴充屬性 5。
user extensionattribute6 擴充屬性 6。
user extensionattribute7 擴充屬性 7。
user extensionattribute8 擴充屬性 8。
user extensionattribute9 擴充屬性 9。
user extensionattribute10 擴充屬性 10。
user extensionattribute11 擴充屬性 11。
user extensionattribute12 擴充屬性 12。
user extensionattribute13 擴充屬性 13。
user extensionattribute14 擴充屬性 14。
User extensionattribute15 擴充屬性 15。

下表所列的轉換方法允許 SAML NameID 使用。

TransformationMethod 限制
ExtractMailPrefix 無
聯結 要加入的後綴必須是資源租使用者的已驗證網域。

具有應用程式識別碼的簽發者

  • 字串 - issuerWithApplicationId
  • 資料類型 - 布林值 （True 或 False）
    • 如果設定為 True，應用程式標識碼就會新增至受原則影響之令牌中的簽發者宣告。
    • 如果設定為 False，則應用程式標識碼不會新增至受原則影響之令牌中的簽發者宣告。 (預設值)
  • 摘要 - 可讓應用程式識別碼包含在簽發者宣告中。 確保相同應用程式的多個實例針對每個實例都有唯一的宣告值。 如果未為應用程式設定自訂簽署金鑰，則會忽略此設定。

物件覆寫

  • 字串 - audienceOverride
  • 數據類型 - 字串
  • 摘要 - 可讓您覆寫傳送至應用程式的物件宣告。 提供的值必須為有效的絕對 URI。 如果未為應用程式設定任何自定義簽署金鑰，則會忽略此設定。

下一步

  • 若要深入瞭解擴充屬性，請參閱 宣告中的目錄擴充屬性。