feat: delegated identity providers and accelerated IdP flow

[igrigorik]

The v1 design (#354) only supports direct OAuth between platform and business: every business requires a fresh redirect, fresh consent, fresh credentials. In practice, many businesses already offer delegated IdPs (Sign in with Google, Shop, Apple, etc.) to give their users accelerated sign-in and account creation+linking. Platforms that already hold an identity at one of those IdPs benefit too: they can complete the link without re-prompting the user, which is essential for agentic flows where redirects and per-merchant consent screens are prohibitive.

This PR lets a business advertise the delegated IdPs it trusts. Platforms that already hold a token at one of those IdPs chain identity to the business via a back-channel token exchange (RFC 8693 + RFC 7523) — no redirect, no extra prompt — and the business still issues its own access tokens under its own authority. Direct OAuth against the business's own AS remains always available; providers is an additive allowlist for chaining only, and businesses MUST NOT self-list (chaining-to-self is degenerate).

How a business advertises providers

Single delegation: business trusts one external IdP. Platforms chain identity through that IdP; direct OAuth on the business domain is implicitly available as a fallback.

"config": {
  "providers": {
    "com.shopify.accounts": {
      "type": "oauth2",
      "auth_url": "https://accounts.shopify.com/"
    }
  },
  "scopes": { "dev.ucp.shopping.order:read": {} }
}

Multiple IdPs with claim pre-filter: business accepts several IdPs and declares required OIDC §5.1 claims so platforms can skip providers whose upstream tokens can't satisfy them (reactive enforcement at the token endpoint remains mandatory):

"config": {
  "providers": {
    "com.shopify.accounts": {
      "type": "oauth2",
      "auth_url": "https://accounts.shopify.com/",
      "required_claims": ["email"]
    },
    "com.google": {
      "type": "oauth2",
      "auth_url": "https://accounts.google.com/"
    }
  },
  "scopes": { "dev.ucp.shopping.order:read": {} }
}

The type discriminator is future-extensible (e.g., wallet attestation) as a non-breaking extension. AS discovery anchors on RFC 9728 protected-resource metadata, so the business's AS can live on a different origin than its API domain.

---

Checklist

• Core Protocol: Changes to the base communication layer, global context, or breaking refactors.
• Capability: New schemas (Discovery, Cart, etc.) or extensions.
• Documentation: Updates to README, or documentations regarding schema or capabilities.
• I have followed the Contributing Guide.
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks.
• (For Core/Capability) I have included/updated the relevant JSON schemas.

[jamesandersen]

This is a great step forward in helping remove end user friction in the commerce journey; left a few comments for discussion.

[douglasborthwick-crypto]

Strong +1 on lifting provider.type into the schema $def with the oauth2 default — that turns providers from an OAuth-only list into a genuine mechanism registry, and the "filter unsupported type, apply the whitelist, abort if nothing remains" selection rule is the right shape for letting a business offer more than one mechanism class side by side.

It's worth stress-testing the extensibility model against a concrete non-oauth2 consumer, since that's where the abstraction either holds or leaks. The wallet attestation mechanism I proposed in #415 is the natural first one, and it surfaces a few assumptions worth loosening now while this section is being written.

A wallet attestation provider issues no token. The platform presents the business a signed boolean ("wallet satisfies predicate P at block N"), the business verifies it offline against the provider's published JWKS, and nothing is minted — no access token, no session, and it contributes no entries to the scopes map under config. That doesn't fit the RFC 8693 → RFC 7523 grant-exchange chain, which assumes the flow terminates in a business-issued bearer token. Three additive adjustments would keep verification-only mechanisms non-breaking:

1. Generalize the deferred-mechanics phrase from "grant exchange mechanics" to something like "discovery and proof-presentation mechanics," so a type that presents a verifiable assertion (rather than exchanging a grant for a token) is in scope by construction.
2. Note that a provider entry's type MAY contribute no scopes — presence in providers doesn't imply participation in the scope/token model. The selection and abort rules work unchanged; they turn on whether the platform supports the type, independent of whether that type issues a token.
3. Scope auth_url to the mechanism that needs it. The provider $def currently sets required: ["auth_url"], but the $def description already promises "additional types (e.g., 'wallet') without breaking the shape" — and a verification-only type discovers via provider_jwks, not an authorization-server URL, so it has no auth_url to supply. As written, any non-oauth2 entry fails validation against the $def. Suggest either an if/then on the discriminator (auth_url required only when type is oauth2), or relaxing required at the $def level and letting each type declare its own required fields. This is the one structural change that lets feat: identity linking — mechanism extensibility with wallet attestation #415 land as a pure extension rather than a retrofit.

Happy to rebase #415 onto this branch's selection semantics once it merges, and to fold these clarifications into that PR if you'd rather keep #423 focused on the OAuth-chaining path.

And agreed on the agentic-flow framing — that's the strongest case for keeping the registry mechanism-plural.

Douglas

[raginpirate]

high level thought about restructuring where we advertise this set of providers, wdyt?

[igrigorik]

@amithanda @jamesandersen @douglasborthwick-crypto ty for thorough review and comments. Pushed a set of commits that should address all the flags and clarifications, ptal.

[shopdave]

Overall looks good. Suggest revamping the discovery section to explicitly use PRM as the mechanism for discovering where the authorization server is located. This also closely aligns us with the MCP approach and makes off-business domain authorization servers possible.

Also suggest updating the PR body to reflect the latest changes as to not confuse anyone in the future.

[igrigorik]

@raginpirate sharp eyes and great catch! Agree on the nudge, updated -- ptal.

[raginpirate]

🚀!

[amithanda]

I think the "JWT grant single-use" bullet is broken mid-clause:

Businesses MUST enforce single-use JWT; a short exp narrows the replay window, but only jti tracking closes it. authorization grants by tracking the jti claim within the grant's validity window.

This is probably a merge artifact from @shopdave's suggestion. I think, two fragments got spliced.

Suggested change

	* **JWT grant single-use.** Businesses **MUST** enforce single-use JWT;
	* **JWT grant single-use.** Businesses **MUST** enforce single-use of JWT
	authorization grants by tracking the `jti` claim within the grant's
	validity window. A short `exp` narrows the replay window, but only
	`jti` tracking closes it.

[amithanda]

Approving — great work on this 🚀

Thanks for the thorough iteration here, @igrigorik. My earlier suggestions are all well addressed:

• resource/audience interop - the move to "resource and/or audience, MUST include at least one" cleanly unblocks existing implementations like Google STS and Keycloak without weakening the binding. 👍
• Self-listed vs. external IdP ambiguity - flipping providers to a delegated-only closed allowlist (plus the "ignore an entry whose auth_url matches the business's own issuer" rule) resolves the circular-token-exchange concern far more elegantly than a self flag would have.
• Non-OAuth extensibility - using if/then on the type discriminator keeps auth_url required only for oauth2 while leaving the door open for wallet attestation and future mechanisms as non-breaking additions.

One small open item before merge - the "JWT grant single-use" bullet in Security Considerations is currently garbled (the original sentence's tail got left dangling when @shopdave's jti suggestion was applied). Left an inline suggestion to restore it to a single coherent MUST. Purely editorial.

This is a meaningful step forward for UCP identity linking capability. Nicely done. Approving with the one nit above.