Skip to content

Claims, ClaimsIdentity, ClaimsPrincipal — Quick Reference

Big Picture

Authentication builds a ClaimsPrincipal. Authorization evaluates a ClaimsPrincipal. If something is not in the principal, the system does not know it.

Claim

What it is: A single fact about a user, represented as a key–value pair.

Examples: userId = 8f3e… email = abhishek@gmail.com role = Admin permission = invoice.create

Used for: - Authorization decisions - Auditing - Token payloads (JWT) - Personalization

Mental model: Claims describe the user.

ClaimsIdentity

What it is: A collection of claims plus metadata describing how and from where those claims were issued.

Contains: - Claims - Authentication type (Cookies, Bearer, Google) - IsAuthenticated flag - Name claim type - Role claim type

Represents: Who the user is according to a specific authentication mechanism.

Examples: - Google identity → claims issued by Google - Cookie or bearer identity → claims issued by your application

Important rule: Identities represent trust boundaries, not personas or roles.

ClaimsPrincipal

What it is: The top-level authenticated user representation for the current request.

Structure: - One or more ClaimsIdentity instances grouped together

In ASP.NET Core: HttpContext.User

Represents: Who the system believes is calling right now.

Key rule: All authorization decisions are based only on the ClaimsPrincipal.

Common External Login Flow

  1. External provider authenticates the user and returns claims
  2. A temporary external identity is created
  3. The application validates or creates a local user
  4. The application issues its own identity and claims
  5. The user is signed in using the application’s scheme

Key idea: External identities are usually transient. Application-issued identities are authoritative.

Critical Distinctions (Interview Gold)

  • Claim is not a role and not a permission
  • ClaimsIdentity is not a database user
  • ClaimsPrincipal is not a persisted entity
  • Authentication is not authorization

One-Liners to Memorize

  • Claim: a fact about the user
  • ClaimsIdentity: who issued those facts and how
  • ClaimsPrincipal: the authenticated caller being evaluated

Alternative: Claims are facts. Identities are issuers. Principals are callers.

Important Nuances

  • ClaimsPrincipal is request-scoped and ephemeral
  • Rebuilt on every request from a cookie or token
  • Multiple identities can exist, but authorization should trust your own issuer
  • External providers authenticate; your system authorizes

Clean Architecture Mapping

  • Web layer builds the ClaimsPrincipal
  • Application layer reads user data via a current-user abstraction
  • Infrastructure layer must not depend on HTTP context or ClaimsPrincipal

Final Rule

If a permission is required, it must exist as a claim inside the ClaimsPrincipal.