iOS Sample Applications

Following is a complete iOS sample applications demonstrating both client-direct and backend-proxied FIDO2 authentication patterns. These examples are useful for developers building iOS applications that integrate with the Arculus FIDO2 Server.

Minimal Examples

These minimal examples show the essential code to register and authenticate a user without any UI scaffolding or error handling.

Minimal Client-Direct Example

import ArculusFidoSDKFramework

let arculusFido = ArculusFido()

// Registration
func register() async {
    let fidoServer = ArculusFidoServer(domain: "fido.example.com")
    fidoServer.registrationBeginEndpoint = "fidoapi/certify/attestation/options"
    fidoServer.registrationCompleteEndpoint = "fidoapi/certify/attestation/result"
    
    let result = await arculusFido.registerUser(
        fidoServer: fidoServer,
        pin: "123456",
        username: "[email protected]",
        displayName: "My Device",
        relyingParty: "example.com"
    )
    print("Registration: \(result)")
}

// Authentication
func authenticate() async {
    let fidoServer = ArculusFidoServer(domain: "fido.example.com")
    fidoServer.authorizationBeginEndpoint = "fidoapi/certify/assertion/options"
    fidoServer.authorizationCompleteEndpoint = "fidoapi/certify/assertion/result"
    
    let result = await arculusFido.authenticateUser(
        fidoServer: fidoServer,
        pin: "123456",
        username: "[email protected]",
        displayName: "My Device",
        relyingParty: "example.com"
    )
    print("Authentication: \(result)")
}

Minimal Backend-Proxied Example

import ArculusFidoSDKFramework

let arculusFido = ArculusFido()

// Registration (3-phase flow)
func register() async throws {
    // Phase 1: Get challenge from backend
    let beginResponse = try await backendClient.registerBegin(
        username: "[email protected]",
        displayName: "My Device",
        rpId: "example.com"
    )
    let challenge = beginResponse["challenge"] as! String
    let rpId = beginResponse["rpId"] as! String
    
    // Phase 2: Card operations only
    let cardResponse = try await arculusFido.registerCardOnly(
        pin: "123456",
        username: "[email protected]",
        displayName: "My Device",
        rpId: rpId,
        challenge: challenge,
        origin: "https://example.com"
    )
    
    // Phase 3: Complete with backend
    let completeResponse = try await backendClient.registerComplete(
        username: "[email protected]",
        cardResponseData: try JSONSerialization.jsonObject(with: cardResponse.data(using: .utf8)!) as! [String: Any]
    )
    print("Registration: \(completeResponse)")
}

// Authentication (3-phase flow)
func authenticate() async throws {
    // Phase 1: Get challenge from backend
    let beginResponse = try await backendClient.authenticateBegin(
        username: "[email protected]",
        rpId: "example.com"
    )
    let optionsResponse = createOptionsResponseFromBackend(beginResponse)
    
    // Phase 2: Card operations only
    let cardResponse = try await arculusFido.authenticateCardOnly(
        pin: "123456",
        username: "[email protected]",
        rpId: "example.com",
        optionsResponse: optionsResponse
    )
    
    // Phase 3: Complete with backend
    let completeResponse = try await backendClient.authenticateComplete(
        username: "[email protected]",
        cardResponseData: try JSONSerialization.jsonObject(with: cardResponse.data(using: .utf8)!) as! [String: Any]
    )
    print("Authentication: \(completeResponse)")
}

Complete Sample Applications

The following sections provide complete, production-ready sample applications with full error handling, UI components, and backend integration.

Client-Direct Pattern

A simple WebView-based sample app demonstrating direct FIDO2 server communication:

import UIKit
import WebKit
import ArculusFidoSDKFramework

class ViewController: UIViewController, WKNavigationDelegate, WKScriptMessageHandler, WKUIDelegate {
    var webView: WKWebView!
    private var arculusFido: ArculusFido = ArculusFido()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupWebView()
    }
    
    func setupWebView() {
        let userContentController = WKUserContentController()
        userContentController.add(self, name: "SetPin")
        userContentController.add(self, name: "ChangePin")
        userContentController.add(self, name: "Register")
        userContentController.add(self, name: "Authenticate")
        
        let configuration = WKWebViewConfiguration()
        configuration.userContentController = userContentController
        
        webView = WKWebView(frame: view.bounds, configuration: configuration)
        webView.navigationDelegate = self
        webView.uiDelegate = self
        view.addSubview(webView)
        
        // Load your HTML interface
        if let htmlPath = Bundle.main.path(forResource: "main", ofType: "html") {
            let url = URL(fileURLWithPath: htmlPath)
            webView.load(URLRequest(url: url))
        }
    }
    
    func userContentController(_ userContentController: WKUserContentController, 
                               didReceive message: WKScriptMessage) {
        let messageBody = message.body as! [Any]
        
        switch message.name {
        case "Register":
            handleRegister(messageBody)
        case "Authenticate":
            handleAuthenticate(messageBody)
        case "SetPin":
            handleSetPin(messageBody)
        case "ChangePin":
            handleChangePin(messageBody)
        default:
            break
        }
    }
    
    func handleRegister(_ params: [Any]) {
        let pin = params[0] as! String
        let fido = params[1] as! String
        let user = params[2] as! String
        let deviceinfo = params[3] as! String
        let rp = params[4] as! String
        let beginEndpoint = params[5] as! String
        let completeEndpoint = params[6] as! String
        
        Task {
            let fidoServer = ArculusFidoServer(domain: fido)
            fidoServer.registrationBeginEndpoint = beginEndpoint
            fidoServer.registrationCompleteEndpoint = completeEndpoint
            
            let result = await arculusFido.registerUser(
                fidoServer: fidoServer,
                pin: pin,
                username: user,
                displayName: "iOS Device",
                relyingParty: rp,
                resetDevice: false,
                registrationInfo: deviceinfo
            )
            showAlert(message: result)
        }
    }
    
    func handleAuthenticate(_ params: [Any]) {
        let pin = params[0] as! String
        let fido = params[1] as! String
        let user = params[2] as! String
        let displayName = params[3] as! String
        let rp = params[4] as! String
        let beginEndpoint = params[5] as! String
        let completeEndpoint = params[6] as! String
        
        Task {
            let fidoServer = ArculusFidoServer(domain: fido)
            fidoServer.authorizationBeginEndpoint = beginEndpoint
            fidoServer.authorizationCompleteEndpoint = completeEndpoint
            
            let result = await arculusFido.authenticateUser(
                fidoServer: fidoServer,
                pin: pin,
                username: user,
                displayName: displayName,
                relyingParty: rp
            )
            showAlert(message: result)
        }
    }
    
    func handleSetPin(_ params: [Any]) {
        let pin = params[0] as! String
        Task {
            let result = await arculusFido.setPin(pin: pin)
            showAlert(message: result)
        }
    }
    
    func handleChangePin(_ params: [Any]) {
        let oldPin = params[0] as! String
        let newPin = params[1] as! String
        Task {
            let result = await arculusFido.changePin(oldPin: oldPin, newPin: newPin)
            showAlert(message: result)
        }
    }
    
    func showAlert(message: String) {
        let alert = UIAlertController(title: "Result", message: message, preferredStyle: .alert)
        alert.addAction(UIAlertAction(title: "OK", style: .default))
        present(alert, animated: true)
    }
}

Backend-Proxied Pattern (Recommended)

A complete sample app demonstrating the backend-proxied pattern with 3-phase authentication and registration flows. This pattern is recommended for production deployments as it provides enhanced security by isolating the FIDO2 server from client applications.

Backend API Client

import Foundation

class BackendApiClient {
    private let baseUrl: String
    private var sessionCookies: String?
    
    init(baseUrl: String) {
        self.baseUrl = baseUrl
    }
    
    func clearSessionCookies() {
        sessionCookies = nil
    }
    
    func authenticateBegin(username: String, rpId: String) async throws -> [String: Any] {
        let url = URL(string: "\(baseUrl)/fido/authenticate")!
        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        
        let body: [String: Any] = [
            "operation": "authenticate",
            "username": username,
            "rpId": rpId
        ]
        request.httpBody = try JSONSerialization.data(withJSONObject: body)
        
        let (data, _) = try await URLSession.shared.data(for: request)
        
        guard let json = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
            throw NSError(domain: "BackendApiClient", code: -1, userInfo: [NSLocalizedDescriptionKey: "Invalid response"])
        }
        
        // Extract cookies from JSON response body
        extractAndStoreCookies(from: json)
        
        return json
    }
    
    func authenticateComplete(
        cardResponseData: [String: Any],
        sessionId: String?,
        username: String
    ) async throws -> [String: Any] {
        let url = URL(string: "\(baseUrl)/fido/authenticate")!
        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        
        var body: [String: Any] = [
            "operation": "authenticate",
            "username": username,
            "cardResponseData": cardResponseData
        ]
        
        if let sessionId = sessionId {
            body["sessionId"] = sessionId
        }
        
        if let cookies = sessionCookies {
            body["cookies"] = cookies
            request.setValue(cookies, forHTTPHeaderField: "Cookie")
        }
        
        request.httpBody = try JSONSerialization.data(withJSONObject: body)
        
        let (data, _) = try await URLSession.shared.data(for: request)
        
        guard let json = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
            throw NSError(domain: "BackendApiClient", code: -1, userInfo: [NSLocalizedDescriptionKey: "Invalid response"])
        }
        
        return json
    }
    
    func registerBegin(username: String, displayName: String, rpId: String) async throws -> [String: Any] {
        let url = URL(string: "\(baseUrl)/fido/register")!
        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        
        let body: [String: Any] = [
            "operation": "register",
            "username": username,
            "displayName": displayName,
            "rpId": rpId
        ]
        request.httpBody = try JSONSerialization.data(withJSONObject: body)
        
        let (data, _) = try await URLSession.shared.data(for: request)
        
        guard let json = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
            throw NSError(domain: "BackendApiClient", code: -1, userInfo: [NSLocalizedDescriptionKey: "Invalid response"])
        }
        
        // Extract cookies from JSON response body
        extractAndStoreCookies(from: json)
        
        return json
    }
    
    func registerComplete(
        username: String,
        cardResponseData: [String: Any]
    ) async throws -> [String: Any] {
        let url = URL(string: "\(baseUrl)/fido/register")!
        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        
        var body: [String: Any] = [
            "operation": "register",
            "username": username,
            "cardResponseData": cardResponseData
        ]
        
        if let cookies = sessionCookies {
            body["cookies"] = cookies
            request.setValue(cookies, forHTTPHeaderField: "Cookie")
        }
        
        request.httpBody = try JSONSerialization.data(withJSONObject: body)
        
        let (data, _) = try await URLSession.shared.data(for: request)
        
        guard let json = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
            throw NSError(domain: "BackendApiClient", code: -1, userInfo: [NSLocalizedDescriptionKey: "Invalid response"])
        }
        
        return json
    }
    
    private func extractAndStoreCookies(from response: [String: Any]) {
        if let cookies = response["cookies"] as? String, !cookies.isEmpty {
            sessionCookies = cookies
        }
    }
}

Complete Backend-Proxied Sample App

import UIKit
import WebKit
import ArculusFidoSDKFramework
import CommonCrypto

class ViewController: UIViewController, WKNavigationDelegate, WKScriptMessageHandler {
    var webView: WKWebView!
    private var arculusFido: ArculusFido = ArculusFido()
    private var backendClient: BackendApiClient!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Initialize backend client
        backendClient = BackendApiClient(baseUrl: "https://your-backend.com")
        
        setupWebView()
    }
    
    func setupWebView() {
        let userContentController = WKUserContentController()
        userContentController.add(self, name: "Register")
        userContentController.add(self, name: "Authenticate")
        
        let configuration = WKWebViewConfiguration()
        configuration.userContentController = userContentController
        
        webView = WKWebView(frame: view.bounds, configuration: configuration)
        webView.navigationDelegate = self
        view.addSubview(webView)
        
        if let htmlPath = Bundle.main.path(forResource: "main", ofType: "html") {
            let url = URL(fileURLWithPath: htmlPath)
            webView.load(URLRequest(url: url))
        }
    }
    
    func userContentController(_ userContentController: WKUserContentController, 
                               didReceive message: WKScriptMessage) {
        let messageBody = message.body as! [Any]
        
        switch message.name {
        case "Register":
            handleRegisterBackendProxied(messageBody)
        case "Authenticate":
            handleAuthenticateBackendProxied(messageBody)
        default:
            break
        }
    }
    
    // Backend-Proxied Registration
    func handleRegisterBackendProxied(_ params: [Any]) {
        let pin = params[0] as! String
        let username = params[1] as! String
        let displayName = params[2] as! String
        let rpId = params[3] as! String
        
        Task {
            do {
                // Phase 1: Backend gets challenge
                // Note: If displayName is empty, it will default to username
                let backendResponse = try await backendClient.registerBegin(
                    username: username,
                    displayName: displayName.isEmpty ? username : displayName,
                    rpId: rpId
                )
                
                guard backendResponse["status"] as? String == "success",
                      let fidoServerResponse = backendResponse["fidoServerResponse"] as? [String: Any],
                      let challenge = fidoServerResponse["challenge"] as? String else {
                    // Error messages may be in "message" or "errorMessage" field
                    let errorMsg = (backendResponse["message"] as? String) ?? 
                        (backendResponse["errorMessage"] as? String) ?? "Backend registration begin failed"
                    showAlert(message: errorMsg)
                    return
                }
                
                // Extract rpId from server response if available (CRITICAL: must match what server expects)
                var rpIdFromServer = rpId // Fallback to provided value
                if let rpObject = fidoServerResponse["rp"] as? [String: Any],
                   let rpIdFromRp = rpObject["id"] as? String {
                    rpIdFromServer = rpIdFromRp
                }
                
                // Extract fido2ServerOrigin (required for clientDataJSON)
                guard let origin = backendResponse["fido2ServerOrigin"] as? String else {
                    showAlert(message: "Backend response missing fido2ServerOrigin")
                    return
                }
                
                // Note: Session cookies are automatically stored by backendClient.registerBegin()
                
                // Phase 2: Card operations only
                // registerCardOnly() takes challenge and origin directly (not optionsResponse)
                let cardResponseJson = try await arculusFido.registerCardOnly(
                    pin: pin,
                    username: username,
                    displayName: displayName.isEmpty ? username : displayName,
                    rpId: rpIdFromServer,  // Use rpId from server response
                    challenge: challenge,   // Base64-encoded challenge from backend
                    origin: origin  // Origin URL for clientDataJSON
                )
                
                guard !cardResponseJson.isEmpty,
                      let responseData = cardResponseJson.data(using: .utf8),
                      let cardResponseData = try? JSONSerialization.jsonObject(with: responseData) as? [String: Any] else {
                    showAlert(message: "Card registration returned null or empty response")
                    return
                }
                
                // Extract credential ID for potential rollback
                var credentialId: String? = nil
                if let id = cardResponseData["id"] as? String {
                    credentialId = id
                }
                
                // Phase 3: Backend completes registration
                // Note: Session cookies are automatically included from Phase 1
                let completeResponse = try await backendClient.registerComplete(
                    username: username,
                    cardResponseData: cardResponseData
                )
                
                if completeResponse["status"] as? String == "success" {
                    showAlert(message: "Registration successful!")
                } else {
                    // Registration failed - rollback: delete credential from card
                    // Error messages may be in "message" or "errorMessage" field
                    var errorMsg = (completeResponse["message"] as? String) ?? 
                        (completeResponse["errorMessage"] as? String) ?? "Registration failed"
                    
                    // Perform rollback if credential was created
                    if let credId = credentialId {
                        do {
                            try await arculusFido.deleteCredentialByCredentialId(pin: pin, credentialId: credId)
                        } catch {
                            errorMsg += " (Warning: Credential may still exist on card - rollback failed)"
                        }
                    }
                    
                    showAlert(message: errorMsg)
                }
            } catch {
                let errorMsg: String
                if let urlError = error as? URLError {
                    errorMsg = "Registration failed: Network error - \(urlError.localizedDescription)"
                } else {
                    errorMsg = "Error: \(error.localizedDescription)"
                }
                showAlert(message: errorMsg)
            }
        }
    }
    
    // Backend-Proxied Authentication
    func handleAuthenticateBackendProxied(_ params: [Any]) {
        let pin = params[0] as! String
        let username = params[1] as! String
        let rpId = params[2] as! String
        
        Task {
            do {
                // Phase 1: Backend gets challenge
                let backendResponse = try await backendClient.authenticateBegin(
                    username: username,
                    rpId: rpId
                )
                
                guard backendResponse["status"] as? String == "success",
                      let fidoServerResponse = backendResponse["fidoServerResponse"] as? [String: Any],
                      let challenge = fidoServerResponse["challenge"] as? String else {
                    // Error messages may be in "message" or "errorMessage" field
                    let errorMsg = (backendResponse["message"] as? String) ?? 
                        (backendResponse["errorMessage"] as? String) ?? "Backend authentication begin failed"
                    showAlert(message: errorMsg)
                    return
                }
                
                // Extract rpId from server response if available (CRITICAL: must match what server expects)
                var rpIdFromServer = rpId // Fallback to provided value
                if let rpIdFromResponse = fidoServerResponse["rpId"] as? String {
                    rpIdFromServer = rpIdFromResponse
                }
                
                // Extract fido2ServerOrigin (required for clientDataJSON)
                guard let origin = backendResponse["fido2ServerOrigin"] as? String else {
                    showAlert(message: "Backend response missing fido2ServerOrigin")
                    return
                }
                
                let sessionId = backendResponse["sessionId"] as? String
                // Note: Session cookies are automatically stored by backendClient.authenticateBegin()
                
                // Phase 2: Card operations only
                let optionsResponse = try createOptionsResponseFromBackend(
                    fidoServerResponse: fidoServerResponse,
                    challenge: challenge,
                    rpId: rpIdFromServer,  // Use rpId from server response
                    fido2ServerOrigin: origin
                )
                
                let cardResponseJson = try await arculusFido.authenticateCardOnly(
                    pin: pin,
                    username: username,
                    rpId: rpIdFromServer,  // Use rpId from server response
                    optionsResponse: optionsResponse
                )
                
                guard !cardResponseJson.isEmpty,
                      let responseData = cardResponseJson.data(using: .utf8),
                      let cardResponseData = try? JSONSerialization.jsonObject(with: responseData) as? [String: Any] else {
                    showAlert(message: "Card authentication returned null or empty response")
                    return
                }
                
                // Phase 3: Backend completes authentication
                // Note: Session cookies are automatically included from Phase 1
                let completeResponse = try await backendClient.authenticateComplete(
                    cardResponseData: cardResponseData,
                    sessionId: sessionId,
                    username: username
                )
                
                if completeResponse["status"] as? String == "success" {
                    showAlert(message: "Authentication successful!")
                } else {
                    // Error messages may be in "message" or "errorMessage" field
                    let errorMsg = (completeResponse["message"] as? String) ?? 
                        (completeResponse["errorMessage"] as? String) ?? "Authentication failed"
                    showAlert(message: errorMsg)
                }
            } catch {
                let errorMsg: String
                if let urlError = error as? URLError {
                    errorMsg = "Authentication failed: Network error - \(urlError.localizedDescription)"
                } else {
                    errorMsg = "Error: \(error.localizedDescription)"
                }
                showAlert(message: errorMsg)
            }
        }
    }
    
    func showAlert(message: String) {
        DispatchQueue.main.async {
            let alert = UIAlertController(title: "Result", message: message, preferredStyle: .alert)
            alert.addAction(UIAlertAction(title: "OK", style: .default))
            self.present(alert, animated: true)
        }
    }
    
    // Helper function to create options response from backend response
    func createOptionsResponseFromBackend(
        fidoServerResponse: [String: Any],
        challenge: String,
        rpId: String,
        fido2ServerOrigin: String
    ) throws -> ArculusFidoOptionsAuthorizationResponse {
        let optionsResponse = ArculusFidoOptionsAuthorizationResponse()
        
        // Set challenge and RP ID
        optionsResponse.challenge = challenge
        optionsResponse.rpId = rpId
        
        // Extract allowCredentials if present
        if let allowCredentials = fidoServerResponse["allowCredentials"] as? [[String: Any]] {
            // Convert to allowList format (implementation depends on SDK)
            // This is a simplified example - actual implementation may vary
            optionsResponse.allowList = [] // Set based on SDK requirements
        }
        
        // Construct clientDataJSON
        let clientData: [String: Any] = [
            "type": "webauthn.get",
            "challenge": challenge,
            "origin": fido2ServerOrigin
        ]
        
        let clientDataJSON = try JSONSerialization.data(withJSONObject: clientData)
        let clientDataBase64 = clientDataJSON.base64EncodedString()
            .replacingOccurrences(of: "+", with: "-")
            .replacingOccurrences(of: "/", with: "_")
            .replacingOccurrences(of: "=", with: "")
        
        optionsResponse.clientDataJSONbase64 = clientDataBase64
        
        // Calculate clienthash (SHA-256 of clientDataJSON string)
        let clientDataString = String(data: clientDataJSON, encoding: .utf8)!
        let clientDataBytes = clientDataString.data(using: .utf8)!
        var hash = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
        clientDataBytes.withUnsafeBytes { bytes in
            _ = CC_SHA256(bytes.baseAddress, CC_LONG(clientDataBytes.count), &hash)
        }
        optionsResponse.clienthash = Data(hash)
        
        // Calculate RPIDhash (SHA-256 of rpId)
        let rpIdBytes = rpId.data(using: .utf8)!
        var rpIdHash = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
        rpIdBytes.withUnsafeBytes { bytes in
            _ = CC_SHA256(bytes.baseAddress, CC_LONG(rpIdBytes.count), &rpIdHash)
        }
        optionsResponse.rpIdHash = Data(rpIdHash)
        
        return optionsResponse
    }
}

Note: The createOptionsResponseFromBackend() helper function constructs an ArculusFidoOptionsAuthorizationResponse from the backend response. The exact implementation may vary based on your SDK version. Refer to your SDK documentation for the specific API methods available.

Backend Implementation (Java Servlet)

The backend service receives requests from the iOS app and proxies them to the FIDO2 Server. Here's a complete Java servlet implementation:

import java.io.BufferedReader;
import java.io.IOException;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.google.gson.Gson;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import co.arculus.fido.ArculusFidoServer;
import co.arculus.fido.ArculusFidoServerResponse;
import co.arculus.fido.ArculusFidoException;

public class FidoServlet extends HttpServlet {
    private static final String FIDO2_SERVER_URL = "https://fido.example.com";
    private static final int HTTP_TIMEOUT = 30000; // 30 seconds
    
    private ArculusFidoServer fidoServer;
    private final Gson gson;
    
    @Override
    public void init() throws ServletException {
        super.init();
        this.gson = new Gson();
        initializeFidoServer();
    }
    
    private void initializeFidoServer() {
        try {
            this.fidoServer = new ArculusFidoServer(FIDO2_SERVER_URL);
            this.fidoServer.setBeginAuthenticatePath("/fidoapi/authenticate/begin", null);
            this.fidoServer.setCompleteAuthenticatePath("/fidoapi/authenticate/complete", null);
            this.fidoServer.setBeginRegistrationPath("/fidoapi/register/begin", null);
            this.fidoServer.setCompleteRegistrationPath("/fidoapi/register/complete", null);
            this.fidoServer.setHttpTimeout(HTTP_TIMEOUT);
        } catch (Exception e) {
            throw new ServletException("Failed to initialize FIDO2 server SDK", e);
        }
    }
    
    @Override
    protected void doPost(HttpServletRequest request, HttpServletResponse response) 
            throws ServletException, IOException {
        response.setContentType("application/json; charset=utf-8");
        
        // Read request body
        BufferedReader reader = request.getReader();
        StringBuilder requestBody = new StringBuilder();
        String line;
        while ((line = reader.readLine()) != null) {
            requestBody.append(line);
        }
        
        JsonObject requestJson = JsonParser.parseString(requestBody.toString()).getAsJsonObject();
        String operation = requestJson.has("operation") ? 
            requestJson.get("operation").getAsString() : null;
        
        if (operation == null) {
            sendErrorResponse(response, "Missing operation parameter", 400);
            return;
        }
        
        switch (operation.toLowerCase()) {
            case "register":
                handleRegister(requestJson, response);
                break;
            case "authenticate":
                handleAuthenticate(requestJson, response);
                break;
            default:
                sendErrorResponse(response, "Unknown operation: " + operation, 400);
                break;
        }
    }
    
    private void handleRegister(JsonObject request, HttpServletResponse response) 
            throws IOException {
        String username = request.get("username").getAsString();
        String displayName = request.has("displayName") ? 
            request.get("displayName").getAsString() : username;
        String rpId = request.has("rpId") ? 
            request.get("rpId").getAsString() : "example.com";
        
        if (!request.has("cardResponseData")) {
            // Phase 1: Registration Begin
            handleRegisterBegin(username, displayName, rpId, response);
        } else {
            // Phase 3: Registration Complete
            JsonObject cardResponseData = request.getAsJsonObject("cardResponseData");
            String cookies = request.has("cookies") ? 
                request.get("cookies").getAsString() : null;
            handleRegisterComplete(username, cardResponseData, cookies, response);
        }
    }
    
    private void handleRegisterBegin(String username, String displayName, String rpId, 
            HttpServletResponse response) throws IOException {
        try {
            if (fidoServer == null) {
                sendErrorResponse(response, "FIDO2 server SDK not initialized", 500);
                return;
            }
            
            // Use Arculus SDK to call FIDO2 server
            ArculusFidoServerResponse fidoResponse = fidoServer.callRegisterBegin(username, displayName, null);
            JsonObject fidoJson = JsonParser.parseString(fidoResponse.getResponseBody()).getAsJsonObject();
            
            if (fidoJson.has("error")) {
                sendErrorResponse(response, "FIDO2 server error: " + 
                    fidoJson.get("error").getAsString(), 500);
                return;
            }
            
            // Extract FIDO2 server origin (protocol + host + port, no path)
            String fido2ServerOrigin = extractFido2ServerOrigin();
            
            // Build response for iOS app
            JsonObject responseJson = new JsonObject();
            responseJson.addProperty("status", "success");
            responseJson.addProperty("operation", "register");
            responseJson.addProperty("rpId", rpId);
            responseJson.addProperty("username", username);
            responseJson.add("fidoServerResponse", fidoJson);
            if (fido2ServerOrigin != null) {
                responseJson.addProperty("fido2ServerOrigin", fido2ServerOrigin);
            }
            
            // Pass cookies for session continuity
            if (fidoResponse.getCookies() != null) {
                responseJson.addProperty("cookies", fidoResponse.getCookies());
            }
            
            response.getWriter().write(gson.toJson(responseJson));
            
        } catch (ArculusFidoException e) {
            sendErrorResponse(response, "Registration begin failed: " + 
                (e.getMessage() != null ? e.getMessage() : "FIDO2 server communication failed"), 500);
        } catch (Exception e) {
            sendErrorResponse(response, "Registration begin failed: " + 
                (e.getMessage() != null ? e.getMessage() : "Unknown error"), 500);
        }
    }
    
    private String extractFido2ServerOrigin() {
        // Extract origin from FIDO2_SERVER_URL (protocol + host + port, no path)
        try {
            java.net.URL url = new java.net.URL(FIDO2_SERVER_URL);
            int port = url.getPort();
            if (port == -1) {
                port = url.getDefaultPort();
            }
            String origin = url.getProtocol() + "://" + url.getHost();
            if (port != -1 && port != url.getDefaultPort()) {
                origin += ":" + port;
            }
            return origin;
        } catch (Exception e) {
            return FIDO2_SERVER_URL;
        }
    }
    
    private void handleRegisterComplete(String username, JsonObject cardResponseData, 
            String cookies, HttpServletResponse response) throws IOException {
        try {
            if (fidoServer == null) {
                sendErrorResponse(response, "FIDO2 server SDK not initialized", 500);
                return;
            }
            
            // Clean cookies before sending to FIDO2 server
            // HttpURLConnection (used by SDK) requires Cookie header to contain only name=value pairs
            String cleanedCookies = cleanCookieString(cookies);
            
            // Construct the full FIDO2 registration complete request
            JsonObject fidoRequest = new JsonObject();
            fidoRequest.addProperty("username", username);
            
            // Add type, id, rawId from cardResponseData
            if (cardResponseData.has("type")) {
                fidoRequest.addProperty("type", cardResponseData.get("type").getAsString());
            } else {
                fidoRequest.addProperty("type", "public-key"); // Default
            }
            
            if (cardResponseData.has("id")) {
                fidoRequest.addProperty("id", cardResponseData.get("id").getAsString());
            }
            
            if (cardResponseData.has("rawId")) {
                fidoRequest.addProperty("rawId", cardResponseData.get("rawId").getAsString());
            } else if (cardResponseData.has("id")) {
                // Use id as rawId if rawId not present
                fidoRequest.addProperty("rawId", cardResponseData.get("id").getAsString());
            }
            
            // Add response object (preserve exact structure from card)
            if (cardResponseData.has("response")) {
                fidoRequest.add("response", cardResponseData.getAsJsonObject("response"));
            } else {
                // Fallback: use entire cardResponseData as response
                fidoRequest.add("response", cardResponseData);
            }
            
            String requestBody = gson.toJson(fidoRequest);
            
            // Use Arculus SDK to call FIDO2 server
            ArculusFidoServerResponse fidoResponse = fidoServer.callRegisterComplete(requestBody, cleanedCookies);
            JsonObject fidoJson = JsonParser.parseString(fidoResponse.getResponseBody()).getAsJsonObject();
            
            if (fidoJson.has("error")) {
                sendErrorResponse(response, "FIDO2 registration failed: " + 
                    fidoJson.get("error").getAsString(), 400);
                return;
            }
            
            JsonObject responseJson = new JsonObject();
            responseJson.addProperty("status", "success");
            responseJson.addProperty("operation", "register");
            responseJson.addProperty("message", "Registration completed successfully");
            response.getWriter().write(gson.toJson(responseJson));
            
        } catch (ArculusFidoException e) {
            sendErrorResponse(response, "Registration complete failed: " + 
                (e.getMessage() != null ? e.getMessage() : "FIDO2 server communication failed"), 500);
        } catch (Exception e) {
            sendErrorResponse(response, "Registration complete failed: " + 
                (e.getMessage() != null ? e.getMessage() : "Unknown error"), 500);
        }
    }
    
    /**
     * Clean cookie string before sending to FIDO2 server.
     * HttpURLConnection (used by SDK) requires Cookie header to contain only name=value pairs.
     * This removes any "Cookie:" prefix and trims whitespace.
     */
    private String cleanCookieString(String cookies) {
        if (cookies == null || cookies.trim().isEmpty()) {
            return null;
        }
        // Remove "Cookie:" prefix if present, and clean up whitespace
        String cleaned = cookies.replaceFirst("(?i)^Cookie:\\s*", "").trim();
        return cleaned.isEmpty() ? null : cleaned;
    }
    
    private void handleAuthenticate(JsonObject request, HttpServletResponse response) 
            throws IOException {
        String username = request.get("username").getAsString();
        String rpId = request.has("rpId") ? 
            request.get("rpId").getAsString() : "example.com";
        
        if (!request.has("cardResponseData")) {
            // Phase 1: Authentication Begin
            handleAuthenticateBegin(username, rpId, response);
        } else {
            // Phase 3: Authentication Complete
            JsonObject cardResponseData = request.getAsJsonObject("cardResponseData");
            String cookies = request.has("cookies") ? 
                request.get("cookies").getAsString() : null;
            handleAuthenticateComplete(username, cardResponseData, cookies, response);
        }
    }
    
    private void handleAuthenticateBegin(String username, String rpId, 
            HttpServletResponse response) throws IOException {
        try {
            if (fidoServer == null) {
                sendErrorResponse(response, "FIDO2 server SDK not initialized", 500);
                return;
            }
            
            // Use Arculus SDK to call FIDO2 server
            ArculusFidoServerResponse fidoResponse = fidoServer.callAuthenticateBegin(username, username, null);
            JsonObject fidoJson = JsonParser.parseString(fidoResponse.getResponseBody()).getAsJsonObject();
            
            if (fidoJson.has("error")) {
                sendErrorResponse(response, "FIDO2 server error: " + 
                    fidoJson.get("error").getAsString(), 500);
                return;
            }
            
            String sessionId = null;
            if (fidoJson.has("allowCredentials")) {
                com.google.gson.JsonArray allowCredentials = fidoJson.getAsJsonArray("allowCredentials");
                if (allowCredentials.size() > 0) {
                    JsonObject credential = allowCredentials.get(0).getAsJsonObject();
                    if (credential.has("id")) {
                        sessionId = credential.get("id").getAsString();
                    }
                }
            }
            
            // Build response for iOS app
            JsonObject responseJson = new JsonObject();
            responseJson.addProperty("status", "success");
            responseJson.addProperty("operation", "authenticate");
            responseJson.addProperty("rpId", rpId);
            responseJson.addProperty("username", username);
            responseJson.add("fidoServerResponse", fidoJson);
            
            if (sessionId != null) {
                responseJson.addProperty("sessionId", sessionId);
            }
            
            // CRITICAL: Pass FIDO2 server URL to mobile app for clientDataJSON origin
            String fido2ServerOrigin = extractFido2ServerOrigin();
            responseJson.addProperty("fido2ServerOrigin", fido2ServerOrigin);
            
            // Pass cookies for session continuity
            if (fidoResponse.getCookies() != null) {
                responseJson.addProperty("cookies", fidoResponse.getCookies());
            }
            
            response.getWriter().write(gson.toJson(responseJson));
            
        } catch (ArculusFidoException e) {
            sendErrorResponse(response, "Authentication begin failed: " + 
                (e.getMessage() != null ? e.getMessage() : "FIDO2 server communication failed"), 500);
        } catch (Exception e) {
            sendErrorResponse(response, "Authentication begin failed: " + 
                (e.getMessage() != null ? e.getMessage() : "Unknown error"), 500);
        }
    }
    
    private void handleAuthenticateComplete(String username, JsonObject cardResponseData, 
            String cookies, HttpServletResponse response) throws IOException {
        try {
            if (fidoServer == null) {
                sendErrorResponse(response, "FIDO2 server SDK not initialized", 500);
                return;
            }
            
            // Clean cookies before sending to FIDO2 server
            String cleanedCookies = cleanCookieString(cookies);
            
            String type = cardResponseData.has("type") ? 
                cardResponseData.get("type").getAsString() : "public-key";
            String id = cardResponseData.has("id") ? 
                cardResponseData.get("id").getAsString() : null;
            
            // Preserve the exact responseData structure as received from the card
            JsonObject responseData = cardResponseData.has("response") ?
                cardResponseData.getAsJsonObject("response") : new JsonObject();
            
            // Prepare authentication completion request to FIDO2 server
            JsonObject fidoRequest = new JsonObject();
            fidoRequest.addProperty("username", username);
            fidoRequest.addProperty("type", type);
            if (id != null) {
                fidoRequest.addProperty("id", id);
            }
            fidoRequest.add("response", responseData);
            
            String requestBody = gson.toJson(fidoRequest);
            
            // Use Arculus SDK to call FIDO2 server
            co.arculus.fido.internal.FidoEndpoint endpoint = fidoServer.getCompleteAuthenticateEndpoint();
            ArculusFidoServerResponse fidoResponse;
            try {
                fidoResponse = fidoServer.makeHttpCall(endpoint, requestBody, cleanedCookies);
            } catch (ArculusFidoException e) {
                int serverResponseCode = e.getUnderlyingServerResponseCode();
                
                if (serverResponseCode == 401) {
                    sendErrorResponse(response, 
                        "FIDO2 server session expired. Please retry authentication from the beginning.", 401);
                    return;
                }
                
                sendErrorResponse(response, "FIDO2 server communication failed (HTTP " + serverResponseCode + "): " + 
                    (e.getMessage() != null ? e.getMessage() : "Unknown error"), 500);
                return;
            }
            
            JsonObject fidoJson = JsonParser.parseString(fidoResponse.getResponseBody()).getAsJsonObject();
            
            if (fidoJson.has("error")) {
                sendErrorResponse(response, "FIDO2 authentication failed: " + 
                    fidoJson.get("error").getAsString(), 400);
                return;
            }
            
            JsonObject responseJson = new JsonObject();
            responseJson.addProperty("status", "success");
            responseJson.addProperty("operation", "authenticate");
            responseJson.addProperty("message", "Authentication completed successfully");
            response.getWriter().write(gson.toJson(responseJson));
            
        } catch (ArculusFidoException e) {
            sendErrorResponse(response, "Authentication complete failed: " + 
                (e.getMessage() != null ? e.getMessage() : "FIDO2 server communication failed"), 500);
        } catch (Exception e) {
            sendErrorResponse(response, "Authentication complete failed: " + 
                (e.getMessage() != null ? e.getMessage() : "Unknown error"), 500);
        }
    }
    
    private void sendErrorResponse(HttpServletResponse response, String message, int statusCode) 
            throws IOException {
        response.setStatus(statusCode);
        JsonObject errorJson = new JsonObject();
        errorJson.addProperty("status", "failed");
        errorJson.addProperty("error", message);
        response.getWriter().write(errorJson.toString());
    }
}

Key Implementation Notes:

1. Operation-Based Routing: The servlet uses the operation field to route requests to registration or authentication handlers.

2. Phase Detection: The presence of cardResponseData determines whether it's a "begin" (Phase 1) or "complete" (Phase 3) request.

3. Session Cookie Management: Cookies from the FIDO2 server are extracted and passed back to the client, then forwarded in subsequent requests.

4. FIDO2 Server Origin: The backend extracts and returns the FIDO2 server origin URL for the client to use in clientDataJSON validation.

5. Error Handling: All errors are caught and returned in a consistent JSON format.

Note: This example uses the Arculus SDK server-side methods (ArculusFidoServer) instead of direct REST API calls. For Python backend developers or advanced debugging, see 5.7 FIDO2 Server REST API Reference in the Appendix.