Skip to main content

WebAuthn / Passkeys Authentication Guide

Overview

ZewstID provides production-ready WebAuthn/Passkeys authentication, enabling passwordless and multi-factor authentication using biometrics (Face ID, Touch ID, Android Biometric) and hardware security keys.

Key Features

✅ Platform Authenticators

  • iOS: Face ID, Touch ID
  • Android: Biometric Prompt (fingerprint, face, iris)
  • Desktop: Windows Hello, Touch ID

✅ Security Features

  • FIDO2/WebAuthn compliant
  • Phishing-resistant authentication
  • Counter-based replay attack prevention
  • User verification required
  • Origin and RP ID validation
  • Resident keys (discoverable credentials)

✅ Multi-Factor Authentication

  • Password + Biometric
  • Passwordless biometric-only authentication
  • Step-up authentication for sensitive operations

Authentication Flows

Flow 1: Password + Biometric (Recommended for High Security)

1. User enters password
2. Password validated via OAuth/OIDC
3. System prompts for biometric verification
4. User authenticates with Face ID/Touch ID
5. Full access granted with MFA claim in token

Flow 2: Passwordless Biometric (Recommended for UX)

1. User taps "Sign in with Face ID"
2. Biometric prompt appears
3. Authentication verified
4. Access granted immediately

Flow 3: Conditional MFA (Smart Security)

1. User logs in with password
2. If low-risk: Access granted
3. If high-risk: Biometric verification required
   - New device
   - Unusual location
   - Sensitive operation

Architecture

┌─────────────────┐
│  Mobile App     │
│  (iOS/Android)  │
└────────┬────────┘
         │
         │ HTTPS
         ▼
┌─────────────────┐
│  ZewstID API    │
│  Gateway        │
│  (Port 3000)    │
└────────┬────────┘
         │
         ├──► WebAuthn Service
         │    - Challenge generation
         │    - Credential verification
         │    - Redis storage
         │
         ├──► Auth Service
         │    - User management
         │    - Token issuance
         │
         └──► Audit Logger
              - MFA events
              - Security monitoring

Security Guarantees

Phishing Resistance

  • Credentials bound to origin (domain)
  • Cannot be used on phishing sites
  • Browser/OS enforces origin check

Replay Attack Prevention

  • Challenge-response mechanism
  • 5-minute challenge expiration
  • Counter increment on each use
  • Challenge consumed after verification

Credential Protection

  • Private keys never leave device
  • Stored in Secure Enclave (iOS) / TEE (Android)
  • Biometric gates access to private keys
  • No credential export possible

User Verification

  • Biometric verification required
  • User presence verified
  • Device PIN as fallback
  • No "something you have" only auth

API Endpoints

Base URL:

https://api.zewstid.com/api/v1

Registration

  • POST /auth/webauthn/register/begin
    - Start credential registration
  • POST /auth/webauthn/register/finish
    - Complete registration

Authentication

  • POST /auth/webauthn/authenticate/begin
    - Start authentication
  • POST /auth/webauthn/authenticate/finish
    - Complete authentication & get tokens

Management

  • GET /auth/webauthn/credentials
    - List user's credentials
  • PUT /auth/webauthn/credentials/:id
    - Update credential name
  • DELETE /auth/webauthn/credentials/:id
    - Delete credential

Implementation Guides

Quick Start

Prerequisites

  1. OAuth client registered in ZewstID
  2. HTTPS enabled (required for WebAuthn)
  3. Associated domain configured (iOS)
  4. Digital Asset Links configured (Android)

iOS (5 minutes)

import AuthenticationServices

// 1. Register Face ID
let biometricManager = ZewstBiometricManager(
    apiBaseURL: "https://api.zewstid.com",
    clientID: "your-client-id"
)

await biometricManager.registerBiometric(idToken: token)

// 2. Authenticate with Face ID
let tokens = await biometricManager.authenticateWithBiometric()

Android (5 minutes)

import androidx.biometric.BiometricPrompt

// 1. Register biometric
val biometricManager = ZewstBiometricManager(
    context = context,
    apiBaseUrl = "https://api.zewstid.com",
    clientId = "your-client-id"
)

biometricManager.registerBiometric(idToken)

// 2. Authenticate with biometric
val tokens = biometricManager.authenticateWithBiometric()

Testing

Test Credentials

Email: test@example.com
Password: TestPassword123!

Test API Endpoints

# Start authentication
curl -X POST https://api.zewstid.com/api/v1/auth/webauthn/authenticate/begin \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com"}'

# Response includes challenge for credential
{
  "options": {
    "challenge": "base64-challenge",
    "timeout": 60000,
    "userVerification": "preferred",
    "rpId": "zewst.com"
  }
}

Admin Dashboard

Monitor and manage passkeys at: https://admin.zewstid.com/passkeys

  • View all registered passkeys
  • See device types and usage
  • Revoke compromised credentials
  • Track biometric authentication events

Security Best Practices

For Developers

  1. Always use HTTPS - WebAuthn requires secure context
  2. Validate challenges - Server-side verification is critical
  3. Store counters - Detect cloned credentials
  4. Audit logs - Monitor MFA events
  5. Graceful degradation - Fallback to password if biometric fails

For Users

  1. Register backup methods - Add multiple devices
  2. Enable device PIN - Biometric fallback
  3. Review devices - Check registered passkeys regularly
  4. Remove old devices - Delete unused credentials
  5. Report lost devices - Contact admin immediately

Troubleshooting

iOS: Face ID not working

- Check Info.plist has NSFaceIDUsageDescription
- Verify device supports Face ID
- Ensure user has enrolled Face ID in Settings
- Check associated domains configured

Android: Biometric prompt not showing

- Check device has biometric hardware
- Verify user has enrolled biometric
- Ensure BiometricPrompt API is used (not deprecated)
- Check app permissions

Challenge expired

- Challenges expire in 5 minutes
- Re-request challenge from begin endpoint
- Don't cache challenges client-side

Origin mismatch

- Ensure app URL matches registered origin
- Check Associated Domains (iOS)
- Check Digital Asset Links (Android)
- Verify HTTPS certificate valid

Performance

  • Challenge generation: < 50ms
  • Credential verification: < 100ms
  • Total authentication time: < 2 seconds
  • Challenge TTL: 5 minutes
  • Credential storage: Redis (in-memory)

Compliance

✅ FIDO2/WebAuthn Level 2 compliant ✅ W3C WebAuthn specification ✅ NIST SP 800-63B AAL2/AAL3 ✅ PSD2 SCA compliant ✅ GDPR compliant (biometrics never leave device)

Support

Next Steps

  1. Set up iOS integration
  2. Set up Android integration
  3. Configure MFA policies
  4. Test your integration

Was this page helpful?

Let us know how we can improve our documentation