Aggregated and Distributed Claims in OpenID Connect

In OpenID Connect (OIDC), Standard Claims (like sub, email, name) and Custom Claims are attributes directly asserted and digitally signed by the primary OpenID Provider (OP). However, OIDC includes two mechanisms, Aggregated Claims and Distributed Claims, that allow an OP to integrate data from external sources, such as an CRM system, payment provider, employee directory, known as Claims Providers. These mechanisms enable the separation of concerns and the integration of specialized attribute authorities.

Summary and Comparison

Feature	Standard/Custom Claims	Aggregated Claims	Distributed Claims
Source Asserted By	Primary OpenID Provider (OP)	Claims Provider	Claims Provider
Return Value	Literal key-value pair e.g., "name": "Jane Doe"	Nested JWT signed by Claims Provider.	JSON object with endpoint and access_token as reference.
Assertion of Trust	OP's signature on the token	OP's signature on the container + Claims Provider's signature on the nested JWT.	P's signature on the container + RP must trust the secure channel to the third-party Claims Provider.
RP Retrieval Method	Direct fetch from ID Token or UserInfo Endpoint.	Direct fetch from ID Token or UserInfo Endpoint; requires nested JWT validation.	Separate API call by the RP to the Claims Provider's endpoint.
Data Flow	OP → RP	Claims Provider → OP → RP	Claims Provider → RP (Direct)
Primary Use Case	Core identity data.	Integrating claims from partners while maintaining the OP as the delivery channel.	Large, sensitive, or external claims that require an independent fetch.

Distributed Claims

Distributed Claims are claims that the Identity Provider (OP) delegates the retrieval of to the application (RP). This is typically used for claims that are too large, volatile, or highly sensitive to include directly in the ID Token or UserInfo response.

The OP includes a special JSON object in the UserInfo response or ID Token instead of the actual claim value. This JSON object must contain three required fields:

• claim_names: An array of strings listing the claims to be retrieved (e.g., ["street_address", "phone_number"]).
• endpoint: The URL of the third-party Claims Provider's API endpoint.
• access_token: A Bearer Token the RP must use when calling the endpoint.

The RP must make a separate HTTP GET request to the endpoint URL, presenting the provided access_token in the Authorization header, to fetch the actual claims. This introduces an extra network hop and a dependency on the Claims Provider's availability and security model.

Example Distributed Claims: OpenID Provider (OP) Response

{
   "sub": "248289761001",
   "name": "Jane Doe",
   "given_name": "Jane",
   "family_name": "Doe",
   "email": "janedoe@example.com",
   "birthdate": "0000-03-22",
   "_claim_names": {
     "country": "src1",
     "is_customer": "src1",
     "payment_info": "src2",
    },
   "_claim_sources": {
     "src1": {
        "endpoint": "https://crm.example.com/claim_source", 
        "access_token": "ksj3n283dke"
     },
     "src2": {
        "endpoint": "https://payments.example.com/claim_source",
     }
   }
}

Example Distributed Claims: Claim Provider

The client application needs to send a second request to the claim provider to receive the distributed claims. The request uses the provided access token in the Authorization header to authenticate with the Claims Provider.

Example get request to the Claims Provider

GET /claim_source HTTP/1.1
Host: crm.example.com
Authentication: Bearer ksj3n283dke

Response from Claim Provider

{
   "iss": "https://crm.example.com",
   "country": "US",
   "is_customer": true,
}

Aggregated Claims

Aggregated Claims allow a primary OP to pass claims from a third-party Claims Provider to the Relying Party (RP) while still acting as the single assertion point. The claims are included in the OP response by value as an aggregation of claims from different Claims Providers.

How They are Returned

1. The Claims Provider issues a JSON Web Token (JWT) containing the claims (e.g., specific health or tax data) and signs it.
2. The OP receives this JWT.
3. The OP places this entire, signed JWT into a single, special claim, typically named _aggregated_claims (or a custom name if negotiated), within the UserInfo response or the ID Token. The OP signs the containing token.

The RP receives the claims within the main token structure, but must then validate the inner JWT signature against the public key of the Claims Provider to trust the source of the claims. The claims themselves are not directly at the top level; they are retrieved by decoding and validating the nested JWT.

Example Aggregated Claims

OpenID Provider (OP) Response

{
   "sub": "248289761001",
   "name": "Jane Doe",
   "given_name": "Jane",
   "family_name": "Doe",
   "email": "janedoe@example.com",
   "birthdate": "0000-03-22",
   "_claim_names": {
     "country": "src1",
     "is_customer": "src1",
    },
   "_claim_sources": {
     "src1": { "JWT": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2NybS5leGFtcGxlLmNvbSIsImNvdW50cnkiOiJVUyIsImlzX2N1c3RvbWVyIjp0cnVlfQ.GsIt_wy9Nimn74O-VYYPf3nKxqRio6_bCWkXNJ_Q0Do" },
   }
}

The aggregated claim is included as a signed JWT token in the OpenID Provider's response. The token contains the claims from the Claims Provider.

Signed JWT Token

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.
eyJpc3MiOiJodHRwczovL2NybS5leGFtcGxlLmNvbSIsImNvdW50cnkiOiJVUyIsImlzX2N1c3RvbWVyIjp0cnVlfQ.
sIt_wy9Nimn74O-VYYPf3nKxqRio6_bCWkXNJ_Q0Do

The OpenID Standard describes the format as jwt_header.jwt_part2.jwt_part3. You can decode the JWT using a tool like jwt.io (jwt.io):

• Typ: JWT
• Alg: HS256
• Signing key: a-string-secret-at-least-256-bits-long

Pseudo-Decoded JWT

//jwt_header
{
    "typ": "JWT",
    "alg": "HS256"
}
//jwt_part2
{
   "iss": "https://crm.example.com",
   "country": "US",
   "is_customer": true,
}
//jwt_part3
{
   "a-string-secret-at-least-256-bits-long"
}

Registration and User Consent

The OpenID Connect Claims Aggregation 1.0 - Draft 03, 2025 (openid.net) draft discusses how a user can give consent in an aggregated claims model.

In the aggregated claims model, the OpenID Provider (OP) must establish a trust relationship with the claims provider. This can be achieved by when the OP registers as an OIDC client to a Claims Provider.

Before collecting the claims on behalf of the subject, OP must collect consent from the user for all claims collected.

There are four phases involved:

1. CP Discovery Phase: OP discovers Claims Provider's metadata with the discovery endpoint.
2. OP Registration Phase (OP → CP): OP registers to Claims Provider as a relying party (RP) via OpenID Connect Dynamic Client Registration (openid.net).
3. Setup Phase (CP → OP): OP obtains the access and refresh tokens from the Claims Provider. The user must give consent for each claim requested from a claims provider. The granting must involve active user interaction and must be done with an OIDC authentication request.
4. Delivery Phase (RP → OP ← CP):
   1. Claims Request: RP makes authentication and claims request to OP,
   2. Request Verification: OP validates the request,
   3. Subject Granting: OP authenticates the user, displays consent screen, and obtains consent through explicit action,
   4. Claims Collection: OP fetches relevant claim sets from CPs' UserInfo endpoints,
   5. Claims Delivery: OP respond to the RP in the previously defined format with the collected claims as embedded, signed JWT token,
   6. Claims Verification: the RP verifies the response including embedded JWT signatures and trust to the individual Claims Providers.

References

• OpenID Connect Core 1.0 incorporating errata set 2 - Aggregated and Distributed Claims (openid.net)
• OpenID Connect as a KYC Token distribution protocol (ec.europa.eu)
• OpenID Connect Claims Aggregation Draft 02, 2021 (openid.net)
• OpenID Connect Claims Aggregation 1.0 - Draft 03, 2025 (openid.net)
• OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 2 (openid.net)