Simple Authentication Flow Endpoints

Simple Authentication Flow Endpoints

Table of Contents

1. Introduction
2. Architecture Overview
3. Registration Endpoints
4. Authentication Endpoints
5. Session Management
6. Credential Storage
7. Frontend Integration
8. Security Considerations
9. Error Handling
10. Examples

Introduction

The Post-Quantum WebAuthn Platform provides a simplified authentication flow through four core endpoints that enable secure passkey registration and authentication. This simple flow uses default configurations optimized for post-quantum cryptographic algorithms while maintaining compatibility with standard WebAuthn protocols.

The authentication system supports both classical and post-quantum cryptographic algorithms, automatically selecting appropriate COSE algorithm parameters and handling attestation verification for enhanced security. The platform integrates seamlessly with modern browsers' WebAuthn APIs while providing robust session management and credential persistence.

Architecture Overview

The simple authentication flow consists of two main phases: registration and authentication. Each phase involves coordinated interactions between frontend JavaScript, backend API endpoints, and underlying storage systems.

sequenceDiagram
participant Client as "Browser Client"
participant Frontend as "Frontend JS"
participant Backend as "API Server"
participant Storage as "Credential Storage"
participant Authenticator as "Authenticator Device"
Note over Client,Authenticator : Registration Flow
Client->>Frontend : User clicks Register
Frontend->>Backend : POST /api/register/begin
Backend-->>Frontend : Registration Options
Frontend->>Authenticator : WebAuthn Create Request
Authenticator-->>Frontend : Generated Credential
Frontend->>Backend : POST /api/register/complete
Backend->>Storage : Store Credential Data
Storage-->>Backend : Confirmation
Backend-->>Frontend : Registration Success
Note over Client,Authenticator : Authentication Flow
Client->>Frontend : User clicks Authenticate
Frontend->>Backend : POST /api/authenticate/begin
Backend-->>Frontend : Authentication Options
Frontend->>Authenticator : WebAuthn Get Request
Authenticator-->>Frontend : Assertion Response
Frontend->>Backend : POST /api/authenticate/complete
Backend-->>Frontend : Authentication Success

Loading

Diagram sources

• server/server/routes/simple.py
• server/server/routes/simple.py
• server/server/static/scripts/simple/auth-simple.js
• server/server/static/scripts/simple/auth-simple.js

Registration Endpoints

/api/register/begin - Registration Initialization

HTTP Method: POST
URL Pattern: /api/register/begin?email={email}

This endpoint initiates the registration process by generating registration options with appropriate COSE algorithm parameters and attestation configurations.

Request Parameters

Parameter	Type	Location	Description
email	string	Query	User email address for credential association
credentials	array	Body	Existing credentials to exclude from registration
existingCredentials	array	Body	Alternative parameter name for existing credentials

Request Schema

{
  "credentials": [
    {
      "credentialId": "base64url_encoded_id",
      "aaguid": "base64url_encoded_aaguid",
      "publicKey": "base64url_encoded_public_key",
      "algorithm": -49,
      "signCount": 0
    }
  ]
}

Response Schema

{
  "status": "OK",
  "publicKey": {
    "challenge": "base64url_encoded_challenge",
    "rp": {
      "id": "example.com",
      "name": "Example RP"
    },
    "user": {
      "id": "base64url_encoded_user_id",
      "name": "a_user",
      "displayName": "A. User"
    },
    "pubKeyCredParams": [
      {
        "type": "public-key",
        "alg": -49
      },
      {
        "type": "public-key",
        "alg": -50
      }
    ],
    "timeout": 90000,
    "attestation": "none",
    "authenticatorSelection": {
      "authenticatorAttachment": "cross-platform",
      "requireResidentKey": false,
      "userVerification": "discouraged"
    }
  },
  "__session_state": "session_state_data"
}

Implementation Details

The registration begin endpoint performs several critical operations:

1. Session Management: Stores registration state and public key options in the Flask session
2. Algorithm Selection: Filters available COSE algorithms to include only supported post-quantum and classical algorithms
3. Existing Credentials: Processes existing credentials to exclude them from the new registration
4. RP Configuration: Determines relying party ID and creates appropriate registration options

Section sources

• server/server/routes/simple.py

/api/register/complete - Registration Completion

HTTP Method: POST
URL Pattern: /api/register/complete?email={email}

This endpoint completes the registration process by validating the attestation response, performing security checks, and storing the credential data.

Request Parameters

Parameter	Type	Location	Description
email	string	Query	User email address associated with registration
response	object	Body	WebAuthn registration response from authenticator
__session_state	object	Body	Session state for validation (optional)

Request Schema

{
  "id": "base64url_encoded_credential_id",
  "rawId": "base64url_encoded_credential_id",
  "response": {
    "attestationObject": "base64url_encoded_attestation_object",
    "clientDataJSON": "base64url_encoded_client_data"
  },
  "type": "public-key",
  "clientExtensionResults": {},
  "__session_state": {
    "challenge": "base64url_encoded_challenge",
    "timeout": 90000,
    "rpId": "example.com"
  }
}

Response Schema

{
  "status": "OK",
  "algo": "ML-DSA-65 (PQC)",
  "attestationFormat": "packed",
  "storedCredential": {
    "type": "simple",
    "email": "user@example.com",
    "userName": "user@example.com",
    "displayName": "user@example.com",
    "credentialId": "base64_encoded_credential_id",
    "credentialIdBase64Url": "base64url_encoded_credential_id",
    "aaguid": "base64url_encoded_aaguid",
    "publicKey": "base64_encoded_public_key",
    "publicKeyAlgorithm": -49,
    "signCount": 0,
    "createdAt": 1640995200.0,
    "attestationFormat": "packed",
    "properties": {
      "attestationSignatureValid": true,
      "attestationRootValid": true,
      "attestationRpIdHashValid": true,
      "attestationAaguidMatch": true
    }
  },
  "relyingParty": {
    "attestationFmt": "packed",
    "credentialId": "hex_encoded_credential_id",
    "publicKeyAlgorithm": -49,
    "registrationData": {
      "flags": {
        "UP": true,
        "UV": false,
        "AT": true,
        "ED": false
      },
      "signatureCounter": 0
    }
  }
}

Processing Pipeline

The registration completion endpoint implements a comprehensive validation pipeline:

1. State Validation: Verifies session state and challenge integrity
2. Attestation Processing: Extracts and validates attestation statements
3. Security Checks: Performs signature validation, root certificate verification, and RP ID hash validation
4. Credential Storage: Persists credential data with metadata and properties
5. Session Cleanup: Removes temporary session data

Section sources

• server/server/routes/simple.py

Authentication Endpoints

/api/authenticate/begin - Authentication Initialization

HTTP Method: POST
URL Pattern: /api/authenticate/begin?email={email}

This endpoint initiates the authentication process by retrieving stored credentials and generating authentication options.

Request Parameters

Parameter	Type	Location	Description
email	string	Query	User email address for credential lookup
credentials	array	Body	Stored credentials for authentication
storedCredentials	array	Body	Alternative parameter name for stored credentials

Request Schema

{
  "credentials": [
    {
      "credentialId": "base64url_encoded_id",
      "aaguid": "base64url_encoded_aaguid",
      "publicKey": "base64url_encoded_public_key",
      "algorithm": -49,
      "signCount": 0
    }
  ]
}

Response Schema

{
  "publicKey": {
    "challenge": "base64url_encoded_challenge",
    "rpId": "example.com",
    "allowCredentials": [
      {
        "type": "public-key",
        "id": "base64url_encoded_credential_id"
      }
    ],
    "timeout": 90000,
    "userVerification": "discouraged"
  },
  "__session_state": "session_state_data"
}

Implementation Details

The authentication begin endpoint:

1. Credential Retrieval: Fetches stored credentials from session or storage
2. Option Generation: Creates authentication options with appropriate challenges
3. State Management: Stores authentication state for session validation
4. Error Handling: Returns 404 if no credentials are found for the user

Section sources

• server/server/routes/simple.py

/api/authenticate/complete - Authentication Completion

HTTP Method: POST
URL Pattern: /api/authenticate/complete?email={email}

This endpoint completes the authentication process by validating the assertion response and updating credential counters.

Request Parameters

Parameter	Type	Location	Description
email	string	Query	User email address for authentication
response	object	Body	WebAuthn assertion response from authenticator
__session_state	object	Body	Session state for validation (optional)

Request Schema

{
  "id": "base64url_encoded_credential_id",
  "rawId": "base64url_encoded_credential_id",
  "response": {
    "authenticatorData": "base64url_encoded_authenticator_data",
    "clientDataJSON": "base64url_encoded_client_data",
    "signature": "base64url_encoded_signature",
    "userHandle": "base64url_encoded_user_handle"
  },
  "type": "public-key",
  "clientExtensionResults": {},
  "__session_state": {
    "challenge": "base64url_encoded_challenge",
    "timeout": 90000,
    "rpId": "example.com"
  }
}

Response Schema

{
  "status": "OK",
  "authenticatedCredentialId": "base64url_encoded_credential_id",
  "signCount": 123
}

Processing Pipeline

The authentication completion endpoint:

1. State Validation: Verifies session state and challenge integrity
2. Assertion Verification: Validates the authenticator's signature and data
3. Counter Update: Updates the credential's signature counter
4. Session Cleanup: Removes authentication state from session
5. Success Response: Returns authentication confirmation with updated counter

Section sources

• server/server/routes/simple.py

Session Management

The simple authentication flow uses Flask session management for temporary state storage during registration and authentication processes.

Session Data Structure

graph TD
A[Flask Session] --> B[state]
A --> C[simple_credentials]
A --> D[simple_credentials_email]
A --> E[simple_register_public_key]
A --> F[register_rp_id]
A --> G[authenticate_rp_id]
B --> B1[Registration/Authentication State]
C --> C1[Stored Credentials List]
D --> D1[Associated Email]
E --> E1[Registration Public Key Options]
F --> F1[Registration Relying Party ID]
G --> G1[Authentication Relying Party ID]

Loading

Diagram sources

• server/server/routes/simple.py
• server/server/routes/simple.py

Session Lifecycle

The session management follows a strict lifecycle pattern:

1. Registration Phase:

   • state: Stores registration challenge and options
   • simple_register_public_key: Contains public key parameters
   • register_rp_id: Relying party identifier

2. Authentication Phase:

   • state: Stores authentication challenge and options
   • authenticate_rp_id: Relying party identifier
   • simple_credentials: List of stored credentials

3. Cleanup:

   • Sessions are automatically cleared after successful completion
   • Temporary data is removed to prevent replay attacks

Section sources

• server/server/routes/simple.py
• server/server/routes/simple.py

Credential Storage

The platform implements a dual-storage system supporting both local filesystem storage and Google Cloud Storage for credential persistence.

Storage Architecture

graph TB
subgraph "Storage Backends"
A[Local Filesystem]
B[Google Cloud Storage]
end
subgraph "Storage Components"
C[Credential Data]
D[Metadata]
E[Session Data]
end
subgraph "Storage Operations"
F[savekey]
G[readkey]
H[delkey]
I[iter_credentials]
end
A --> C
B --> C
A --> D
B --> D
A --> E
B --> E
F --> A
F --> B
G --> A
G --> B
H --> A
H --> B
I --> A
I --> B

Loading

Diagram sources

• server/server/storage.py
• server/server/storage.py

Credential Data Structure

Each stored credential contains comprehensive metadata and cryptographic material:

Field	Type	Description
credential_data	object	Attested credential data from authenticator
auth_data	object	Authenticator data and flags
user_info	object	User identity information
registration_time	number	Unix timestamp of registration
client_data_json	string	Base64-encoded client data
attestation_object	string	Base64-encoded attestation object
attestation_format	string	Attestation format type
attestation_statement	object	Attestation statement data
client_extension_outputs	object	Client extension results
properties	object	Additional credential properties

Storage Operations

The storage system provides atomic operations for credential management:

1. Save Operation: Serializes and persists credential data using pickle
2. Read Operation: Deserializes stored credential data
3. Delete Operation: Removes credential data and associated metadata
4. Iterate Operation: Enumerates all stored credentials

Section sources

• server/server/storage.py
• server/server/storage.py

Frontend Integration

The frontend integration provides seamless WebAuthn API interaction through JavaScript modules that handle the complete authentication flow.

Frontend Architecture

sequenceDiagram
participant UI as "User Interface"
participant JS as "auth-simple.js"
participant WebAuthn as "WebAuthn API"
participant Server as "API Server"
Note over UI,Server : Registration Flow
UI->>JS : simpleRegister()
JS->>Server : POST /api/register/begin
Server-->>JS : Registration Options
JS->>WebAuthn : create(options)
WebAuthn-->>JS : Generated Credential
JS->>Server : POST /api/register/complete
Server-->>JS : Registration Result
JS->>UI : Display Success Message
Note over UI,Server : Authentication Flow
UI->>JS : simpleAuthenticate()
JS->>Server : POST /api/authenticate/begin
Server-->>JS : Authentication Options
JS->>WebAuthn : get(options)
WebAuthn-->>JS : Assertion Response
JS->>Server : POST /api/authenticate/complete
Server-->>JS : Authentication Result
JS->>UI : Display Success Message

Loading

Diagram sources

• server/server/static/scripts/simple/auth-simple.js
• server/server/static/scripts/simple/auth-simple.js

Error Handling

The frontend implements comprehensive error handling for various WebAuthn scenarios:

Error Type	Browser Error	User-Friendly Message
Cancelled	NotAllowedError	"User cancelled or authenticator not available"
Already Registered	InvalidStateError	"Authenticator is already registered for this account"
Security Issue	SecurityError	"Security error - check your connection and try again"
Not Supported	NotSupportedError	"WebAuthn is not supported in this browser"

Local Storage Integration

The frontend maintains a local credential cache using browser localStorage for offline access and improved performance:

1. Credential Persistence: Stores generated credentials locally
2. Automatic Loading: Loads stored credentials for authentication
3. Counter Updates: Updates signature counts after successful authentication
4. Cleanup: Provides mechanisms to clear stored credentials

Section sources

• server/server/static/scripts/simple/auth-simple.js
• server/server/static/scripts/simple/auth-simple.js
• server/server/static/scripts/shared/local-storage.js

Security Considerations

The simple authentication flow implements multiple layers of security to protect against common attack vectors and ensure cryptographic integrity.

Input Validation

The backend implements comprehensive input validation:

1. Challenge Validation: Ensures challenges are properly formatted and not expired
2. Credential ID Validation: Validates credential identifiers and prevents tampering
3. Signature Verification: Cryptographically verifies all signatures and attestations
4. RP ID Verification: Validates relying party identifiers and hashes

State Management Security

Session state management incorporates several security measures:

1. Challenge Binding: Associates challenges with specific sessions
2. Timeout Protection: Implements reasonable timeouts for authentication flows
3. State Isolation: Prevents cross-session state leakage
4. Cleanup Mechanisms: Automatically clears sensitive data after completion

Attestation Security

The platform implements robust attestation verification:

1. Certificate Chain Validation: Verifies complete certificate chains
2. Root Certificate Trust: Validates against trusted root certificates
3. Algorithm Integrity: Ensures cryptographic algorithm consistency
4. Metadata Verification: Cross-references with FIDO Metadata Service

Replay Attack Prevention

Multiple mechanisms prevent replay attacks:

1. Challenge Uniqueness: Each challenge is unique and single-use
2. Timestamp Validation: Validates timestamps and expiration
3. Counter Monitoring: Tracks and validates signature counters
4. Session Isolation: Maintains separate sessions for different operations

Section sources

• server/server/routes/simple.py
• server/server/attestation.py

Error Handling

The authentication endpoints implement structured error handling with meaningful error messages and appropriate HTTP status codes.

Error Response Patterns

Endpoint	Error Conditions	HTTP Status	Response Format
/api/register/begin	Invalid email format, malformed credentials	400	{ "error": "message" }
/api/register/complete	Missing session state, invalid attestation	400	{ "error": "message" }
/api/authenticate/begin	No credentials found, invalid email	404	{ "error": "message" }
/api/authenticate/complete	Authentication state expired, invalid signature	400	{ "error": "message" }

Error Recovery Strategies

1. State Expiration: Clear expired session state automatically
2. Retry Mechanisms: Allow retry with fresh challenges
3. Graceful Degradation: Provide fallback options for unsupported features
4. User Guidance: Offer clear instructions for resolving common errors

Section sources

• server/server/routes/simple.py
• server/server/routes/simple.py

Examples

Registration Example

Step 1: Begin Registration

curl -X POST "https://example.com/api/register/begin?email=user@example.com" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "publicKey": {
    "challenge": "dGVzdF9jaGFsbGVuZ2U=",
    "rp": {
      "id": "example.com",
      "name": "Example RP"
    },
    "user": {
      "id": "dXNlcg==",
      "name": "a_user",
      "displayName": "A. User"
    },
    "pubKeyCredParams": [
      {
        "type": "public-key",
        "alg": -49
      }
    ],
    "timeout": 90000,
    "attestation": "none",
    "authenticatorSelection": {
      "authenticatorAttachment": "cross-platform",
      "requireResidentKey": false,
      "userVerification": "discouraged"
    }
  },
  "__session_state": "eyJjaGFsbGVuZ2UiOiAi...",
  "status": "OK"
}

Step 2: Complete Registration

curl -X POST "https://example.com/api/register/complete?email=user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "credential_id",
    "rawId": "credential_id",
    "response": {
      "attestationObject": "base64_encoded_attestation",
      "clientDataJSON": "base64_encoded_client_data"
    },
    "type": "public-key",
    "__session_state": {
      "challenge": "dGVzdF9jaGFsbGVuZ2U="
    }
  }'

Response:

{
  "status": "OK",
  "algo": "ML-DSA-65 (PQC)",
  "storedCredential": {
    "type": "simple",
    "email": "user@example.com",
    "credentialId": "base64_encoded_id",
    "publicKeyAlgorithm": -49,
    "signCount": 0,
    "createdAt": 1640995200.0
  },
  "relyingParty": {
    "attestationFmt": "packed",
    "credentialId": "hex_encoded_id",
    "publicKeyAlgorithm": -49
  }
}

Authentication Example

Step 1: Begin Authentication

curl -X POST "https://example.com/api/authenticate/begin?email=user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": [
      {
        "credentialId": "base64url_encoded_id",
        "aaguid": "base64url_encoded_aaguid",
        "publicKey": "base64url_encoded_public_key",
        "algorithm": -49
      }
    ]
  }'

Response:

{
  "publicKey": {
    "challenge": "dGVzdF9jaGFsbGVuZ2U=",
    "rpId": "example.com",
    "allowCredentials": [
      {
        "type": "public-key",
        "id": "base64url_encoded_credential_id"
      }
    ],
    "timeout": 90000,
    "userVerification": "discouraged"
  },
  "__session_state": "eyJjaGFsbGVuZ2UiOiAi..."
}

Step 2: Complete Authentication

curl -X POST "https://example.com/api/authenticate/complete?email=user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "credential_id",
    "rawId": "credential_id",
    "response": {
      "authenticatorData": "base64_encoded_auth_data",
      "clientDataJSON": "base64_encoded_client_data",
      "signature": "base64_encoded_signature"
    },
    "type": "public-key",
    "__session_state": {
      "challenge": "dGVzdF9jaGFsbGVuZ2U="
    }
  }'

Response:

{
  "status": "OK",
  "authenticatedCredentialId": "base64url_encoded_credential_id",
  "signCount": 123
}