In an OpenID Connect claim set, what do _claim_names and _claim_sources indicate about where a claim came from?

## Not every claim belongs to the provider you are talking to The simple model of OpenID Connect is that a provider knows things about an end user and asserts them. Often that is true. But an identity provider is frequently not the authority for some attribute a client needs — a professional certification, a licence, a membership grade held by an entirely different organisation. Rather than pretend to own those, the specification provides two OPTIONAL shapes for claims that come from elsewhere. ## Three claim types | Type | Where the values are | Who asserted them | |---|---|---| | normal | in the claim set, as ordinary members | the provider itself | | aggregated | in the response, inside a signed JWT | another issuer, passed through | | distributed | not in the response — only a reference | another issuer, fetched by the client | The provider advertises which of these it can produce in the `claim_types_supported` member of its configuration document. ## The two members that wire it up Both non-normal types use the same pair of members in the claim set: - **`_claim_names`** maps each externally sourced **claim name** to a short key. It answers "which claims are not mine, and which source does each belong to?" - **`_claim_sources`** maps each key to the **source description**. It answers "what is that source, and how do I get the value?" The shape of a source entry is what distinguishes the two kinds: - An **aggregated** source carries a `JWT` member holding a signed token from the issuing authority. The values are already in the client's hands; what remains is verifying that token against the issuing authority's key. - A **distributed** source carries an `endpoint`, and optionally an `access_token` to present when calling it. The values are not in the response at all. One consequence follows directly: a claim listed under `_claim_names` is **not** also present as an ordinary member of the claim set. Client code that only reads top-level members will see the attribute as absent, which is the usual first symptom that a deployment is using these at all. ## What each shape costs the client **Aggregated claims** cost verification work. The client is receiving a signed statement from a second issuer, and it has to decide whether it trusts that issuer and check the signature against that issuer's key, not the provider's. The values are frozen at whatever moment the provider collected them; freshness is whatever the JWT itself says. **Distributed claims** cost a network dependency and a failure mode. The client now makes a second call, to a party it may not have a relationship with, at a moment the provider chose for it. That call can be slow, can fail, can require a credential the client mishandles, and turns a self-contained response into a fan-out. In exchange, the values are fetched when needed rather than when the response was assembled, and the provider never holds attributes it has no business holding. ## In the sighting recorder The nature reserve accepts records only from rangers who hold a bird-ringing licence, and the licence is issued by a national ringing registry — not by the reserve's identity provider. Two designs are available. Aggregated: the provider collects a signed statement from the registry and passes it through in the response. The recorder verifies it against the registry's key and can work offline thereafter, at the cost of a licence status that is as old as the collection. Distributed: the provider says only "the licence claim is at the registry, here is where and here is a credential". The recorder fetches it and sees current status, at the cost of being unable to record a sighting when the registry is unreachable. That trade — staleness against availability — is the whole decision, and it is why this is a design question rather than a syntax one. ## What to check before shipping either 1. **Does the provider advertise it?** Both types are OPTIONAL; read `claim_types_supported` rather than assuming. 2. **Whose key verifies an aggregated claim?** The issuing authority's, not the provider you fetched the response from. Verifying against the wrong key is the classic error here. 3. **What happens when a distributed source is down?** Decide before it happens, and do not let a third party's outage silently degrade into "the user has no licence". 4. **Is the claim name deployment-specific?** These mechanisms are usually carrying attributes outside the four standard claim sets, so the names are local to the deployment and must be agreed in writing.