共用方式為

使用原則的宣告自定義

  • 發行項

原則物件代表個別應用程式或組織中所有應用程式上強制執行的一組規則。 每個類型的原則都具有包含一組屬性的獨特結構，這些屬性會接著套用至它們已被指派的物件。

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 除了基本宣告集和核心宣告集之外，還會定義原則所影響的權杖中的宣告。 此屬性中所定義的每個宣告結構描述項目必須有某些資訊。 指定資料的來源([值]、[來源/識別碼配對] 或 [來源/ExtensionID 配對]) 以及所發出的 [宣告類型] ([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
  • 來源/識別碼配對：定義宣告中資料的來源位置。
  • 來源/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 使用者的傳真電話號碼。
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
  • 摘要：使用此屬性可將常見的轉換套用至來源資料，為宣告結構描述中所指定的宣告產生輸出資料。
  • ID：參考 TransformationID 宣告結構描述項目中的轉換項目。 對於這項原則內的每個轉換項目，此值都必須是唯一的。
  • TransformationMethod：識別執行以產生宣告資料的作業。

根據您所選擇的方法，系統預期會有一組輸入和輸出。 您可以使用 InputClaims、InputParameters 和 OutputClaims 元素定義這些輸入和輸出。

TransformationMethod 預期的輸入 預期的輸出 描述
聯結 string1、string2、分隔符號 輸出宣告 可在輸入字串之間使用分隔符號來聯結這些字串。 例如，string1:foo@bar.com、string2:sandbox、separator:. 會導出輸出宣告：foo@bar.com.sandbox。
ExtractMailPrefix 電子郵件或 UPN 解壓縮的字串 擴充屬性 1-15 或任何其他目錄擴充，其會儲存使用者的 UPN 或電子郵件地址值。 例如： johndoe@contoso.com 。 擷取電子郵件地址的本機部分。 例如，mail:foo@bar.com 會導致輸出宣告：foo。 如果沒有 @ 符號，則會傳回原始輸入字串。
ToLowercase() 字串 輸出字串 將所選取屬性中的字元轉換成小寫字元。
ToUppercase() 字串 輸出字串 將所選取屬性中的字元轉換成大寫字元。
RegexReplace() RegexReplace() 轉換接受作為輸入參數：
- 參數 1：作為 RegEx 輸入的使用者屬性
- 信任來源作為多重值的選項
- Regex 模式
- 取代模式。 取代模式可能會包含靜態文字格式，以及指向 RegEx 輸出群組和其他輸入參數的參考。
  • InputClaims：用來將資料從宣告結構描述項目傳遞至轉換。 其有三種屬性：ClaimTypeReferenceId、TransformationClaimType 和 TreatAsMultiValue。
    • ClaimTypeReferenceId：與宣告結構描述項目的 ID 元素聯結，以尋找適當的輸入宣告。
    • TransformationClaimType 提供此輸入的唯一名稱。 此名稱必須符合轉換方法的其中一個預期輸入。
    • TreatAsMultiValue 是布林值旗標，指出應該將轉換套用至所有值還是只套用至第一個值。 根據預設，只會將轉換套用至多重值宣告中的第一個元素。 將此值設定為 true 可確保將其套用至全部。 ProxyAddresses 和 groups 是輸入宣告的兩個範例，您可能會想要將其視為多重值宣告。
  • InputParameters：將常數值傳遞至轉換。 它有兩個屬性：值和識別碼。
    • 值是要傳遞的實際常數值。
    • 識別碼可用來為此輸入指定唯一的名稱。 名稱必須符合轉換方法的其中一個預期輸入。
  • 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。 如果未為應用程式設定自訂簽署金鑰，則會忽略此設定。

下一步