Chapter 18: Claims Design and Privacy — Identity Data Without Overshare

This is Part 18 of a chapter-by-chapter walkthrough of my book OpenID: Modern Identity for Developers and Architects. In the previous chapter we covered federation. Chapter 18 is about the thing that flows through federation: claims — and how to design them without becoming a privacy liability.

18.1 — Custom Claims

Standard OIDC claims cover the essentials: sub, email, name, a few more. Real applications need more — department, cost center, manager, medical license number, tenant affiliation, subscription tier. Custom claims exist for this, but they come with design discipline.

Namespace them with a URI you control (https://example.com/claims/department). Keep them small — tokens travel in headers and cookies, and large claims make your tokens slow. Type them consistently; document their meaning, allowed values, and the events that change them. Treat the claim catalog as an API, because it is one.

18.2 — Attribute Mapping Across Providers

Federation guarantees that different providers will name the same thing differently. One sends email, another sends email_address, a third sends primary_email. One lowercases, another doesn't, a third sometimes does. Attribute mapping is how you make sense of it.

The pattern that holds up: a single internal schema your application uses, and a thin mapping layer per provider that translates their claims into your schema. Your application code shouldn't know or care which IdP a user came from. Every time an engineer writes if (provider == "okta") ..., you owe your future self a refactor.

18.3 — Privacy by Design

Identity is personal data by definition. Every claim you collect or transmit is a privacy decision, whether you make it deliberately or not. Chapter 18 walks through the principles that make the defaults safer:

• Data minimization — request only the scopes you actually need. OIDC's scope mechanism maps directly to this.
• Selective disclosure — let users consent to individual claims, not just "accept/deny" the whole login. Emerging Verifiable Credentials support this natively (Chapter 21).
• Pairwise identifiers — where appropriate, give different sub values to different RPs, so two RPs can't trivially correlate the same user across their systems.
• Retention and deletion — GDPR and CCPA require real answers to "what does 'forget me' actually do?" Design the answer before the request.

What Chapter 18 Sets Up

After Chapter 18 you should be able to design a claim set that expresses what your application needs without becoming a data-exfil target, map attributes cleanly across multiple providers, and reason about privacy compliance from the architecture up rather than bolting it on at the end.

Next up — Chapter 19: Observability and Operations. We close Part VI with the unglamorous but critical work: authentication logs, distributed tracing of login flows, and immutable audit trails. Identity you can't observe is identity you can't operate.