Advanced Configuration Flow Endpoints

Advanced Configuration Flow Endpoints

Table of Contents

1. Introduction
2. Endpoint Overview
3. Request/Response Schemas
4. Advanced WebAuthn Features
5. Algorithm Processing
6. Credential Parsing
7. Extension Parameters
8. Security Considerations
9. Examples
10. Error Handling

Introduction

The Post-Quantum WebAuthn Platform provides advanced configuration flow endpoints that enable sophisticated WebAuthn operations with extensive customization capabilities. These endpoints support advanced features including custom algorithm selection, authenticator attachment preferences, resident key requirements, and comprehensive extension parameters.

The advanced flow endpoints are designed for developers who need fine-grained control over WebAuthn operations beyond the basic simple registration and authentication flows. They provide JSON editor support, custom credential parameters, and advanced attestation processing capabilities.

Endpoint Overview

The platform exposes four primary advanced configuration endpoints:

Endpoint	Method	Purpose
/api/advanced/register/begin	POST	Begin advanced credential registration with custom parameters
/api/advanced/register/complete	POST	Complete advanced credential registration with attestation
/api/advanced/authenticate/begin	POST	Begin advanced authentication with custom credential selection
/api/advanced/authenticate/complete	POST	Complete advanced authentication with assertion verification

sequenceDiagram
participant Client as "Web Client"
participant Server as "Advanced API Server"
participant Authenticator as "Authenticator Device"
participant Storage as "Credential Storage"
Note over Client,Storage : Registration Flow
Client->>Server : POST /api/advanced/register/begin
Server-->>Client : Registration Options
Client->>Authenticator : Create Credential
Authenticator-->>Client : Registration Response
Client->>Server : POST /api/advanced/register/complete
Server->>Server : Validate Attestation
Server->>Storage : Store Credential
Server-->>Client : Registration Result
Note over Client,Storage : Authentication Flow
Client->>Server : POST /api/advanced/authenticate/begin
Server-->>Client : Authentication Options
Client->>Authenticator : Authenticate
Authenticator-->>Client : Assertion Response
Client->>Server : POST /api/advanced/authenticate/complete
Server->>Server : Verify Assertion
Server-->>Client : Authentication Result

Loading

Diagram sources

• server/server/routes/advanced.py
• server/server/routes/advanced.py

Request/Response Schemas

Registration Begin Endpoint

Request Schema:

{
  "publicKey": {
    "rp": {
      "id": "string",
      "name": "string"
    },
    "user": {
      "id": "string | object",
      "name": "string",
      "displayName": "string"
    },
    "challenge": "string",
    "pubKeyCredParams": [
      {
        "type": "public-key",
        "alg": "number | string"
      }
    ],
    "timeout": "number",
    "attestation": "none | direct | indirect | enterprise",
    "authenticatorSelection": {
      "authenticatorAttachment": "platform | cross-platform",
      "userVerification": "required | preferred | discouraged",
      "residentKey": "required | preferred | discouraged",
      "requireResidentKey": "boolean"
    },
    "excludeCredentials": [
      {
        "type": "public-key",
        "id": "string | object"
      }
    ],
    "extensions": {
      "credProps": "boolean",
      "minPinLength": "boolean",
      "credProtect": "number | string",
      "largeBlob": "object | string"
    },
    "hints": ["string"]
  }
}

Response Schema:

{
  "publicKey": {
    "challenge": "string",
    "rpId": "string",
    "allowCredentials": [
      {
        "type": "public-key",
        "id": "string"
      }
    ],
    "timeout": "number",
    "userVerification": "required | preferred | discouraged",
    "extensions": {
      "credProps": "boolean"
    }
  },
  "__session_state": "object",
  "warnings": ["string"]
}

Registration Complete Endpoint

Request Schema:

{
  "__credential_response": {
    "response": {
      "attestationObject": "string",
      "clientDataJSON": "string",
      "authenticatorData": "string",
      "transports": ["string"],
      "authenticatorAttachment": "platform | cross-platform"
    },
    "id": "string",
    "rawId": "string",
    "type": "public-key"
  },
  "__session_state": "object",
  "publicKey": {
    // Original request parameters
  }
}

Response Schema:

{
  "status": "OK",
  "algo": "string",
  "relyingParty": {
    "credentialId": "string",
    "publicKeyAlgorithm": "number",
    "attestationFormat": "string",
    "registrationData": {
      "authenticatorData": "string",
      "signatureCounter": "number",
      "flags": {
        "UP": "boolean",
        "UV": "boolean",
        "AT": "boolean",
        "BE": "boolean",
        "BS": "boolean",
        "ED": "boolean"
      }
    }
  },
  "storedCredential": {
    "credentialId": "string",
    "publicKeyAlgorithm": "number",
    "residentKey": "boolean",
    "authenticatorAttachment": "string"
  },
  "warnings": ["string"]
}

Authentication Begin Endpoint

Request Schema:

{
  "publicKey": {
    "challenge": "string",
    "timeout": "number",
    "userVerification": "required | preferred | discouraged",
    "allowCredentials": [
      {
        "type": "public-key",
        "id": "string | object"
      }
    ],
    "extensions": {
      "largeBlob": "object"
    },
    "hints": ["string"]
  },
  "storedCredentials": [
    {
      "credentialId": "string",
      "publicKey": "string",
      "resident": "boolean",
      "authenticatorAttachment": "platform | cross-platform"
    }
  ]
}

Response Schema:

{
  "publicKey": {
    "challenge": "string",
    "rpId": "string",
    "allowCredentials": [
      {
        "type": "public-key",
        "id": "string"
      }
    ],
    "timeout": "number",
    "userVerification": "required | preferred | discouraged"
  },
  "__session_state": "object"
}

Authentication Complete Endpoint

Request Schema:

{
  "__assertion_response": {
    "response": {
      "authenticatorData": "string",
      "clientDataJSON": "string",
      "signature": "string",
      "attestationObject": "string"
    },
    "id": "string",
    "rawId": "string",
    "type": "public-key"
  },
  "__session_state": "object",
  "publicKey": {
    // Original request parameters
  },
  "storedCredentials": [
    {
      "credentialId": "string",
      "publicKey": "string",
      "resident": "boolean"
    }
  ]
}

Response Schema:

{
  "status": "OK",
  "authenticatedCredentialId": "string",
  "signCount": "number",
  "algorithm": "number",
  "algorithmDescription": "string",
  "hintsUsed": ["string"]
}

Section sources

• server/server/routes/advanced.py
• server/server/routes/advanced.py

Advanced WebAuthn Features

Custom Algorithm Selection

The advanced endpoints support comprehensive algorithm selection with automatic coercion and validation:

flowchart TD
Start([Algorithm Input]) --> Coerce["Coerce to Integer"]
Coerce --> ParseString["Parse String Values"]
ParseString --> Lookup["Lookup Named Algorithms"]
Lookup --> Validate["Validate Algorithm"]
Validate --> Supported{"Supported?"}
Supported --> |Yes| Use["Use Algorithm"]
Supported --> |No| Custom{"Custom Algorithm?"}
Custom --> |Yes| Warn["Log Warning"]
Custom --> |No| Reject["Reject"]
Warn --> Use
Use --> End([Algorithm Ready])
Reject --> End

Loading

Diagram sources

• server/server/routes/advanced.py

The platform supports both standard and post-quantum cryptographic algorithms:

Algorithm Category	Examples	Status
Standard ECDSA	ES256 (-7), ES384 (-35), ES512 (-36)	Full Support
Standard RSA	RS256 (-257), RS384 (-258), RS512 (-259)	Full Support
Post-Quantum	ML-DSA-87 (-50), ML-DSA-65 (-49), ML-DSA-44 (-48)	Conditional Support
EdDSA Variants	EdDSA (-8), Ed25519 (-19), Ed448 (-53)	Full Support

Authenticator Attachment Preferences

The system supports flexible attachment preference handling:

• Platform Authenticators: Built-in devices (touch ID, face ID, Windows Hello)
• Cross-Platform Authenticators: External devices (USB, NFC, BLE)
• Hint-Based Selection: Dynamic attachment resolution based on hints

Resident Key Requirements

Advanced resident key handling with multiple configuration options:

• Required: Authenticator must support resident keys
• Preferred: Prefer resident keys when available
• Discouraged: Avoid resident keys if possible
• Legacy Support: Backward compatibility with older configurations

Section sources

• server/server/routes/advanced.py
• server/server/routes/advanced.py

Algorithm Processing

Algorithm Coercion and Validation

The platform implements robust algorithm processing with multiple input formats:

classDiagram
class AlgorithmProcessor {
+coerce_cose_algorithm(value) int
+lookup_named_cose_algorithm(name) int
+normalize_algorithm_name_key(name) string
+is_custom_cose_algorithm(alg_id) bool
+describe_algorithm(alg_id) string
}
class AlgorithmValidation {
+validate_algorithm_support(alg_id) bool
+check_pqc_availability(alg_id) bool
+fallback_to_classical(alg_id) int
}
class AlgorithmLogging {
+log_algorithm_selection(stage, alg_id) void
+describe_algorithm(alg_id) string
}
AlgorithmProcessor --> AlgorithmValidation : "validates"
AlgorithmProcessor --> AlgorithmLogging : "logs"

Loading

Diagram sources

• server/server/routes/advanced.py
• server/server/pqc.py

Post-Quantum Cryptography Support

The platform includes comprehensive post-quantum cryptography support:

• ML-DSA Algorithms: ML-DSA-87, ML-DSA-65, ML-DSA-44
• Falcon Signature: Falcon post-quantum signature scheme
• Kyber KEM: Kyber key encapsulation mechanism
• Sphincs+: Stateless hash-based signature scheme

Section sources

• server/server/routes/advanced.py
• server/server/pqc.py

Credential Parsing

Multi-Format Support

The system supports multiple credential input formats:

flowchart TD
Input[Credential Input] --> TypeCheck{Input Type?}
TypeCheck --> |Object| Extract["Extract Properties"]
TypeCheck --> |String| Decode["Decode String"]
TypeCheck --> |Array| Parse["Parse Array"]
Extract --> Binary["Binary Extraction"]
Decode --> Base64["Base64 Decoding"]
Decode --> Hex["Hex Decoding"]
Binary --> Validate["Validate Format"]
Base64 --> Validate
Hex --> Validate
Validate --> Success["Valid Credential"]
Validate --> Error["Parsing Error"]

Loading

Diagram sources

• server/server/routes/advanced.py
• server/server/routes/advanced.py

Supported Formats

Format	Example	Description
Base64 URL	eyJraWQiOiJ...	Standard URL-safe base64 encoding
Base64	eyJraWQiOiJ...	Standard base64 encoding with padding
Hex	0123456789abcdef	Hexadecimal representation
Object with $base64url	{"$base64url": "..."}	Explicit format specification
Object with $base64	{"$base64": "..."}	Explicit base64 format
Object with $hex	{"$hex": "..."}	Explicit hex format

Section sources

• server/server/routes/advanced.py
• server/server/routes/advanced.py

Extension Parameters

Available Extensions

The advanced endpoints support comprehensive WebAuthn extensions:

Extension	Purpose	Configuration
credProps	Credential properties	Boolean enable/disable
minPinLength	Minimum PIN length	Boolean enable/disable
credProtect	Credential protection policy	Policy level (1-3)
largeBlob	Large blob storage	Read/write configuration
prf	Private key reduction	Evaluation parameters

Extension Processing

sequenceDiagram
participant Client as "Client Request"
participant Server as "Extension Processor"
participant Authenticator as "Authenticator"
Client->>Server : Request with Extensions
Server->>Server : Process Extension Config
Server->>Authenticator : Send Extension Data
Authenticator-->>Server : Extension Results
Server->>Server : Validate Results
Server-->>Client : Final Response

Loading

Diagram sources

• server/server/routes/advanced.py
• server/server/routes/advanced.py

Section sources

• server/server/routes/advanced.py
• server/server/routes/advanced.py

Security Considerations

Input Validation

The platform implements comprehensive input validation:

1. Algorithm Validation: Ensures algorithms are supported and valid
2. Binary Format Validation: Validates encoding formats (base64, hex)
3. Parameter Sanitization: Sanitizes user-provided parameters
4. Session State Protection: Validates session state integrity

Custom Algorithm Handling

When dealing with custom COSE algorithms:

• Warning Logging: Logs when custom algorithms are encountered
• Fallback Mechanism: Falls back to classical algorithms when needed
• Signature Verification: May bypass signature verification for custom algorithms
• Audit Trail: Maintains audit trail for security monitoring

Attestation Security

Advanced attestation processing includes:

• Root Certificate Validation: Validates attestation chain
• AAGUID Matching: Verifies authenticator identification
• RP ID Hash Validation: Ensures proper relying party binding
• Metadata Verification: Uses FIDO Metadata Service for authenticator validation

Section sources

• server/server/routes/advanced.py
• server/server/routes/advanced.py

Examples

Basic Registration with Custom Algorithm

{
  "publicKey": {
    "rp": {
      "id": "example.com",
      "name": "Example Application"
    },
    "user": {
      "id": "user123",
      "name": "alice@example.com",
      "displayName": "Alice Johnson"
    },
    "challenge": "dGhlIHNhbXBsZSBjb250ZXh0",
    "pubKeyCredParams": [
      {
        "type": "public-key",
        "alg": "-50"  // ML-DSA-87
      }
    ],
    "authenticatorSelection": {
      "authenticatorAttachment": "platform",
      "userVerification": "required",
      "residentKey": "preferred"
    },
    "attestation": "direct",
    "extensions": {
      "credProps": true,
      "largeBlob": {
        "write": "blob-data-hex"
      }
    }
  }
}

Advanced Authentication with Credential Selection

{
  "publicKey": {
    "challenge": "dGhlIHNhbXBsZSBjb250ZXh0",
    "allowCredentials": [
      {
        "type": "public-key",
        "id": "specific-credential-id"
      }
    ],
    "userVerification": "preferred",
    "extensions": {
      "largeBlob": {
        "read": true
      }
    },
    "hints": ["platform", "cross-platform"]
  },
  "storedCredentials": [
    {
      "credentialId": "credential123",
      "publicKey": "base64-public-key",
      "resident": true,
      "authenticatorAttachment": "platform"
    }
  ]
}

JSON Editor Integration

The platform includes a JSON editor for advanced configuration:

// Example JSON editor configuration
const editorConfig = {
  registration: {
    rp: { id: "example.com", name: "Example App" },
    user: { id: "user123", name: "alice", displayName: "Alice" },
    challenge: "base64-challenge",
    pubKeyCredParams: [{ type: "public-key", alg: -50 }],
    authenticatorSelection: {
      authenticatorAttachment: "platform",
      userVerification: "required"
    }
  }
};

Section sources

• server/server/static/scripts/advanced/json-editor.js

Error Handling

Common Error Responses

Error Code	Message	Cause
400	"Invalid request: Missing publicKey"	Missing required publicKey field
400	"Credential response is required"	Missing credential response
400	"Authentication state not found"	Expired session state
404	"No credentials detected"	No stored credentials available
400	"Invalid challenge format"	Malformed challenge parameter

Error Recovery Strategies

1. Session State Recovery: Attempts to recover from expired states
2. Algorithm Fallback: Falls back to supported algorithms when custom ones fail
3. Credential Refresh: Provides guidance for credential refresh when needed
4. Validation Feedback: Detailed error messages for debugging

Debug Information

The platform provides comprehensive debug information:

{
  "debugInfo": {
    "algorithmsUsed": [-50, -49],
    "attestationFormat": "packed",
    "hintsUsed": ["platform"],
    "algorithm": -50,
    "algorithmDescription": "ML-DSA-87 (PQC)",
    "customAlgorithmBypass": false
  }
}

Section sources

• server/server/routes/advanced.py
• server/server/routes/advanced.py