Python Sample Applications

This document provides complete Python sample applications demonstrating both client-direct and backend-proxied FIDO2 authentication patterns. These examples are useful for developers building Python backends or desktop applications that integrate with the Arculus FIDO2 Server.

Minimal Examples

These minimal examples show the essential REST API calls to register and authenticate a user. Note that Python does not have an SDK, so all operations use direct REST API calls to the FIDO2 server.

Minimal Client-Direct Example

import requests

FIDO_SERVER_URL = "https://fido.example.com"
USERNAME = "[email protected]"
RP_ID = "example.com"

# Registration
def register_user():
    # Phase 1: Get registration options
    begin_response = requests.post(
        f"{FIDO_SERVER_URL}/fidoapi/certify/attestation/options",
        json={"username": USERNAME, "rpId": RP_ID}
    )
    begin_data = begin_response.json()
    challenge = begin_data["challenge"]
    
    # Phase 2: Card operations (performed by mobile app with SDK)
    # Mobile app returns card_response_data after calling registerCardOnly()
    card_response_data = {
        "id": "credential-id",
        "rawId": "base64-raw-id",
        "type": "public-key",
        "response": {
            "authenticatorData": "base64-data",
            "clientDataJSON": "base64-data",
            "signature": "base64-signature"
        }
    }
    
    # Phase 3: Complete registration
    complete_response = requests.post(
        f"{FIDO_SERVER_URL}/fidoapi/certify/attestation/result",
        json=card_response_data,
        cookies=begin_response.cookies
    )
    print("Registration:", complete_response.json())

# Authentication
def authenticate_user():
    # Phase 1: Get authentication options
    begin_response = requests.post(
        f"{FIDO_SERVER_URL}/fidoapi/certify/assertion/options",
        json={"username": USERNAME, "rpId": RP_ID}
    )
    begin_data = begin_response.json()
    
    # Phase 2: Card operations (performed by mobile app with SDK)
    # Mobile app returns card_response_data after calling authenticateCardOnly()
    card_response_data = {
        "id": "credential-id",
        "rawId": "base64-raw-id",
        "type": "public-key",
        "response": {
            "authenticatorData": "base64-data",
            "clientDataJSON": "base64-data",
            "signature": "base64-signature"
        }
    }
    
    # Phase 3: Complete authentication
    complete_response = requests.post(
        f"{FIDO_SERVER_URL}/fidoapi/certify/assertion/result",
        json=card_response_data,
        cookies=begin_response.cookies
    )
    print("Authentication:", complete_response.json())

Minimal Backend-Proxied Example

import requests

BACKEND_URL = "https://backend.example.com"
USERNAME = "[email protected]"
RP_ID = "example.com"

# Registration (backend handles FIDO2 server communication)
def register_user():
    # Phase 1: Backend gets challenge from FIDO2 server
    begin_response = requests.post(
        f"{BACKEND_URL}/fido/register",
        json={
            "operation": "register",
            "username": USERNAME,
            "displayName": "My Device",
            "rpId": RP_ID
        }
    )
    begin_data = begin_response.json()
    challenge = begin_data["challenge"]
    
    # Phase 2: Card operations (performed by mobile app with SDK)
    # Mobile app uses challenge to call registerCardOnly()
    # Mobile app returns card_response_data
    card_response_data = {
        "id": "credential-id",
        "rawId": "base64-raw-id",
        "type": "public-key",
        "response": {
            "authenticatorData": "base64-data",
            "clientDataJSON": "base64-data",
            "signature": "base64-signature"
        }
    }
    
    # Phase 3: Backend completes with FIDO2 server
    complete_response = requests.post(
        f"{BACKEND_URL}/fido/register",
        json={
            "operation": "complete",
            "username": USERNAME,
            "cardResponseData": card_response_data
        },
        cookies=begin_response.cookies
    )
    print("Registration:", complete_response.json())

# Authentication (backend handles FIDO2 server communication)
def authenticate_user():
    # Phase 1: Backend gets challenge from FIDO2 server
    begin_response = requests.post(
        f"{BACKEND_URL}/fido/authenticate",
        json={
            "operation": "authenticate",
            "username": USERNAME,
            "rpId": RP_ID
        }
    )
    begin_data = begin_response.json()
    
    # Phase 2: Card operations (performed by mobile app with SDK)
    # Mobile app uses optionsResponse to call authenticateCardOnly()
    # Mobile app returns card_response_data
    card_response_data = {
        "id": "credential-id",
        "rawId": "base64-raw-id",
        "type": "public-key",
        "response": {
            "authenticatorData": "base64-data",
            "clientDataJSON": "base64-data",
            "signature": "base64-signature"
        }
    }
    
    # Phase 3: Backend completes with FIDO2 server
    complete_response = requests.post(
        f"{BACKEND_URL}/fido/authenticate",
        json={
            "operation": "complete",
            "username": USERNAME,
            "cardResponseData": card_response_data
        },
        cookies=begin_response.cookies
    )
    print("Authentication:", complete_response.json())

Complete Sample Applications

The following sections provide complete, production-ready sample applications with full error handling, session management, and proper integration patterns.

Client-Direct Pattern

In the client-direct pattern, the Python application communicates directly with the FIDO2 server. This pattern is suitable for desktop applications or simple backend services.

Basic Client-Direct Example

import requests
import json

# Configuration
FIDO_SERVER_URL = "https://fido.example.com"
USERNAME = "[email protected]"
PIN = "123456"
RP_ID = "example.com"

# Registration
def register_user():
    # Phase 1: Get registration options
    begin_url = f"{FIDO_SERVER_URL}/fidoapi/register/begin"
    begin_response = requests.post(begin_url, json={
        "username": USERNAME,
        "rpId": RP_ID
    })
    begin_data = begin_response.json()
    challenge = begin_data["challenge"]
    
    # Phase 2: Card operations (must be performed on mobile device with SDK)
    # The mobile app would:
    # - Create options response from challenge
    # - Call registerCardOnly() or register() with the challenge
    # - Return card response data
    
    # For this example, assume card_response_data is received from mobile app
    card_response_data = {
        "id": "credential-id",
        "rawId": "base64-raw-id",
        "type": "public-key",
        "response": {
            "authenticatorData": "base64-data",
            "clientDataJSON": "base64-data",
            "signature": "base64-signature"
        }
    }
    
    # Phase 3: Complete registration
    complete_url = f"{FIDO_SERVER_URL}/fidoapi/register/complete"
    complete_response = requests.post(complete_url, json={
        "username": USERNAME,
        "type": card_response_data["type"],
        "id": card_response_data["id"],
        "response": card_response_data["response"]
    }, cookies=begin_response.cookies)
    
    return complete_response.json()

# Authentication
def authenticate_user():
    # Phase 1: Get authentication options
    begin_url = f"{FIDO_SERVER_URL}/fidoapi/authenticate/begin"
    begin_response = requests.post(begin_url, json={
        "username": USERNAME,
        "rpId": RP_ID
    })
    begin_data = begin_response.json()
    challenge = begin_data["challenge"]
    
    # Phase 2: Card operations (must be performed on mobile device with SDK)
    # The mobile app would:
    # - Create options response from challenge
    # - Call authenticateCardOnly() with the challenge
    # - Return card response data
    
    # For this example, assume card_response_data is received from mobile app
    card_response_data = {
        "id": "credential-id",
        "rawId": "base64-raw-id",
        "type": "public-key",
        "response": {
            "authenticatorData": "base64-data",
            "clientDataJSON": "base64-data",
            "signature": "base64-signature"
        }
    }
    
    # Phase 3: Complete authentication
    complete_url = f"{FIDO_SERVER_URL}/fidoapi/authenticate/complete"
    complete_response = requests.post(complete_url, json={
        "username": USERNAME,
        "type": card_response_data["type"],
        "id": card_response_data["id"],
        "response": card_response_data["response"]
    }, cookies=begin_response.cookies)
    
    return complete_response.json()

Backend-Proxied Pattern (Recommended)

In the backend-proxied pattern, a backend service handles all FIDO2 server communication, and the client (mobile app or desktop app) only performs card operations. This is the recommended pattern for production deployments.

Backend API Client

import requests
import json
from typing import Optional, Dict, Any

class BackendApiClient:
    """Client for communicating with backend services that proxy FIDO2 requests."""
    
    def __init__(self, backend_url: str, verify_ssl: bool = True):
        self.backend_url = backend_url.rstrip('/')
        self.verify_ssl = verify_ssl
        self.session_cookies = None
    
    def clear_session_cookies(self):
        """Clear stored session cookies."""
        self.session_cookies = None
    
    def authenticate_begin(self, username: str, rp_id: str) -> Dict[str, Any]:
        """
        Phase 1: Get challenge from backend.
        
        Args:
            username: User identifier
            rp_id: Relying party ID
            
        Returns:
            Backend response containing challenge, FIDO2 server response, and session info
        """
        url = f"{self.backend_url}/fido/authenticate"
        payload = {
            "operation": "authenticate",
            "username": username,
            "rpId": rp_id
        }
        
        response = requests.post(url, json=payload, verify=self.verify_ssl)
        response.raise_for_status()
        
        # Extract and store cookies
        if 'Set-Cookie' in response.headers:
            self.session_cookies = response.headers['Set-Cookie']
        
        return response.json()
    
    def authenticate_complete(
        self, 
        card_response_data: Dict[str, Any], 
        session_id: Optional[str], 
        username: str
    ) -> Dict[str, Any]:
        """
        Phase 3: Complete authentication with backend.
        
        Args:
            card_response_data: Card response from Phase 2
            session_id: Session ID from Phase 1 (optional)
            username: User identifier
            
        Returns:
            Authentication result
        """
        url = f"{self.backend_url}/fido/authenticate"
        payload = {
            "operation": "authenticate",
            "username": username,
            "cardResponseData": card_response_data
        }
        
        if session_id:
            payload["sessionId"] = session_id
        
        if self.session_cookies:
            payload["cookies"] = self.session_cookies
        
        headers = {"Content-Type": "application/json"}
        if self.session_cookies:
            headers["Cookie"] = self.session_cookies
        
        response = requests.post(
            url, 
            json=payload, 
            headers=headers, 
            verify=self.verify_ssl
        )
        response.raise_for_status()
        
        return response.json()
    
    def register_begin(
        self, 
        username: str, 
        display_name: str, 
        rp_id: str
    ) -> Dict[str, Any]:
        """
        Phase 1: Get registration challenge from backend.
        
        Args:
            username: User identifier
            display_name: Human-readable display name
            rp_id: Relying party ID
            
        Returns:
            Backend response containing challenge, FIDO2 server response, and session info
        """
        url = f"{self.backend_url}/fido/register"
        payload = {
            "operation": "register",
            "username": username,
            "displayName": display_name,
            "rpId": rp_id
        }
        
        response = requests.post(url, json=payload, verify=self.verify_ssl)
        response.raise_for_status()
        
        # Extract and store cookies
        if 'Set-Cookie' in response.headers:
            self.session_cookies = response.headers['Set-Cookie']
        
        return response.json()
    
    def register_complete(
        self, 
        card_response_data: Dict[str, Any], 
        session_id: Optional[str], 
        username: str
    ) -> Dict[str, Any]:
        """
        Phase 3: Complete registration with backend.
        
        Args:
            card_response_data: Card response from Phase 2
            session_id: Session ID from Phase 1 (optional)
            username: User identifier
            
        Returns:
            Registration result
        """
        url = f"{self.backend_url}/fido/register"
        payload = {
            "operation": "register",
            "username": username,
            "cardResponseData": card_response_data
        }
        
        if session_id:
            payload["sessionId"] = session_id
        
        if self.session_cookies:
            payload["cookies"] = self.session_cookies
        
        headers = {"Content-Type": "application/json"}
        if self.session_cookies:
            headers["Cookie"] = self.session_cookies
        
        response = requests.post(
            url, 
            json=payload, 
            headers=headers, 
            verify=self.verify_ssl
        )
        response.raise_for_status()
        
        return response.json()

Complete Backend-Proxied Authentication Example

import requests
import json
from typing import Dict, Any, Optional

class FidoHelper:
    """Helper class for FIDO2 authentication using backend-proxied pattern."""
    
    def __init__(self, backend_url: str, verify_ssl: bool = True):
        self.backend_client = BackendApiClient(backend_url, verify_ssl)
    
    def authenticate(
        self, 
        username: str, 
        pin: str, 
        rp_id: str,
        card_response_provider
    ) -> Dict[str, Any]:
        """
        Complete authentication flow using backend-proxied pattern.
        
        Args:
            username: User identifier
            pin: Card PIN
            rp_id: Relying party ID
            card_response_provider: Function that performs Phase 2 card operations
                                    and returns card response data
                                    Signature: (challenge, fido_server_response, rp_id, fido2_server_origin) -> card_response_data
        
        Returns:
            Authentication result
        """
        # Phase 1: Backend gets challenge
        backend_response = self.backend_client.authenticate_begin(username, rp_id)
        
        if backend_response.get("status") != "success":
            return {
                "status": "failed",
                "errorMessage": backend_response.get("message", "Backend authentication begin failed")
            }
        
        # Extract challenge and FIDO2 server response
        fido_server_response = backend_response.get("fidoServerResponse")
        if not fido_server_response:
            return {
                "status": "failed",
                "errorMessage": "Backend response missing fidoServerResponse"
            }
        
        challenge = fido_server_response.get("challenge")
        if not challenge:
            return {
                "status": "failed",
                "errorMessage": "Backend response missing challenge"
            }
        
        fido2_server_origin = backend_response.get("fido2ServerOrigin")
        if not fido2_server_origin:
            return {
                "status": "failed",
                "errorMessage": "Backend response missing fido2ServerOrigin"
            }
        
        session_id = backend_response.get("sessionId")
        
        # Phase 2: Card operations (performed by mobile app or desktop app with SDK)
        # The card_response_provider function should:
        # 1. Create options response from backend response
        # 2. Call SDK's authenticateCardOnly() method
        # 3. Return card response data
        try:
            card_response_data = card_response_provider(
                challenge, 
                fido_server_response, 
                rp_id, 
                fido2_server_origin
            )
        except Exception as e:
            return {
                "status": "failed",
                "errorMessage": f"Card operation failed: {str(e)}"
            }
        
        # Phase 3: Backend completes authentication
        complete_response = self.backend_client.authenticate_complete(
            card_response_data,
            session_id,
            username
        )
        
        return complete_response
    
    def register(
        self, 
        username: str, 
        pin: str, 
        display_name: str,
        rp_id: str,
        card_response_provider
    ) -> Dict[str, Any]:
        """
        Complete registration flow using backend-proxied pattern.
        
        Args:
            username: User identifier
            pin: Card PIN
            display_name: Human-readable display name
            rp_id: Relying party ID
            card_response_provider: Function that performs Phase 2 card operations
                                    and returns card response data
                                    Signature: (challenge, fido_server_response, rp_id, fido2_server_origin) -> card_response_data
        
        Returns:
            Registration result
        """
        # Phase 1: Backend gets challenge
        backend_response = self.backend_client.register_begin(username, display_name, rp_id)
        
        if backend_response.get("status") != "success":
            return {
                "status": "failed",
                "errorMessage": backend_response.get("message", "Backend registration begin failed")
            }
        
        # Extract challenge and FIDO2 server response
        fido_server_response = backend_response.get("fidoServerResponse")
        if not fido_server_response:
            return {
                "status": "failed",
                "errorMessage": "Backend response missing fidoServerResponse"
            }
        
        challenge = fido_server_response.get("challenge")
        if not challenge:
            return {
                "status": "failed",
                "errorMessage": "Backend response missing challenge"
            }
        
        fido2_server_origin = backend_response.get("fido2ServerOrigin")
        if not fido2_server_origin:
            return {
                "status": "failed",
                "errorMessage": "Backend response missing fido2ServerOrigin"
            }
        
        session_id = backend_response.get("sessionId")
        
        # Phase 2: Card operations (performed by mobile app or desktop app with SDK)
        try:
            card_response_data = card_response_provider(
                challenge, 
                fido_server_response, 
                rp_id, 
                fido2_server_origin
            )
        except Exception as e:
            return {
                "status": "failed",
                "errorMessage": f"Card operation failed: {str(e)}"
            }
        
        # Phase 3: Backend completes registration
        complete_response = self.backend_client.register_complete(
            card_response_data,
            session_id,
            username
        )
        
        return complete_response

# Usage Example
def example_usage():
    """Example of using the FidoHelper class."""
    
    # Initialize helper
    backend_url = "https://localhost:8444/myapp"
    fido_helper = FidoHelper(backend_url, verify_ssl=False)
    
    # Define card response provider (this would typically call mobile SDK)
    def get_card_response(challenge, fido_server_response, rp_id, fido2_server_origin):
        """
        This function would typically:
        1. Create options response from backend response
        2. Call mobile SDK's authenticateCardOnly() method
        3. Return card response data
        
        For this example, we'll return a placeholder structure.
        """
        # In real implementation, this would call:
        # - iOS: arculusFido.authenticateCardOnly(pin, username, rpId, optionsResponse)
        # - Android: arculusFido.authenticateCardOnly(pin, username, rpId, optionsResponse)
        # - Desktop: arculusFido.authenticateCardOnly(pin, username, rpId, optionsResponse)
        
        return {
            "id": "credential-id-from-card",
            "rawId": "base64-raw-id",
            "type": "public-key",
            "response": {
                "authenticatorData": "base64-authenticator-data",
                "clientDataJSON": "base64-client-data",
                "signature": "base64-signature"
            }
        }
    
    # Authenticate user
    username = "[email protected]"
    pin = "123456"
    rp_id = "example.com"
    
    result = fido_helper.authenticate(
        username=username,
        pin=pin,
        rp_id=rp_id,
        card_response_provider=get_card_response
    )
    
    if result.get("status") == "success":
        print("Authentication successful!")
    else:
        print(f"Authentication failed: {result.get('errorMessage')}")

Integration with Mobile Apps

When using the backend-proxied pattern, the Python backend coordinates with mobile applications that perform the card operations:

Backend Flow

1. Phase 1: Backend receives authentication/registration request

2. Phase 2: Backend sends challenge to mobile app (via API, WebSocket, or push notification)

3. Phase 3: Mobile app performs card operations using SDK

4. Phase 4: Mobile app sends card response back to backend

5. Phase 5: Backend completes authentication/registration with FIDO2 server

Example: Flask Backend Endpoint

from flask import Flask, request, jsonify
from FidoHelper import FidoHelper

app = Flask(__name__)
fido_helper = FidoHelper("https://fido.example.com", verify_ssl=True)

@app.route('/api/authenticate/begin', methods=['POST'])
def authenticate_begin():
    """Phase 1: Get challenge from FIDO2 server."""
    data = request.json
    username = data.get('username')
    rp_id = data.get('rpId')
    
    backend_response = fido_helper.backend_client.authenticate_begin(username, rp_id)
    return jsonify(backend_response)

@app.route('/api/authenticate/complete', methods=['POST'])
def authenticate_complete():
    """Phase 3: Complete authentication with FIDO2 server."""
    data = request.json
    username = data.get('username')
    card_response_data = data.get('cardResponseData')
    session_id = data.get('sessionId')
    
    result = fido_helper.backend_client.authenticate_complete(
        card_response_data, 
        session_id, 
        username
    )
    return jsonify(result)

Error Handling

def handle_fido_error(response: Dict[str, Any]) -> str:
    """Extract and format error message from FIDO2 response."""
    if response.get("status") == "failed":
        error_message = response.get("errorMessage", "Unknown error")
        response_code = response.get("responseCode", 0)
        
        # Map common error codes to user-friendly messages
        error_messages = {
            401: "Authentication failed: Invalid credentials",
            403: "User not found. Please register first.",
            408: "Session expired. Please try again.",
            600: "Card communication error: Please hold card steady",
            602: "No credentials found: Please register card first",
            608: "PIN verification failed: Check your PIN",
        }
        
        if response_code in error_messages:
            return error_messages[response_code]
        
        return f"Error {response_code}: {error_message}"
    
    return None

Session Management

class SessionManager:
    """Manages user sessions and authentication state."""
    
    def __init__(self):
        self.sessions = {}
    
    def create_session(self, session_id: str, username: str, expires_at: float):
        """Create a new session."""
        self.sessions[session_id] = {
            "username": username,
            "expires_at": expires_at,
            "authenticated": False
        }
    
    def is_session_valid(self, session_id: str) -> bool:
        """Check if session is valid and not expired."""
        import time
        session = self.sessions.get(session_id)
        if not session:
            return False
        return time.time() < session["expires_at"]
    
    def mark_authenticated(self, session_id: str):
        """Mark session as authenticated."""
        if session_id in self.sessions:
            self.sessions[session_id]["authenticated"] = True
    
    def get_username(self, session_id: str) -> Optional[str]:
        """Get username for session."""
        session = self.sessions.get(session_id)
        return session["username"] if session else None

Complete Example: Flask Application

from flask import Flask, request, jsonify
from FidoHelper import FidoHelper, BackendApiClient
from SessionManager import SessionManager
import time

app = Flask(__name__)
fido_helper = FidoHelper("https://fido.example.com", verify_ssl=True)
session_manager = SessionManager()

@app.route('/api/authenticate/begin', methods=['POST'])
def authenticate_begin():
    """Phase 1: Begin authentication - get challenge from backend."""
    data = request.json
    username = data.get('username')
    rp_id = data.get('rpId')
    
    try:
        backend_response = fido_helper.backend_client.authenticate_begin(username, rp_id)
        
        if backend_response.get("status") == "success":
            # Create session
            session_id = f"session_{int(time.time())}"
            session_manager.create_session(session_id, username, time.time() + 3600)
            backend_response["sessionId"] = session_id
        
        return jsonify(backend_response)
    except Exception as e:
        return jsonify({
            "status": "failed",
            "errorMessage": str(e)
        }), 500

@app.route('/api/authenticate/complete', methods=['POST'])
def authenticate_complete():
    """Phase 3: Complete authentication with card response."""
    data = request.json
    username = data.get('username')
    card_response_data = data.get('cardResponseData')
    session_id = data.get('sessionId')
    
    # Validate session
    if not session_manager.is_session_valid(session_id):
        return jsonify({
            "status": "failed",
            "errorMessage": "Session expired or invalid"
        }), 401
    
    # Verify username matches session
    if session_manager.get_username(session_id) != username:
        return jsonify({
            "status": "failed",
            "errorMessage": "Username mismatch"
        }), 403
    
    try:
        result = fido_helper.backend_client.authenticate_complete(
            card_response_data,
            session_id,
            username
        )
        
        if result.get("status") == "success":
            session_manager.mark_authenticated(session_id)
        
        return jsonify(result)
    except Exception as e:
        return jsonify({
            "status": "failed",
            "errorMessage": str(e)
        }), 500

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000, ssl_context='adhoc')