Simple Authentication Interface

Simple Authentication Interface API Documentation

Table of Contents

1. Introduction
2. Architecture Overview
3. Exported Functions
4. Core API Functions
5. Browser WebAuthn Integration
6. Backend Integration
7. Error Handling and User Feedback
8. Browser Compatibility
9. Usage Examples
10. Limitations and Comparison

Introduction

The Simple Authentication Interface provides a streamlined WebAuthn authentication experience through the auth-simple.js module. This interface enables users to register and authenticate using passkeys with minimal configuration, leveraging the browser's native WebAuthn API through the webauthn-json.browser-ponyfill.js library. The simple flow offers default presets for common authentication scenarios while maintaining security through FIDO2 standards.

The interface consists of two primary functions: simpleRegister() for credential creation and simpleAuthenticate() for user verification. Both functions handle the complete WebAuthn flow, from initial challenge generation to final credential storage, with comprehensive error handling and user feedback mechanisms.

Architecture Overview

The simple authentication interface follows a client-server architecture with clear separation of concerns:

graph TB
    subgraph "Client-Side"
        UI["User Interface"]
        AuthJS["auth-simple.js"]
        WebAuthnPonyfill["webauthn-json.browser-ponyfill.js"]
        Status["Status Management"]
        LocalStorage["Local Storage"]
    end
    subgraph "Server-Side"
        FlaskApp["Flask Application"]
        SimpleRoutes["simple.py Routes"]
        FidoServer["FIDO2 Server"]
        Storage["Storage Backend"]
    end
    UI --> AuthJS
    AuthJS --> WebAuthnPonyfill
    AuthJS --> Status
    AuthJS --> LocalStorage
    AuthJS <--> FlaskApp
    FlaskApp --> SimpleRoutes
    SimpleRoutes --> FidoServer
    SimpleRoutes --> Storage

Loading

Diagram sources

• auth-simple.js
• simple.py

Section sources

• auth-simple.js
• simple.py

Exported Functions

The auth-simple.js module exports two primary functions for WebAuthn authentication:

Function Signatures

export async function simpleRegister()
export async function simpleAuthenticate()

Both functions accept no parameters and operate on form data retrieved from the DOM. They return promises that resolve when the authentication flow completes successfully or reject with an error if the operation fails.

Function Parameters

The functions rely on HTML form elements with specific IDs:

• #simple-email: User identifier (typically email address)
• Progress indicators: Loading states during authentication flow
• Status displays: User feedback and error messages

Return Value Structures

Both functions return Promise<void> and handle their own state management internally. Successful operations trigger credential storage updates and UI state changes, while failures are handled through the error handling mechanism.

Section sources

• auth-simple.js

Core API Functions

simpleRegister()

The registration function initiates the WebAuthn credential creation process:

sequenceDiagram
participant User as User
participant UI as User Interface
participant AuthJS as auth-simple.js
participant Server as Flask Backend
participant Browser as Browser WebAuthn API
User->>UI : Enter email and click Register
UI->>AuthJS : simpleRegister()
AuthJS->>AuthJS : Validate email input
AuthJS->>Server : POST /api/register/begin
Server-->>AuthJS : Registration options
AuthJS->>Browser : navigator.credentials.create()
Browser-->>AuthJS : Created credential
AuthJS->>Server : POST /api/register/complete
Server-->>AuthJS : Registration result
AuthJS->>AuthJS : Store credential locally
AuthJS-->>UI : Success notification

Loading

Diagram sources

• auth-simple.js
• simple.py

Registration Flow Details

1. Input Validation: Validates email presence and format
2. Begin Registration: Sends email to /api/register/begin endpoint
3. Challenge Generation: Receives WebAuthn challenge from server
4. Credential Creation: Uses browser WebAuthn API to create credential
5. Completion: Submits credential to /api/register/complete endpoint
6. Storage: Stores credential in local browser storage
7. Feedback: Provides success/error notifications to user

simpleAuthenticate()

The authentication function validates user identity using existing credentials:

sequenceDiagram
participant User as User
participant UI as User Interface
participant AuthJS as auth-simple.js
participant Server as Flask Backend
participant Browser as Browser WebAuthn API
User->>UI : Enter email and click Authenticate
UI->>AuthJS : simpleAuthenticate()
AuthJS->>AuthJS : Validate email input
AuthJS->>AuthJS : Load stored credentials
AuthJS->>Server : POST /api/authenticate/begin
Server-->>AuthJS : Authentication options
AuthJS->>Browser : navigator.credentials.get()
Browser-->>AuthJS : Authentication assertion
AuthJS->>Server : POST /api/authenticate/complete
Server-->>AuthJS : Authentication result
AuthJS->>AuthJS : Update credential counters
AuthJS-->>UI : Success notification

Loading

Diagram sources

• auth-simple.js
• simple.py

Authentication Flow Details

1. Credential Retrieval: Loads stored credentials for the user
2. Begin Authentication: Sends credentials to /api/authenticate/begin endpoint
3. Challenge Generation: Receives authentication challenge from server
4. Assertion Request: Uses browser WebAuthn API to request authentication
5. Validation: Submits assertion to /api/authenticate/complete endpoint
6. Counter Update: Updates credential signature counters
7. Feedback: Provides success/error notifications to user

Section sources

• auth-simple.js
• simple.py

Browser WebAuthn Integration

The interface integrates with the browser's WebAuthn API through the webauthn-json.browser-ponyfill.js library, which handles the conversion between JSON and CBOR-encoded binary data required by the WebAuthn specification.

Library Integration

The ponyfill provides essential WebAuthn API functions:

import {
    create,
    get,
    parseCreationOptionsFromJSON,
    parseRequestOptionsFromJSON
} from '../shared/webauthn-json.browser-ponyfill.js';

Data Conversion Process

The library handles automatic conversion between JSON and binary formats:

flowchart LR
JSON[JSON Options] --> Parse[parseCreationOptionsFromJSON]
Parse --> CBOR[CBOR Binary Data]
CBOR --> WebAuthn[Browser WebAuthn API]
WebAuthn --> CBOR2[Binary Response]
CBOR2 --> Convert[getResponseToJSON]
Convert --> JSON2[JSON Response]

Loading

Diagram sources

• webauthn-json.browser-ponyfill.js

Supported Features

The integration supports:

• Credential creation with attestation
• Authentication assertions
• Extension processing
• Base64 URL encoding/decoding
• Automatic JSON-to-binary conversion

Section sources

• webauthn-json.browser-ponyfill.js
• auth-simple.js

Backend Integration

The simple authentication interface communicates with Python Flask backend routes that implement FIDO2 WebAuthn standards.

Registration Endpoint Integration

sequenceDiagram
participant Client as Client Script
participant Flask as Flask Server
participant Fido2 as FIDO2 Library
participant Storage as Storage Backend
Client->>Flask : POST /api/register/begin
Note right of Flask : Extract email from query
Flask->>Fido2 : server.register_begin()
Fido2-->>Flask : Registration options + state
Flask->>Flask : Filter algorithms
Flask-->>Client : JSON registration options
Client->>Flask : POST /api/register/complete
Note right of Flask : Validate attestation
Flask->>Fido2 : server.register_complete()
Fido2-->>Flask : Authenticated credential
Flask->>Storage : Store credential data
Flask-->>Client : Registration result

Loading

Diagram sources

• simple.py
• simple.py

Authentication Endpoint Integration

sequenceDiagram
participant Client as Client Script
participant Flask as Flask Server
participant Fido2 as FIDO2 Library
participant Storage as Storage Backend
Client->>Flask : POST /api/authenticate/begin
Note right of Flask : Load stored credentials
Flask->>Fido2 : server.authenticate_begin()
Fido2-->>Flask : Authentication options + state
Flask-->>Client : JSON authentication options
Client->>Flask : POST /api/authenticate/complete
Note right of Flask : Validate assertion
Flask->>Fido2 : server.authenticate_complete()
Fido2-->>Flask : Matched credential + counter
Flask-->>Client : Authentication result

Loading

Diagram sources

• simple.py
• simple.py

Algorithm Support

The backend supports specific cryptographic algorithms optimized for post-quantum security:

Algorithm	Identifier	Security Type
ML-DSA-87	-50	Post-Quantum
ML-DSA-65	-49	Post-Quantum
ML-DSA-44	-48	Post-Quantum
ES256	-7	Classical ECDSA
RS256	-257	Classical RSA

Section sources

• simple.py
• simple.py

Error Handling and User Feedback

The interface implements comprehensive error handling with user-friendly feedback mechanisms.

Error Classification

flowchart TD
Error[WebAuthn Error] --> Type{Error Type}
Type --> |NotAllowedError| UserCancelled[User Cancelled/Unavailable]
Type --> |InvalidStateError| InvalidState[Authenticator State Error]
Type --> |SecurityError| Security[Security Issue]
Type --> |NotSupportedError| Unsupported[Browser Not Supported]
Type --> |NetworkError| Network[Network Issue]
UserCancelled --> Message1["User cancelled or authenticator not available"]
InvalidState --> Message2["Authenticator is already registered for this account<br/>or invalid credential"]
Security --> Message3["Security error - check your connection and try again"]
Unsupported --> Message4["WebAuthn is not supported in this browser"]
Network --> Message5["Server communication failed"]

Loading

Diagram sources

• auth-simple.js
• auth-simple.js

Status Management

The interface uses a centralized status management system:

// Show status messages
showStatus(tabId, message, type)

// Hide status messages  
hideStatus(tabIdOrElement)

// Show progress indicators
showProgress(tabId, message)
hideProgress(tabIdOrElement)

Error Handling Patterns

1. WebAuthn API Errors: Catch and classify browser-specific errors
2. Network Errors: Handle server communication failures
3. Validation Errors: Manage input validation and business logic errors
4. State Errors: Handle session and state management issues

Section sources

• auth-simple.js
• auth-simple.js
• status.js

Browser Compatibility

The simple authentication interface supports modern browsers with WebAuthn capabilities.

Supported Browsers

• Chrome: Version 67+ (full support)
• Firefox: Version 60+ (full support)
• Safari: Version 14+ (full support)
• Edge: Version 79+ (full support)

Feature Detection

The interface automatically detects WebAuthn support:

// Basic WebAuthn support detection
if (!('PublicKeyCredential' in window)) {
    // WebAuthn not supported
}

// Platform authenticator detection
if (typeof PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable === 'function') {
    // Platform authenticator available
}

Transport Methods

The interface supports multiple transport methods:

• Internal: Touch/Face ID, PIN, Pattern
• USB: Hardware security keys
• NFC: Near Field Communication
• Bluetooth: Wireless security keys
• Hybrid: Combination of methods

Limitations

1. Legacy Browsers: Older browsers without WebAuthn support
2. Private Mode: Some browsers restrict WebAuthn in private/incognito mode
3. Corporate Policies: Enterprise restrictions on WebAuthn usage
4. Hardware Compatibility: Limited support for older or specialized hardware

Section sources

• analyze-browser.js

Usage Examples

Basic Registration Example

<!-- HTML Form Setup -->
<div class="simple-auth-section">
    <div class="form-group">
        <label for="simple-email">Username</label>
        <input type="text" id="simple-email" placeholder="Enter username">
    </div>
    <button onclick="simpleRegister()">Register Passkey</button>
</div>

Basic Authentication Example

<!-- HTML Form Setup -->
<div class="simple-auth-section">
    <div class="form-group">
        <label for="simple-email">Username</label>
        <input type="text" id="simple-email" placeholder="Enter username">
    </div>
    <button onclick="simpleAuthenticate()">Authenticate</button>
</div>

Programmatic Usage

// Register a new credential
try {
    await simpleRegister();
    console.log('Registration successful');
} catch (error) {
    console.error('Registration failed:', error.message);
}

// Authenticate existing user
try {
    await simpleAuthenticate();
    console.log('Authentication successful');
} catch (error) {
    console.error('Authentication failed:', error.message);
}

Error Handling Example

// Enhanced error handling
async function secureSimpleRegister() {
    try {
        await simpleRegister();
        showStatus('simple', 'Registration successful!', 'success');
    } catch (error) {
        let userMessage = 'Registration failed';
        
        switch (error.name) {
            case 'NotAllowedError':
                userMessage = 'Please try again with your authenticator';
                break;
            case 'SecurityError':
                userMessage = 'Connection issue - please check your network';
                break;
            case 'NotSupportedError':
                userMessage = 'WebAuthn not supported in this browser';
                break;
        }
        
        showStatus('simple', userMessage, 'error');
    }
}

Section sources

• tab.html
• auth-simple.js

Limitations and Comparison

Simple Flow Advantages

1. Ease of Use: Minimal configuration required
2. Default Presets: Optimized for common use cases
3. Quick Setup: Single function calls for registration and authentication
4. Post-Quantum Ready: Built-in support for quantum-resistant algorithms

Simple Flow Limitations

1. Limited Customization: Fixed algorithm selection and authentication policies
2. No Resident Keys: Does not support credential persistence across devices
3. Basic Extensions: Limited extension support compared to advanced mode
4. Simplified UI: Less granular control over user experience

Comparison with Advanced Mode

Feature	Simple Mode	Advanced Mode
Algorithm Selection	Fixed (post-quantum + classical)	Customizable
Resident Keys	Not supported	Full support
Extensions	Basic support	Extensive support
Custom UI	Limited	Highly customizable
Debug Information	Basic	Comprehensive
Error Details	General	Specific

When to Choose Simple Mode

• Quick Prototyping: Rapid development and testing
• Standard Applications: Basic authentication requirements
• Post-Quantum Focus: Immediate quantum-resistant security
• Minimal Configuration: Quick deployment scenarios

When to Choose Advanced Mode

• Enterprise Applications: Complex authentication requirements
• Custom Workflows: Specialized user experiences
• Advanced Security: Fine-grained control over security policies
• Integration Projects: Complex system integrations

Section sources

• auth-simple.js
• simple.py