30
Backend
06
Security
12
iOS
21
Infra

Give every non-production environment one shared passkey RP ID

ADR-0089 ACCEPTED · 2026-10-24
Give every non-production environment one shared passkey RP ID

Amends ADR-0058.

Decision

Use preview.ztp.pghale.com as the WebAuthn relying-party ID for every environment except production, which keeps ztp.pghale.com. Local development, Debug builds from any checkout, and TestFlight builds pointed at a per-branch preview all share it. On the server the RP ID is configuration, separate from the server's own URL. The app picks its RP ID from the endpoint it talks to: production for the production API and the shared ID for anything else. It refuses a challenge whose RP ID differs.

The server accepts https://<rp id>, which is what Apple's native passkey API puts in client data, and its own URL, so the browser sign-in page on a preview works too. The app's associated-domains entitlement lists the shared RP ID without developer mode, and production serves the association file for it, so Apple's CDN can always fetch it.

Why

A native passkey ceremony never contacts the RP host. The OS signs for a domain when the app's entitlement names it and Apple has verified that domain's association file. So the RP ID only has to be a real public domain that lists the app, not the API host. Deriving it from the server URL gave every preview an RP ID no build could match, and gave every developer a private one served from a laptop. That relied on associated-domains developer mode, which macOS never honoured.

The app binds the RP ID to its endpoint rather than trusting the server. The entitlement covers production too, so a non-production server allowed to choose could have a developer's production passkey sign a relayed production challenge.

Rejected alternatives

  • An RP ID per environment. Every new preview host would need an entitlement entry and a new build, so previews could never use passkeys.
  • Allow every subdomain of the RP ID as an origin. Any branch's page could then complete a ceremony against another branch's server. The same setting in production would extend that to every host under ztp.pghale.com.
  • Use the production RP ID everywhere. Pre-release code would then handle credentials that unlock real accounts.

Consequences

Passkeys work on previews and in the macOS app during development, and local development no longer needs a publicly trusted certificate for them. All non-production passkeys appear in one system picker, but each environment has its own database, so a passkey only signs in where it was created. Non-production passkeys depend on production serving the association file. The browser sign-in page on a local machine can't use passkeys, because its host isn't under the shared RP ID, so it falls back to a password.