Desktop Sample Applications

Below are complete Desktop (Java) sample applications demonstrating both client-direct and backend-proxied FIDO2 authentication patterns. These examples are useful for developers building Java desktop applications that integrate with the Arculus FIDO2 Server using PC/SC-compatible NFC readers.

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 co.arculus.fido.ArculusFido;
import co.arculus.fido.ArculusFidoServer;
import co.arculus.pcsc.PCSC;

// Initialize PC/SC reader
String[] readers = PCSC.listPCSCReaders();
PCSC pcsc = new PCSC(readers[0]);
ArculusFido arculusFido = new ArculusFido(pcsc);

// Registration
ArculusFidoServer fidoServer = new ArculusFidoServer("fido.example.com");
fidoServer.setBeginRegistrationPath("fidoapi/certify/attestation/options", null);
fidoServer.setCompleteRegistrationPath("fidoapi/certify/attestation/result", null);

String result = arculusFido.register(
    fidoServer,
    "123456",                    // pin
    "[email protected]",          // username
    "My Device",                 // displayName
    "example.com",               // relyingParty
    false,                       // resetDevice
    null                         // registrationInfo
);
System.out.println("Registration: " + result);

// Authentication
fidoServer.setBeginAuthorizationPath("fidoapi/certify/assertion/options", null);
fidoServer.setCompleteAuthorizationPath("fidoapi/certify/assertion/result", null);

String authResult = arculusFido.authenticate(
    fidoServer,
    "123456",                    // pin
    "[email protected]",          // username
    "My Device",                 // displayName
    "example.com"                // relyingParty
);
System.out.println("Authentication: " + authResult);

Minimal Backend-Proxied Example

import co.arculus.fido.ArculusFido;
import co.arculus.fido.ArculusFidoOptionsAuthorizationResponse;
import co.arculus.pcsc.PCSC;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

// Initialize PC/SC reader
String[] readers = PCSC.listPCSCReaders();
PCSC pcsc = new PCSC(readers[0]);
ArculusFido arculusFido = new ArculusFido(pcsc);

// Registration (3-phase flow)
public void register() throws Exception {
    // Phase 1: Get challenge from backend
    JsonObject beginResponse = backendClient.registerBegin("[email protected]", "My Device", "example.com");
    String challenge = beginResponse.getAsJsonObject("fidoServerResponse").get("challenge").getAsString();
    String rpId = beginResponse.getAsJsonObject("fidoServerResponse").get("rp").getAsJsonObject("id").getAsString();
    
    // Phase 2: Card operations only
    String cardResponse = arculusFido.registerCardOnly(
        "123456",                    // pin
        "[email protected]",          // username
        "My Device",                 // displayName
        rpId,                        // relyingParty
        challenge,                   // challenge
        "https://example.com"        // origin
    );
    
    // Phase 3: Complete with backend
    JsonObject cardResponseData = JsonParser.parseString(cardResponse).getAsJsonObject();
    JsonObject completeResponse = backendClient.registerComplete("[email protected]", cardResponseData);
    System.out.println("Registration: " + completeResponse);
}

// Authentication (3-phase flow)
public void authenticate() throws Exception {
    // Phase 1: Get challenge from backend
    JsonObject beginResponse = backendClient.authenticateBegin("[email protected]", "example.com");
    ArculusFidoOptionsAuthorizationResponse optionsResponse = 
        createOptionsResponseFromBackend(beginResponse);
    
    // Phase 2: Card operations only
    AuthenticateCardSignResponse cardResponse = arculusFido.authenticateCardOnly(
        "123456",                    // pin
        "[email protected]",          // username
        "example.com",               // relyingParty
        optionsResponse              // optionsResponse
    );
    
    // Phase 3: Complete with backend
    JsonObject cardResponseData = new JsonObject();
    cardResponseData.addProperty("id", cardResponse.getId());
    cardResponseData.addProperty("rawId", cardResponse.getRawId());
    cardResponseData.add("response", cardResponse.getResponse());
    
    JsonObject completeResponse = backendClient.authenticateComplete("[email protected]", cardResponseData);
    System.out.println("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 desktop application demonstrating direct FIDO2 server communication:

import co.arculus.fido.ArculusFido;
import co.arculus.fido.ArculusFidoServer;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

public class DesktopFidoApp {
    private ArculusFido arculusFido;
    
    public DesktopFidoApp() {
        // Initialize SDK with PC/SC reader
        arculusFido = new ArculusFido();
    }
    
    public void registerUser(String pin, String username, String displayName, String rpId) {
        try {
            // Configure FIDO2 server
            ArculusFidoServer fidoServer = new ArculusFidoServer(
                "fido.example.com",
                "fidoapi/certify/attestation/options",
                "fidoapi/certify/attestation/result",
                "fidoapi/certify/assertion/options",
                "fidoapi/certify/assertion/result"
            );
            
            // Perform registration
            String result = arculusFido.register(
                fidoServer,
                pin,
                username,
                displayName,
                rpId,
                false,
                null  // registrationInfo
            );
            
            // Parse result
            JsonObject resultJson = JsonParser.parseString(result).getAsJsonObject();
            if ("ok".equals(resultJson.get("status").getAsString())) {
                System.out.println("Registration successful!");
            } else {
                System.err.println("Registration failed: " + 
                    resultJson.get("errorMessage").getAsString());
            }
        } catch (Exception e) {
            System.err.println("Error during registration: " + e.getMessage());
            e.printStackTrace();
        }
    }
    
    public void authenticateUser(String pin, String username, String displayName, String rpId) {
        try {
            // Configure FIDO2 server
            ArculusFidoServer fidoServer = new ArculusFidoServer(
                "fido.example.com",
                "fidoapi/certify/attestation/options",
                "fidoapi/certify/attestation/result",
                "fidoapi/certify/assertion/options",
                "fidoapi/certify/assertion/result"
            );
            
            // Perform authentication
            String result = arculusFido.authenticate(
                fidoServer,
                pin,
                username,
                displayName,
                rpId
            );
            
            // Parse result
            JsonObject resultJson = JsonParser.parseString(result).getAsJsonObject();
            if ("ok".equals(resultJson.get("status").getAsString())) {
                System.out.println("Authentication successful!");
            } else {
                System.err.println("Authentication failed: " + 
                    resultJson.get("errorMessage").getAsString());
            }
        } catch (Exception e) {
            System.err.println("Error during authentication: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Backend-Proxied Pattern (Recommended)

A complete desktop application demonstrating the backend-proxied pattern with 3-phase authentication and registration flows. This pattern is recommended for production deployments.

Backend API Client

package com.arculus.desktop.backend;

import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import java.io.IOException;
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;

public class BackendApiClient {
    private final String baseUrl;
    private String sessionCookies = null;
    
    public BackendApiClient(String baseUrl) {
        this.baseUrl = baseUrl;
    }
    
    public void clearSessionCookies() {
        sessionCookies = null;
    }
    
    public JsonObject authenticateBegin(String username, String rpId) throws IOException {
        JsonObject request = new JsonObject();
        request.addProperty("operation", "authenticate");
        request.addProperty("username", username);
        request.addProperty("rpId", rpId);
        
        JsonObject response = makeRequest("/fido/authenticate", request);
        extractAndStoreCookies(response);
        return response;
    }
    
    public JsonObject authenticateComplete(
        JsonObject cardResponseData, 
        String sessionId, 
        String username
    ) throws IOException {
        JsonObject request = new JsonObject();
        request.addProperty("operation", "authenticate");
        request.addProperty("username", username);
        request.add("cardResponseData", cardResponseData);
        
        if (sessionId != null) {
            request.addProperty("sessionId", sessionId);
        }
        
        if (sessionCookies != null) {
            request.addProperty("cookies", sessionCookies);
        }
        
        return makeRequest("/fido/authenticate", request);
    }
    
    public JsonObject registerBegin(String username, String displayName, String rpId) throws IOException {
        JsonObject request = new JsonObject();
        request.addProperty("operation", "register");
        request.addProperty("username", username);
        request.addProperty("displayName", displayName);
        request.addProperty("rpId", rpId);
        
        JsonObject response = makeRequest("/fido/register", request);
        extractAndStoreCookies(response);
        return response;
    }
    
    public JsonObject registerComplete(String username, JsonObject cardResponseData) throws IOException {
        JsonObject request = new JsonObject();
        request.addProperty("operation", "register");
        request.addProperty("username", username);
        request.add("cardResponseData", cardResponseData);
        
        if (sessionCookies != null && !sessionCookies.trim().isEmpty()) {
            request.addProperty("cookies", sessionCookies);
        }
        
        return makeRequest("/fido/register", request);
    }
    
    private JsonObject makeRequest(String endpoint, JsonObject requestBody) throws IOException {
        URL url = new URL(baseUrl + endpoint);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("POST");
        conn.setRequestProperty("Content-Type", "application/json");
        
        if (sessionCookies != null && !sessionCookies.trim().isEmpty()) {
            conn.setRequestProperty("Cookie", sessionCookies);
        }
        
        conn.setDoOutput(true);
        
        // Write request body
        try (OutputStream os = conn.getOutputStream()) {
            byte[] input = requestBody.toString().getBytes("utf-8");
            os.write(input, 0, input.length);
        }
        
        // Read response
        int responseCode = conn.getResponseCode();
        if (responseCode != HttpURLConnection.HTTP_OK) {
            throw new IOException("HTTP error code: " + responseCode);
        }
        
        try (BufferedReader br = new BufferedReader(
                new InputStreamReader(conn.getInputStream(), "utf-8"))) {
            StringBuilder response = new StringBuilder();
            String responseLine;
            while ((responseLine = br.readLine()) != null) {
                response.append(responseLine.trim());
            }
            JsonObject jsonResponse = JsonParser.parseString(response.toString()).getAsJsonObject();
            
            // Extract cookies from JSON response body
            extractAndStoreCookies(jsonResponse);
            
            return jsonResponse;
        }
    }
    
    /**
     * Extract cookies from JSON response body and store them for session continuity
     */
    private void extractAndStoreCookies(JsonObject response) {
        if (response.has("cookies") && !response.get("cookies").isJsonNull()) {
            String cookiesFromResponse = response.get("cookies").getAsString();
            if (cookiesFromResponse != null && !cookiesFromResponse.trim().isEmpty()) {
                sessionCookies = cookiesFromResponse;
            }
        }
    }
}

Helper Function: Create Options Response

import co.arculus.fido.options.ArculusFidoOptionsAuthorizationResponse;
import co.arculus.fido.internal.ArculusFidoCredUtil;
import co.arculus.fido.internal.HexUtils;
import com.google.gson.JsonArray;
import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import java.security.MessageDigest;
import java.util.ArrayList;
import java.util.Base64;
import java.util.List;
import java.util.Map;

public class FidoOptionsHelper {
    public static ArculusFidoOptionsAuthorizationResponse createOptionsResponseFromBackend(
            JsonObject fidoServerResponse, 
            String challenge, 
            String rpId, 
            String fido2ServerOrigin) throws Exception {
        
        ArculusFidoOptionsAuthorizationResponse result = 
            new ArculusFidoOptionsAuthorizationResponse();
        
        // Extract allowCredentials from FIDO2 server response
        List<Map<String, Object>> allowCredentials = new ArrayList<>();
        if (fidoServerResponse.has("allowCredentials")) {
            JsonArray allowCredentialsArray = fidoServerResponse.getAsJsonArray("allowCredentials");
            for (JsonElement element : allowCredentialsArray) {
                JsonObject cred = element.getAsJsonObject();
                Map<String, Object> credMap = new java.util.HashMap<>();
                credMap.put("id", cred.get("id").getAsString());
                credMap.put("type", cred.has("type") ? cred.get("type").getAsString() : "public-key");
                allowCredentials.add(credMap);
            }
        }
        
        // Convert to CBOR allowList
        byte[] allowList = null;
        if (!allowCredentials.isEmpty()) {
            ArrayList<Map<String, Object>> allowCredentialsList = 
                new ArrayList<>(allowCredentials);
            String allowListCBORHexString = ArculusFidoCredUtil.CBORallowListString(allowCredentialsList);
            if (allowListCBORHexString != null) {
                allowList = HexUtils.hexToBytes(allowListCBORHexString);
            }
        }
        
        if (allowList == null) {
            allowList = new byte[0];
        }
        
        result.setAllowList(allowList);
        result.setChallenge(challenge);
        result.setRpId(rpId);
        
        // Construct clientDataJSON
        JsonObject clientDataJson = new JsonObject();
        clientDataJson.addProperty("type", "webauthn.get");
        clientDataJson.addProperty("challenge", challenge);
        clientDataJson.addProperty("origin", fido2ServerOrigin);
        
        String clientDataString = clientDataJson.toString();
        byte[] clientDataBytes = clientDataString.getBytes(java.nio.charset.StandardCharsets.UTF_8);
        String clientDataBase64 = Base64.getUrlEncoder()
            .withoutPadding()
            .encodeToString(clientDataBytes);
        
        result.setClientDataJSONbase64(clientDataBase64);
        
        // Calculate clienthash (SHA-256 of clientDataJSON string)
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] clienthash = digest.digest(clientDataString.getBytes(java.nio.charset.StandardCharsets.UTF_8));
        result.setClienthash(clienthash);
        
        // Calculate RPIDhash (SHA-256 of rpId)
        byte[] rpIdHash = digest.digest(rpId.getBytes(java.nio.charset.StandardCharsets.UTF_8));
        result.setRPIDhash(rpIdHash);
        
        return result;
    }
}

Complete Backend-Proxied Sample App

import co.arculus.fido.ArculusFido;
import co.arculus.fido.authenticate.AuthenticateCardSignResponse;
import co.arculus.fido.options.ArculusFidoOptionsAuthorizationResponse;
import com.arculus.desktop.backend.BackendApiClient;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

public class DesktopFidoApp {
    private ArculusFido arculusFido;
    private BackendApiClient backendClient;
    
    public DesktopFidoApp(String backendUrl) {
        // Initialize SDK with PC/SC reader
        arculusFido = new ArculusFido();
        
        // Initialize backend client
        backendClient = new BackendApiClient(backendUrl);
    }
    
    public void registerUser(String pin, String username, String displayName, String rpId) {
        try {
            // Phase 1: Backend gets challenge
            // Note: If displayName is null, it will default to username
            JsonObject backendResponse = backendClient.registerBegin(
                username, 
                displayName != null ? displayName : username, 
                rpId
            );
            
            if (!backendResponse.has("status") || 
                !"success".equals(backendResponse.get("status").getAsString())) {
                // Error messages may be in "message" or "errorMessage" field
                String errorMsg = backendResponse.has("message") ? 
                    backendResponse.get("message").getAsString() : "Backend registration begin failed";
                System.err.println(errorMsg);
                return;
            }
            
            JsonObject fidoServerResponse = backendResponse.getAsJsonObject("fidoServerResponse");
            if (fidoServerResponse == null) {
                System.err.println("Backend response missing fidoServerResponse");
                return;
            }
            
            String challenge = fidoServerResponse.has("challenge") ? 
                fidoServerResponse.get("challenge").getAsString() : null;
            if (challenge == null) {
                System.err.println("Backend response missing challenge");
                return;
            }
            
            // Extract rpId from server response if available (CRITICAL: must match what server expects)
            String rpIdFromServer = rpId; // Fallback to provided value
            if (fidoServerResponse.has("rp")) {
                JsonObject rpObject = fidoServerResponse.getAsJsonObject("rp");
                if (rpObject != null && rpObject.has("id")) {
                    rpIdFromServer = rpObject.get("id").getAsString();
                }
            }
            
            // Extract fido2ServerOrigin (required for clientDataJSON)
            String fido2ServerOrigin = backendResponse.has("fido2ServerOrigin") ? 
                backendResponse.get("fido2ServerOrigin").getAsString() : null;
            if (fido2ServerOrigin == null) {
                // Fallback: extract from backend URL if not provided
                String backendUrl = backendClient.getBaseUrl();
                fido2ServerOrigin = backendUrl.replaceAll("/$", "");
            }
            
            // Note: Session cookies are automatically stored by backendClient.registerBegin()
            
            // Phase 2: Card operations only
            // registerCardOnly() takes challenge and origin directly (not optionsResponse)
            String cardResponseJson = arculusFido.registerCardOnly(
                pin,
                username,
                displayName != null ? displayName : username,
                rpIdFromServer,  // Use rpId from server response
                challenge,        // Base64-encoded challenge from backend
                fido2ServerOrigin  // Origin URL for clientDataJSON
            );
            
            if (cardResponseJson == null || cardResponseJson.trim().isEmpty()) {
                System.err.println("Card registration returned null or empty response");
                return;
            }
            
            JsonObject cardResponseData = JsonParser.parseString(cardResponseJson).getAsJsonObject();
            
            // Extract credential ID for potential rollback
            String credentialId = null;
            if (cardResponseData.has("id")) {
                credentialId = cardResponseData.get("id").getAsString();
            }
            
            // Phase 3: Backend completes registration
            // Note: Session cookies are automatically included from Phase 1
            JsonObject completeResponse = backendClient.registerComplete(
                username, 
                cardResponseData
            );
            
            if (completeResponse.has("status") && 
                "success".equals(completeResponse.get("status").getAsString())) {
                System.out.println("Registration successful!");
            } else {
                // Registration failed - rollback: delete credential from card
                // Error messages may be in "message" or "errorMessage" field
                String errorMsg = completeResponse.has("message") ? 
                    completeResponse.get("message").getAsString() : 
                    (completeResponse.has("errorMessage") ? 
                        completeResponse.get("errorMessage").getAsString() : "Registration failed");
                
                // Perform rollback if credential was created
                if (credentialId != null) {
                    try {
                        arculusFido.deleteCredentialByCredentialId(pin, credentialId);
                    } catch (Exception rollbackError) {
                        errorMsg += " (Warning: Credential may still exist on card - rollback failed)";
                    }
                }
                
                System.err.println("Registration failed: " + errorMsg);
            }
        } catch (java.io.IOException e) {
            // Backend request failed - rollback needed if card operation succeeded
            System.err.println("Registration failed: Network error - " + 
                (e.getMessage() != null ? e.getMessage() : "Connection failed"));
        } catch (Exception e) {
            System.err.println("Error during registration: " + 
                (e.getMessage() != null ? e.getMessage() : "Unknown error"));
            e.printStackTrace();
        }
    }
    
    public void authenticateUser(String pin, String username, String rpId) {
        try {
            // Phase 1: Backend gets challenge
            JsonObject backendResponse = backendClient.authenticateBegin(username, rpId);
            
            if (!backendResponse.has("status") || 
                !"success".equals(backendResponse.get("status").getAsString())) {
                // Error messages may be in "message" or "errorMessage" field
                String errorMsg = backendResponse.has("message") ? 
                    backendResponse.get("message").getAsString() : "Backend authentication begin failed";
                System.err.println(errorMsg);
                return;
            }
            
            JsonObject fidoServerResponse = backendResponse.getAsJsonObject("fidoServerResponse");
            if (fidoServerResponse == null) {
                System.err.println("Backend response missing fidoServerResponse");
                return;
            }
            
            String challenge = fidoServerResponse.has("challenge") ? 
                fidoServerResponse.get("challenge").getAsString() : null;
            if (challenge == null) {
                System.err.println("Backend response missing challenge");
                return;
            }
            
            // Extract rpId from server response if available (CRITICAL: must match what server expects)
            String rpIdFromServer = rpId; // Fallback to provided value
            if (fidoServerResponse.has("rpId")) {
                rpIdFromServer = fidoServerResponse.get("rpId").getAsString();
            }
            
            // Extract fido2ServerOrigin (required for clientDataJSON)
            String fido2ServerOrigin = backendResponse.has("fido2ServerOrigin") ? 
                backendResponse.get("fido2ServerOrigin").getAsString() : null;
            if (fido2ServerOrigin == null) {
                // Fallback: extract from backend URL if not provided
                String backendUrl = backendClient.getBaseUrl();
                fido2ServerOrigin = backendUrl.replaceAll("/$", "");
            }
            
            String sessionId = backendResponse.has("sessionId") ? 
                backendResponse.get("sessionId").getAsString() : null;
            // Note: Session cookies are automatically stored by backendClient.authenticateBegin()
            
            // Phase 2: Card operations only
            ArculusFidoOptionsAuthorizationResponse optionsResponse = 
                FidoOptionsHelper.createOptionsResponseFromBackend(
                    fidoServerResponse, 
                    challenge, 
                    rpIdFromServer,  // Use rpId from server response
                    fido2ServerOrigin
                );
            
            // Perform card-only authentication
            AuthenticateCardSignResponse cardResponse = arculusFido.authenticateCardOnly(
                pin, 
                username, 
                rpIdFromServer,  // Use rpId from server response
                optionsResponse
            );
            
            // Build FIDO2 authentication response
            JsonObject fido2Response = new JsonObject();
            fido2Response.addProperty("type", "public-key");
            fido2Response.addProperty("id", cardResponse.getId());
            fido2Response.addProperty("rawId", cardResponse.getRawId());
            
            JsonObject responseData = new JsonObject();
            responseData.addProperty("authenticatorData", cardResponse.getAuthdataBase64());
            responseData.addProperty("signature", cardResponse.getSignatureBase64());
            responseData.addProperty("clientDataJSON", optionsResponse.getClientDataJSONbase64());
            
            fido2Response.add("response", responseData);
            
            // Phase 3: Backend completes authentication
            JsonObject completeResponse = backendClient.authenticateComplete(
                fido2Response, 
                sessionId, 
                username
            );
            
            if (completeResponse.has("status") && 
                "success".equals(completeResponse.get("status").getAsString())) {
                System.out.println("Authentication successful!");
            } else {
                // Error messages may be in "message" or "errorMessage" field
                String errorMsg = completeResponse.has("message") ? 
                    completeResponse.get("message").getAsString() : 
                    (completeResponse.has("errorMessage") ? 
                        completeResponse.get("errorMessage").getAsString() : "Authentication failed");
                System.err.println("Authentication failed: " + errorMsg);
            }
        } catch (java.io.IOException e) {
            System.err.println("Authentication failed: Network error - " + 
                (e.getMessage() != null ? e.getMessage() : "Connection failed"));
        } catch (Exception e) {
            System.err.println("Error during authentication: " + 
                (e.getMessage() != null ? e.getMessage() : "Unknown error"));
            e.printStackTrace();
        }
    }
}

Backend Implementation (Java Servlet)

The backend service receives requests from the Desktop app and proxies them to the FIDO2 Server. The implementation is identical to the iOS/Android backend (see 5.2 iOS Sample Applications - Backend Implementation) since all client applications use the same backend API contract.

Key Points:

• Same operation-based routing (operation: "register" or operation: "authenticate")

• Same phase detection (presence of cardResponseData determines begin vs. complete)

• Same session cookie handling

• Same FIDO2 Server REST API endpoints

The backend implementation shown in the iOS sample applications page applies to Desktop applications as well.