Sign-in provider setup

Status: Accepted (2026-09-15) · Amends: ADR-0024, ADR-0028, ADR-0044 · Amended by: ADR-0046 (APP_PUBLIC_URL, the Google and Apple status lines)

Context#

apistock provides passkeys, Google sign-in and Apple sign-in (v0.3), but it never owns the accounts they depend on. Each app's developer creates their own Apple Developer and Google Cloud resources and gives the app the identifiers, keys and fingerprints. Mobile apps and web frontends are built later; the backend must be ready for them now.

The maintainer's requirement (2026-09-15): developers must be told plainly what they need to provide, where to get it and where to paste it, in the .env file, in the documentation and in the terminal, so every sign-in method works once they have filled it in. ADR-0024 already promised that social providers are "disabled until credentials are configured" and that aps dev "reports their status"; ADR-0028's banner showed Google login: not configured → docs/auth-providers.md. Nothing defines what that report contains or where the instructions live.

Decision#

1. What the developer provides#

Everything is an environment variable (ADR-0031: identifiers and keys of external accounts are infrastructure and secrets, not runtime settings). An empty variable means the method is off; the rest of the app works.

Passkeys (ADR-0044)

Files the backend serves for native apps (no file to upload; generated from the variables above):

Google sign-in (implemented with its own ADR; variable names are fixed here)

To register in Google Cloud: authorized redirect URI https://<your API>/v1/auth/google/callback (development: http://localhost:8080/v1/auth/google/callback).

Apple sign-in (implemented with its own ADR; variable names are fixed here)

To register at Apple: the Services ID's domain and return URL https://<your API>/v1/auth/apple/callback. Apple doesn't accept localhost for the web flow; test it through a tunnel or use the native flow (ADR-0024).

2. Where it is written#

3. How the developer is told#

Example in development:

Sign-in methods
  ✓ Email and password
  ✓ Two-factor authentication (authenticator apps)
  ✓ Passkeys in browsers          RP ID localhost, origins http://localhost:8080, http://localhost:3000
  – Passkeys in iOS apps          set WEBAUTHN_APPLE_APP_IDS in .env        AUTH_PROVIDERS.md#passkeys-in-ios-apps
  – Passkeys in Android apps      set WEBAUTHN_ANDROID_APPS in .env         AUTH_PROVIDERS.md#passkeys-in-android-apps
  – Google sign-in                set GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET AUTH_PROVIDERS.md#google
  – Apple sign-in                 set APPLE_TEAM_ID, APPLE_SERVICES_ID, APPLE_KEY_ID, APPLE_PRIVATE_KEY_FILE  AUTH_PROVIDERS.md#apple

Methods appear in the block once they are implemented; Google and Apple join with their ADR.

4. Frontend and mobile, later#

The backend ships everything a client needs now: the endpoints, the generated association files, and the provider callbacks when Google and Apple land. AUTH_PROVIDERS.md records what the web frontend and mobile apps must do when they are built (call navigator.credentials with the returned options, add the Associated Domains entitlement, handle the Google and Apple native SDK tokens), so those stages start from a checklist rather than a search.

Secrets#

Only GOOGLE_CLIENT_SECRET and the Apple private key are secrets: config.Secret, *_FILE supported, never printed, logged, returned by /ops or accepted as flags or runtime settings (threat 19).

Why#

• Developers can't guess console paths and fingerprint formats; one table per method, repeated where they look (.env, docs, terminal), removes the guesswork.
• A status block at start answers "why doesn't Google sign-in work?" before anyone asks.
• Failing on partial configuration catches the common mistake of pasting half the credentials.
• A status endpoint and command give the future dashboard and CI the same information without exposing values.

Trade-offs#

• Console paths change; the guide needs occasional updates.
• One more permission (ops.auth.read) and endpoint.
• Printing configuration status at every development start adds a few lines of output.

Consequences#

• ADR-0044 uses this for passkeys: its variables, generated files, status lines, AUTH_PROVIDERS.md sections and .env.example block ship with it.
• The Google and Apple ADR adopts the variable names and status behaviour above.
• The Full preset gains AUTH_PROVIDERS.md, the status block, auth-providers command and GET /ops/auth/providers.

Implementation notes (2026-09-15)#

• The status comes from one place, Config.signInMethods in internal/app/providers.go: method key and name, enabled, a detail for enabled methods (relying party ID and origins, app IDs, Android packages), and the missing variables and guide section for the others. The start block, the command and the endpoint all use it.
• Partial configuration is refused by LoadConfig: WEBAUTHN_ORIGINS or native app IDs without WEBAUTHN_RP_ID, an RP ID without origins, http origins in production, origins off the RP ID, and malformed Apple app IDs or Android fingerprints, each naming the variable and AUTH_PROVIDERS.md.
• aps new --preset full prints AUTH_PROVIDERS.md in its next steps, and the docs URL on localhost, which passkeys need.
• Tests: the block's lines for enabled and missing methods; the endpoint for ops_viewer, never containing the encryption key, and 403 without an ops role; every configuration error above.