feat!: delegated IdP, identity chaining, and capability-driven scope model

[igrigorik]

Redesign identity linking for multi-merchant agentic commerce. Businesses can offer delegated identity providers, allowing buyers to authenticate through a trusted IdP (e.g., Google, Shop) instead of creating a per-merchant account. Platforms can support these IdPs to streamline identity linking — authenticate once, reuse across businesses that trusts the same provider.

This PR carries builds on / supersedes #265, reverted in #329.

Delegated Identity Providers

The current identity linking spec assumes 1:1 — each business operates its own OAuth authorization server, requiring a full OAuth dance per merchant. In agentic commerce, where platforms shop across many businesses on a buyer's behalf, this means N merchants = N handoffs.

Businesses can now declare trusted identity providers in config.providers, keyed by reverse-domain identifier:

"dev.ucp.common.identity_linking": [{
  "config": {
    "providers": {
      "com.google": {
        "auth_url": "https://accounts.google.com/"
      },
      "com.example.merchant": {
        "auth_url": "https://merchant.example.com/"
      }
    }
  }
}]

Here the business trusts Google as an external IdP and also lists itself (com.example.merchant) for business-hosted OAuth — both use the same discovery mechanism. Each provider's auth_url is resolved via RFC 8414, with OIDC /.well-known/openid-configuration fallback on 404.

Two distinct flows:

• Account Linking: One-time OAuth flow between platform and IdP. Standard Authorization Code + PKCE, with support for additional grant types (device authorization for headless agents via RFC 8628).
• Accelerated IdP Flow: Platform already holds a valid IdP token (e.g., from Google), chains the buyer's identity to a new business without a browser redirect — per draft-ietf-oauth-identity-chaining-08.

Identity chaining

The accelerated flow implements a two-phase pattern:

1. Platform requests a JWT authorization grant from the IdP via token exchange (RFC 8693), using the resource parameter to identify the target business
2. Platform presents the JWT grant to the business's token endpoint via JWT bearer assertion (RFC 7523)
3. Business validates the grant, resolves buyer identity, issues its own access token

The IdP controls consent — it MUST NOT issue grants for businesses the buyer has not authorized. Businesses MAY auto-provision accounts or return a continue_url for buyer onboarding (terms acceptance, etc.). Two independent token lifecycles with independent revocation. Refresh tokens SHOULD NOT be issued per the chaining draft.

Capability-driven scope model

Scopes define the permissions an identified buyer grants to a platform within a capability. Unlike #265's approach of annotating individual capability schemas with identity_scopes, scope declarations live centrally on the identity linking config. This is because whether a capability requires buyer auth is a business decision — a B2B wholesaler gates catalog access, a B2C retailer serves it publicly.

Three access levels

Level	Authentication	Example
Public	None	Browse a public catalog
Agent-authenticated	Platform credentials	Guest checkout, read agent's own orders
Buyer-authenticated	Platform + buyer identity	Saved addresses, full order history, personalized pricing

Identity linking upgrades capabilities to buyer-authenticated access. Capabilities are never pruned from the intersection based on identity linking; there is no capability pruning algorithm.

Config shape

Building on the provider example, businesses declare which capabilities offer buyer-scoped features alongside their trusted IdPs:

"dev.ucp.common.identity_linking": [{
  "config": {
    "providers": {
      "com.google": {
        "auth_url": "https://accounts.google.com/"
      }
    },
    "capabilities": {
      "dev.ucp.shopping.checkout": {},
      "dev.ucp.shopping.order": {
        "required": true,
        "scopes": ["read", "manage"]
      }
    }
  }
}]

• Absent from capabilities map: no buyer-scoped features (fully public)
• Present, no required: accessible without buyer auth, identity upgrades the experience
• required: true: business returns identity_required error without buyer identity
• scopes: sub-scope operation groups defined by each capability's spec, joined with colon on the wire (e.g., dev.ucp.shopping.order:read)
• Scope tokens use capability names directly — no separate scope namespace

Carried forward from #265

• PKCE MUST (platforms and businesses)
• iss validation MUST (RFC 9207, both sides)
• Exact redirect_uri matching MUST (businesses)
• scopes_supported MUST in RFC 8414 metadata
• 2-step discovery hierarchy: RFC 8414 primary, OIDC fallback on 404 only, strict abort on other errors
• JWT authorization grants: 60s lifetime, jti single-use enforcement

---

Type of change

• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing
  functionality to not work as expected, including removal of schema files
  or fields)
• I have added ! to my PR title (e.g., feat!: remove field).

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings

[aglazer]

Thanks @igrigorik. Agree with the changes. Great addition to UCP!

[gsmith85]

Is SHOULD the right keyword here if there is only one in-common provider, which would effectively be a no-op?

Also worth considering that a platform may have a preferred IdP (or operate its own), which isn't just a UX convenience, it has potential security advantages around revocation, since a platform controlling its IdP can enforce consistent token revocation across all trusting businesses. That said, the intent to preserve buyer choice and visibility over which identity is shared is an important counterbalance.

[gsmith85]

Consider splitting the platform's revocation obligation into two levels:

• Revoking the business-issued token should be a MUST as that's the direct relationship the buyer explicitly asked to sever.
• Revoking the IdP token is a broader action that would cascade across all business relationships established through that IdP, so MAY feels more appropriate, leaving the platform to determine the right blast radius.

[gsmith85]

The example here promotes the SHOULD guidance into a MUST. Should revocation really be optional?

[gsmith85]

Architecturally, discouraging refresh tokens for the JWT bearer grant flow makes a lot of sense as it keeps the IdP as the ongoing trust anchor. But that makes the access token lifetime the effective trust re-verification interval, should we be explicit that it should be minutes not hours?

[gsmith85]

I'm left wondering if strengthening this obligation would be a buyer-centric privacy improvement. The IdP's consent gate covers who and where: it knows the buyer and the target business, and actively gates that relationship. But the fine-grained scope negotiation happens between the platform and the business, outside the IdP's visibility. That makes the platform the only participant that sees both sides: which business receives the identity and what scopes that identity unlocks. The buyer should have visibility into both, not just where their identity is going, but what it will be used for.

[gsmith85]

Is there a reason we're closing off extensibility here and leaving it open on provider?

[gsmith85]

Nit: Should config be required here as it was previously? The old schema required it, and declaring identity linking with no config is effectively a no-op: no providers, no capability scope requirements. It feels like a state that's more likely to be a misconfiguration than an intentional choice. That said, there's an argument for allowing it as an incremental rollout path, where a business signals infrastructure support before capabilities opt in.

[gsmith85]

Nit: This scope format doesn't match the new scope naming convention defined in the Scope Naming section.

[richmolj]

Thoughts on moving this to MAY? I'm thinking of the scenario: "as a Business, I want to automatically sign in existing users, but don't want to interrupt the flow and force users to sign up."

[douglasborthwick-crypto]

The delegated IdP architecture is a big improvement — especially the identity chaining flow for reducing N-merchant handoffs in agentic commerce.

One question on provider extensibility, building on @gsmith85's point: the provider schema currently requires auth_url and resolves via RFC 8414 / OIDC discovery. This works for OAuth IdPs, but in agentic commerce there are non-OAuth identity signals that follow a similar trust model — signed claims, public-key discovery via .well-known, offline verification — without an OAuth authorization flow.

Concrete example: wallet attestation. An agent presents a signed credential proving it meets specific conditions (holds assets, passes compliance checks). The verifier fetches the issuer's JWKS from /.well-known/jwks.json, verifies the ES256 signature, checks expiry — no redirect, no token exchange, no browser. The trust model is the same as an IdP (public-key discovery → signature verification), but the flow is attestation-based rather than authorization-based.

This maps to the "agent-authenticated" access level in #330's three-tier model — the agent proves something about itself without a buyer-identity OAuth flow.

Would it make sense for provider to accommodate non-OAuth mechanisms alongside the current OAuth flow? The old mechanism base in #265 had a type discriminator with additionalProperties: true for exactly this kind of extensibility. Even if the initial implementation is OAuth-only, a type field on provider would keep the door open without adding complexity to the current spec.

[proshoumma]

Really like the direction here, the delegated IdP model and identity chaining solve a real pain point for multi-merchant agentic commerce. We've been working through this exact problem on our end and this is a big step forward.

One thing we keep coming back to is per-business buyer consent in the Accelerated IdP Flow.

With the traditional Account Linking flow, the buyer sees the business's consent screen and explicitly approves. The Accelerated IdP Flow removes that touchpoint - identity chains to new businesses server-to-server, which is great for UX but means the buyer never explicitly consents to (or may not even be aware of) each individual business receiving their identity.

The spec has the right instincts here - the MUST NOT on IdPs issuing grants for unauthorized businesses, and the SHOULD on platforms informing the buyer, but neither defines a concrete mechanism. And the underlying draft-ietf-oauth-identity-chaining-08 doesn't help either. It's entirely silent on consent, which makes sense for its enterprise federation roots, but consumer commerce is a different world. Under GDPR especially, per-purpose consent and data subject awareness aren't optional.

A few things we're thinking about:

• Should the spec provide guidance on what "buyer has not authorized" actually means in practice? Right now it's a strong requirement with no defined path to satisfy it.
• Would it make sense to strengthen buyer awareness from SHOULD to MUST for consumer-facing contexts?
• Happy to help think through what a workable consent model could look like here.