OAuth2 & OpenID Connect Deep Dive · Lesson

Claims Request and aggregated Claims

Learn how OpenID Connect lets clients request specific claims with the claims parameter, and how distributed and aggregated claims deliver assertions from external sources.

Claims Request and aggregated Claims is a free OAuth2 & OpenID Connect Deep Dive lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the OAuth2 & OpenID Connect Deep Dive learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Requesting Specific Claims

Beyond scopes like profile or email, OIDC offers a finer-grained claims request parameter. It lets a client ask for individual claims and target where they appear: in the ID token or from UserInfo.

The claims Parameter Shape

The claims parameter is a JSON object with two top-level members: id_token and userinfo. Each maps claim names to a value describing how they are requested.

{
  "id_token": { "auth_time": { "essential": true } },
  "userinfo": { "email": null, "email_verified": null }
}

essential, value, values

Each requested claim can specify:

essential: true — the client really needs it.
value — request that the claim equals a specific value.
values — request one of several allowed values.

{ "acr": { "essential": true,
            "values": ["urn:mace:incommon:iap:silver"] } }

Sending It in the Request

The JSON is URL-encoded and sent as the claims query parameter on the authorization request.

GET /authorize?response_type=code
  &client_id=app123&scope=openid
  &claims=%7B%22id_token%22%3A%7B%22auth_time%22%3A%7B%22essential%22%3Atrue%7D%7D%7D

Why Not Just Scopes?

Scopes bundle many claims at once. The claims parameter is for when you need precision — a single specific claim, an essential requirement, or a constraint on its value. It complements scopes rather than replacing them.

Aggregated Claims

Sometimes claims come from a third party the OP trusts. Aggregated claims are bundled by the OP as a signed JWT from the external claims provider and returned inline, so the client gets verifiable assertions without extra calls.

Aggregated Claims Format

The OP references them via _claim_names (which claim came from which source) and _claim_sources (the JWT holding them).

{
  "_claim_names": { "address": "src1" },
  "_claim_sources": {
    "src1": { "JWT": "eyJhbGciOi..." }
  }
}

Distributed Claims

Distributed claims are not embedded; instead the OP gives an endpoint and access token so the client can fetch them directly from the external source when needed.

{
  "_claim_names": { "payment_info": "src2" },
  "_claim_sources": {
    "src2": {
      "endpoint": "https://bank.example.com/claims",
      "access_token": "ksj3n283dke"
    }
  }
}

Aggregated vs Distributed

The trade-off:

Aggregated — claims travel inline, fewer round-trips, larger token.
Distributed — claims fetched on demand, smaller token, extra request and live availability of the source.

Processing External Claims

For aggregated claims, verify the embedded JWT's signature against the claims provider's keys. For distributed claims, call the endpoint with the supplied access token and validate the returned JWT before trusting any values.

When to Use These

External claim mechanisms shine in federations: an identity provider asserts who you are, while a bank or government source asserts verified attributes. They keep sensitive data at its authoritative source.

Quick Check

Test your understanding of claim requests.

Recap

The claims parameter enables fine-grained, essential, or value-constrained claim requests targeting the ID token or UserInfo.

essential, value, and values refine each request.
Aggregated claims are embedded inline as signed JWTs.
Distributed claims are fetched from an external endpoint.
Always verify external claim signatures before trusting them.

Frequently asked questions

Is the “Claims Request and aggregated Claims” lesson free?

Yes — the full text of “Claims Request and aggregated Claims” is free to read here on the web, and the OAuth2 & OpenID Connect Deep Dive course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the OAuth2 & OpenID Connect Deep Dive course, upgrade to CoddyKit PRO.

What will I learn in “Claims Request and aggregated Claims”?

Learn how OpenID Connect lets clients request specific claims with the claims parameter, and how distributed and aggregated claims deliver assertions from external sources. You practise OAuth2 & OpenID Connect Deep Dive with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start OAuth2 & OpenID Connect Deep Dive?

No prior experience is required. OAuth2 & OpenID Connect Deep Dive on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Claims Request and aggregated Claims” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this OAuth2 & OpenID Connect Deep Dive lesson?

Yes. Every OAuth2 & OpenID Connect Deep Dive lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to OAuth2 & OpenID Connect Deep Dive