OIDC Claims

The Language of Identity

OIDC Claims are the fundamental units of identity data. In the OpenID Connect protocol, a “Claim” is a piece of information about an entity (usually the user) that is asserted by the Identity Provider (IdP). By standardizing these assertions—such as email, sub (Subject), and family_name—OIDC ensures that a user’s profile can be understood across different applications and domains without manual translation. Claims act as the “Vocabulary” that allows a Service Provider to understand who a user is and what characteristics they possess, forming the basis for personalization and authorization decisions.

CLAIMS

Identity Attributes

Core Mission

Universal User Profiling. Providing a consistent, structured, and cryptographically signed set of user attributes that can be trusted across organizational boundaries.

Like the Fields on a Passport: A passport (The ID Token) contains specific, pre-defined fields like "Nationality," "Date of Birth," and "Document Number." These are Claims. Because international authorities have agreed on the meaning of these fields, a border agent in any country can read your passport and understand your identity immediately, without needing to speak your native language or call your home government.

User Personalization / Dynamic Entitlements / Directory Synchronization

The Claims Strategic Matrix

Claims are grouped into standardized sets, often requested through specific OAuth 2.0 “Scopes.”

Strategic Claim Taxonomy

Category	Standard Scopes	Example Claims	Strategic Value
Essential	openid	sub, iss, aud, exp.	Critical for token validation & ID.
Profile	profile	name, given_name, picture.	Basic UI personalization.
Contact	email, phone	email, email_verified.	Communication & MFA.
Custom	(various)	tenant_id, role, dept.	App-specific authorization logic.

The Claim Delivery Cycle

Claims are delivered to an application either embedded within the ID Token or retrieved on-demand from the UserInfo endpoint.

graph LR
    Request[Scope Request] --> Filter[Privacy Filter]
    Filter --> Token[Issue ID Token]
    Token --> API[UserInfo Call]
    API --> Aggregate[Complete Profile]

1

Scope-Based Filtering

The application requests specific identity scopes (e.g., `openid profile email`). The IdP uses these scopes to "Filter" exactly which claims the user has consented to share with that specific application.

2

Token-Based Assertion

Essential identity claims (like the user's ID and issue time) are baked directly into the signed ID Token. This allows the application to verify the core identity instantly without making another network request.

3

Full Profile Hydration

For verbose data (like full addresses or large profile pictures), the application presents its Access Token to the `/userinfo` endpoint. The IdP returns the final, comprehensive set of attributes to complete the user profile.

---

Technical Claims Implementation

Defining custom claims allows you to pass business-critical information directly into the authenticated session.

ID Token Payload (JSON Example)

{
  "iss": "https://auth.example.com/",
  "sub": "user_89123476",
  "aud": "client_abc_123",
  "exp": 1735689600,
  "iat": 1735686000,
  "email": "user@example.com",
  "name": "Jane Doe",
  "app_metadata": {
    "role": "admin",
    "tier": "enterprise",
    "tenant_id": "tenant_456"
  }
}

OIDC Implementation Guides

Master the technical details of managing structured identity data across your ecosystem.

OIDC Overview

Strategic foundational principles for identity federation and authentication Layering.

ID Token Anatomy

Deep-dive into the structure, validation, and lifecycle of identity assertions.

UserInfo Endpoint

Retrieving detailed user profile data after successful authentication.

Claims Mapping

Patterns for transforming and harmonizing attributes across different IdPs.

Next Steps

• Explore Standard Claim Definitions for the full list of OIDC-compliant attributes.
• Review Privacy and Consent patterns to manage user attribute sharing.
• Check JSONPath for Claims for navigating complex, nested OIDC payloads.