ClaimsPrincipal 類別

定義

命名空間:

System.Security.Claims

組件:

System.Security.Claims.dll

來源:

ClaimsPrincipal.cs

IPrincipal 實作，其支援多個宣告式身分識別。

public ref class ClaimsPrincipal : System::Security::Principal::IPrincipal

public class ClaimsPrincipal : System.Security.Principal.IPrincipal

type ClaimsPrincipal = class
    interface IPrincipal

Public Class ClaimsPrincipal
Implements IPrincipal

繼承

Object

ClaimsPrincipal

衍生

System.Security.Principal.GenericPrincipal

System.Security.Principal.WindowsPrincipal

實作

IPrincipal

範例

下列範例會擷取 HTTP 要求中用戶呈現的宣告，並將其寫入 HTTP 回應。 目前使用者會從 HttpContext 讀取為 ClaimsPrincipal。 宣告接著會從中讀取，然後寫入回應。

if (HttpContext.Current.User is ClaimsPrincipal principal)
{
   foreach (Claim claim in principal.Claims)
   {
      Response.Write("CLAIM TYPE: " + claim.Type + "; CLAIM VALUE: " + claim.Value + "</br>");
   }
}

備註

從 .NET Framework 4.5 開始，Windows Identity Foundation (WIF) 和宣告型身分識別會完全整合到 .NET Framework。 這表示許多代表 .NET Framework 主體的類別現在衍生自 ClaimsPrincipal ，而不只是實作 IPrincipal 介面。 除了實作 IPrincipal 介面之外， ClaimsPrincipal 還會公開屬性和方法，這些屬性和方法可用於處理宣告。

ClaimsPrincipal 會公開身分識別的集合，其中每一個 ClaimsIdentity都是 。 在常見的案例中 Identities ，透過屬性存取的這個集合只會有單一元素。

在 .NET 4.5 中引進 ClaimsPrincipal 作為大部分主體類別衍生的來源主體，不會強制您變更任何處理身分識別的方式。 不過，它會開啟更多可能性，並提供更多機會來執行更精細的訪問控制。 例如：

• 應用程式程序代碼本身可以直接使用目前主體中包含的宣告，以驅動額外的驗證、授權和個人化工作。

• 您可以在資源前面加上宣告處理管線，即使在執行到達您的程式代碼之前，也可以處理驗證要求和授權原則。 例如，您可以使用自定義宣告驗證管理員來設定 Web 型應用程式或服務，這是衍生自 類別的 ClaimsAuthenticationManager 類別實例。 設定時，要求處理管線會在宣告驗證管理員上叫 Authenticate 用 方法，並將它傳遞為 ClaimsPrincipal ，代表傳入要求的內容。 您的宣告驗證管理員接著可以根據傳入宣告的值來執行驗證。 它也可以篩選、轉換或新增宣告至傳入宣告集。 例如，它可用來使用從本機數據源建立的新宣告來擴充傳入宣告集，例如本機使用者配置檔

• 您可以使用自定義宣告授權管理員來設定 Web 應用程式，這是衍生自 ClaimsAuthorizationManager 類別的類別實例。 設定時，要求處理管線會將傳入 ClaimsPrincipal 封裝在 中 AuthorizationContext ，並在宣告授權管理員上叫用 CheckAccess 方法。 您的宣告授權管理員接著可以根據傳入宣告強制執行授權。

• 您可以使用自定義宣告授權管理員設定應用程式，並使用 ClaimsPrincipalPermission 類別來執行命令式存取檢查，或 ClaimsPrincipalPermissionAttribute 執行宣告式存取檢查，即可執行內嵌宣告式程式碼存取檢查。 宣告型程式代碼存取檢查會在處理管線外部內嵌執行，因此只要已設定宣告授權管理員，所有應用程式都可以使用。

您可以在信賴憑證者 (RP) 應用程式中，取得ClaimsPrincipal與要求相關聯之主體的實例，或是線程執行所在的主體，方法是將 Thread.CurrentPrincipal 屬性ClaimsPrincipal轉換成 。 與對象相關聯的 ClaimsPrincipal 宣告可透過其 Claims 屬性取得。 屬性 Claims 會傳回與主體相關聯之身分識別所包含的所有宣告。 在包含多個ClaimsIdentity實例的罕見情況下ClaimsPrincipal，您可以使用 Identities 屬性，或使用 屬性來存取主要身分Identity識別。 ClaimsPrincipal 提供數種方法，可搜尋這些宣告，並完整支援語言整合式查詢 (LINQ) 。 您可以使用 或 AddIdentity 方法，將身分識別新增至主體AddIdentities。

注意

若要將身分識別新增至 ClaimsPrincipal，呼叫端必須具有完全信任。

根據預設，WIF 會在選取要透過 Identity 屬性傳回的主要身分識別時，設定物件的優先順序WindowsIdentity。 您可以透過 PrimaryIdentitySelector 屬性提供委派來執行選取專案，以修改此行為。 屬性 ClaimsPrincipalSelector 提供屬性的類似功能 Current 。

在宣告型模型中，主體是否處於指定角色，是由其基礎身分識別所呈現的宣告所決定。 方法 IsInRole 基本上會檢查與主體相關聯的每個身分識別，以判斷其是否擁有具有指定角色值的宣告。 宣告 (的類型，由其 Claim.Type 屬性所表示) 用來判斷角色檢查期間應該檢查哪些宣告是透過其 ClaimsIdentity.RoleClaimType 屬性在身分識別上指定。 因此，在角色檢查期間檢查的宣告可以是與主體相關聯之不同身分識別的不同類型。

建構函式

ClaimsPrincipal()	初始化 ClaimsPrincipal 類別的新執行個體。
ClaimsPrincipal(BinaryReader)	使用指定的 BinaryReader，初始化 ClaimsPrincipal 的執行個體。
ClaimsPrincipal(IEnumerable<ClaimsIdentity>)	使用指定的宣告身份識別，初始化 ClaimsPrincipal 類別的新執行個體。
ClaimsPrincipal(IIdentity)	從指定的識別初始化 ClaimsPrincipal 類別的新執行個體。
ClaimsPrincipal(IPrincipal)	從指定的主體，初始化 ClaimsPrincipal 類別的新執行個體。
ClaimsPrincipal(SerializationInfo, StreamingContext)	已淘汰. 從使用 ISerializable 建立的序列化資料流，初始化 ClaimsPrincipal 類別的新執行個體。

屬性

Claims	取得集合，其中包含來自與這個宣告主體相關聯的所有宣告身分識別之所有宣告。
ClaimsPrincipalSelector	取得或設定用來選取 Current 屬性所傳回宣告主體的委派。
Current	取得目前的宣告主體。
CustomSerializationData	包含衍生類型所提供的任何其他資料。 通常會在呼叫 WriteTo(BinaryWriter, Byte[]) 時設定。
Identities	取得集合，其中包含所有與這個宣告主體相關聯的宣告身分識別。
Identity	取得與這個宣告主體關聯的主要宣告身分識別。
PrimaryIdentitySelector	取得或設定用來選取 Identity 屬性所傳回宣告身分識別的委派。

方法

AddIdentities(IEnumerable<ClaimsIdentity>)	將指定的宣告識別加入這個宣告主體。
AddIdentity(ClaimsIdentity)	將指定的宣告識別加入這個宣告主體。
Clone()	傳回這個執行個體的複本。
CreateClaimsIdentity(BinaryReader)	建立新的宣告身分識別。
Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
FindAll(Predicate<Claim>)	擷取符合指定述詞的所有宣告。
FindAll(String)	擷取所有具有指定宣告類型的宣告。
FindFirst(Predicate<Claim>)	擷取符合指定述詞的第一個宣告。
FindFirst(String)	擷取含指定宣告型別的第一個宣告。
GetHashCode()	做為預設雜湊函式。 (繼承來源 Object)
GetObjectData(SerializationInfo, StreamingContext)	將序列化目前 SerializationInfo 物件所需的資料填入 ClaimsPrincipal。
GetType()	取得目前執行個體的 Type。 (繼承來源 Object)
HasClaim(Predicate<Claim>)	判斷與此宣告主體相關聯之宣告身分識別的任何一個是否包含指定述詞所比對的宣告。
HasClaim(String, String)	判斷與此宣告主體相關聯之宣告身分識別的任何一個，是否包含具有指定宣告類型和值的宣告。
IsInRole(String)	傳回值，表示此宣告主體所代表之實體 (使用者) 是否在指定的角色。
MemberwiseClone()	建立目前 Object 的淺層複製。 (繼承來源 Object)
ToString()	傳回代表目前物件的字串。 (繼承來源 Object)
WriteTo(BinaryWriter, Byte[])	使用 BinaryWriter 序列化。
WriteTo(BinaryWriter)	使用 BinaryWriter 序列化。

另請參閱

• Claim
• ClaimsIdentity
• ClaimsAuthenticationManager
• ClaimsAuthorizationManager