Discovery and company identity

Discovery and company identity

A company publishes discovery metadata at https://{domain}/.well-known/poppy.json. Finding an API URL in that document is only the start of validation.

Check both directions

First, organization.domain must identify the host serving the document after discovery redirects. Then fetch the OAuth server metadata for auth.issuer: its issuer must match exactly, and its poppy_domains must include the company domain.

These checks stop a copied document from impersonating a company and stop an unrelated domain from claiming another company’s issuer. An issuer can contain a path; comparing only hostnames loses part of the identity.

The issuer boundary

Several domains of one company can share an issuer. A provider hosting several companies needs a distinct issuer for each company. Otherwise user identifiers, sessions and account authorization that should be isolated would share a protocol identity.

Personal agent identity

The personal agent’s client_id is an HTTPS URL returning its metadata document. Companies obtain public keys and permitted redirect locations from validated metadata. Published signing keys, private keys and DPoP keys have different roles. Do not trust arbitrary key URLs embedded in a request.

Fetch safely

Metadata comes from a URL controlled by another party. Bound response size, redirects and timeouts; do not attach cookies or authorization headers. Check actual connection addresses and reject loopback, private and link-local destinations unless explicitly configured. Discovery redirects and credential-bearing request redirects follow different rules.

Sources: draft 0.2 and official guides. Next: implementation.

Last updated on