Sign in with KRDPASS (App-to-App): Testing & Go-Live

Quick Test with Scripts

The fastest way to validate end-to-end: App → Backend → KRDPASS → callback → tokens.

1. Create local secrets

cp shared/secrets/.env.example shared/secrets/.env

Fill in shared/secrets/.env:

• BACKEND_URL, REDIRECT_URI, CLIENT_ID, CLIENT_SECRET, RSA_PRIVATE_KEY

2. Sync configs to all sample apps

./scripts/sync-secrets.sh

This updates examples/server/.env, all sample app .env files, and Android signing configs.

Platform-specific sync

./scripts/sync-secrets-android.sh   # Android only
./scripts/sync-secrets-ios.sh       # iOS only

3. Start backend

./scripts/run-sample.sh --app server

Keep this terminal running.

3b. Expose via Cloudflare Tunnel (recommended)

The demo server runs on localhost:3000, but iOS Universal Links require AASA to be served from a real HTTPS domain. Use Cloudflare Tunnel to expose your local server through a domain you control.

Quick tunnel (temporary domain, no setup):

cloudflared tunnel --url http://localhost:3000

This gives you a temporary URL like https://random-name.trycloudflare.com. Works for all platforms, but the domain changes every time you restart the tunnel — meaning you'd need to update Associated Domains in Xcode and rebuild for iOS each time.

Named tunnel (your own domain, recommended for iOS):

# One-time setup
cloudflared tunnel create krdpass-dev
cloudflared tunnel route dns krdpass-dev auth.yourdomain.com

# Run the tunnel
cloudflared tunnel run --url http://localhost:3000 krdpass-dev

Once running, https://auth.yourdomain.com points to your local server. Use this domain as:

• BACKEND_URL in your .env → https://auth.yourdomain.com
• REDIRECT_URI → https://auth.yourdomain.com/_krdpass/oauth/callback
• iOS Associated Domains → applinks:auth.yourdomain.com
• AASA will be served at → https://auth.yourdomain.com/.well-known/apple-app-site-association

TIP

After changing the domain, re-run ./scripts/sync-secrets.sh so all sample apps pick up the new values.

4. Run a sample app

# Flutter
./scripts/run-sample.sh --app flutter --platform android
./scripts/run-sample.sh --app flutter --platform ios

# Native
./scripts/run-sample.sh --app android
./scripts/run-sample.sh --app ios

# React Native
./scripts/run-sample.sh --app react-native --platform android
./scripts/run-sample.sh --app react-native --platform ios

Script options

# Sync before launching
./scripts/run-sample.sh --app flutter --platform android --sync

# Force patch tracked demo files
./scripts/run-sample.sh --app ios --sync-patch-tracked

# Custom secrets file
./scripts/sync-secrets.sh --secrets-file /path/to/.env

# Specific device
./scripts/run-sample.sh --app ios --device "iPhone 13 Pro"

Recommended validation order

1. Flutter Android → 2. Flutter iOS → 3. Android native → 4. iOS native → 5. React Native Android → 6. React Native iOS

What to test

• Successful sign-in and token exchange
• User-cancelled flow
• Timeout behavior
• State validation (one-time server consumption)
• UserInfo retrieval
• Refresh/revoke (if approved)

Troubleshooting

Error codes

Error	Meaning	Fix
cancelled	User cancelled auth	Handle gracefully, allow retry
busy	Auth already in progress	Prevent duplicate taps
timeout	Flow timed out	Retry, verify app switch behavior
launch_failed	Can't open KRDPASS app	Check app availability
invalid_redirect	Callback redirect mismatch	Check exact registered redirect URL
state_mismatch	State doesn't match	Don't reuse state values, generate fresh each time
no_code	Callback came back without code	Check callback params and server logs
platform_error	Generic platform failure	Validate setup and initialization

iOS callback never returns

• Associated Domains enabled in Xcode
• Domain matches your redirect URI host (applinks:<host>)
• AASA is reachable at https://<host>/.well-known/apple-app-site-association (no redirects)
• onOpenURL / user activity handler wired to SDK
• HTTPS redirect URI exactly matches registration

Android returns invalid_redirect

• redirectUri matches onboarding registration exactly
• App and backend use the same redirect URL value

Token exchange fails with state error

• App sends the state returned by PAR to the token exchange
• Backend stores state at PAR time
• State is one-time use (not reused between attempts)

state_mismatch appears intermittently

• Generate state with SDK helpers (not hardcoded):
  • Flutter: KrdpassAuth.instance.generateState()
  • Android: KrdpassAuth.generateState()
  • iOS: try auth.generateState()
  • React Native: KrdpassAuth.generateState()
• Same state from PAR goes to token exchange

React Native module unavailable

• Expo: ran npx expo prebuild
• Bare RN: ran npx install-expo-modules@latest
• iOS pods installed and app rebuilt
• Package installed from correct local path

No refresh token in response

• Confirm you requested offline_access scope
• Confirm refresh token issuance is approved for your integration (restricted by default)

Quick sanity reset

Before deep debugging, reset everything:

./scripts/sync-secrets.sh
./scripts/run-sample.sh --app server

Then re-run your app.

General debug checklist

• Environment matches (development vs production) in app + backend
• clientId matches target environment
• Redirect URI matches everywhere (app, backend, onboarding)
• SDK initialized before auth calls
• Backend endpoints reachable

Still stuck?

Email integration@pass.krd with: SDK + platform + version, environment, error code, request timestamp, and reproduction steps.

Go-Live Security Checklist

Before you ship

• No client_secret or private keys in the mobile app
• No .env with real credentials committed to git
• No secrets in examples, docs, CI logs, or screenshots

OAuth requirements

• Authorization Code + PKCE flow
• Backend-mediated token exchange (not client-side)
• state validated server-side, one-time use
• HTTPS redirectUri enforced
• iOS Universal Link + AASA verified on real device
• Android SHA-256 fingerprint verified with production signing

Production hardening

• Move state store from memory to Redis/database
• Rate limiting on auth endpoints
• Structured logging with trace IDs (redact sensitive values)
• Secrets in managed secret storage with rotation
• TLS enforced end-to-end

Refresh token policy

• Default: avoid refresh tokens unless required
• If enabled: strict storage, rotation, and revocation
• Use backend controls, not client-side persistence

Next Step

→ Reference — Endpoint contracts, environment variables, and platform setup details