Backend Integration Helpers

This page provides complete implementations of helper classes and functions required for backend-proxied deployments. These helpers handle backend API communication and transform FIDO2 server responses into formats required by the SDK.

Note: These are reference implementations. You may need to adapt them to your specific backend API contract, error handling requirements, and security policies.

iOS (Swift)

BackendApiClient

The BackendApiClient class handles communication with your backend services, including session cookie management.

import Foundation

class BackendApiClient {
    private let baseUrl: String
    private var sessionCookies: String?
    
    init(baseUrl: String) {
        self.baseUrl = baseUrl
    }
    
    func clearSessionCookies() {
        sessionCookies = nil
    }
    
    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
    }
    
    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
    }
    
    private func extractAndStoreCookies(from response: [String: Any]) {
        if let cookies = response["cookies"] as? String, !cookies.isEmpty {
            sessionCookies = cookies
        }
    }
}

createOptionsResponseFromBackend

This helper function constructs an ArculusFidoOptionsAuthorizationResponse from the backend response for use with authenticateCardOnly().

import Foundation
import CommonCrypto

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
}

Android (Java)

BackendApiClient

The BackendApiClient class handles communication with your backend services, including session cookie management and SSL certificate handling.

import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;
import javax.net.ssl.SSLContext;
import javax.net.ssl.TrustManager;
import javax.net.ssl.X509TrustManager;
import java.io.IOException;
import java.security.cert.X509Certificate;
import java.util.concurrent.TimeUnit;

public class BackendApiClient {
    private final OkHttpClient httpClient;
    private final String baseUrl;
    private String sessionCookies = null;
    
    public BackendApiClient(AppConfig appConfig) {
        if (appConfig == null) {
            throw new IllegalArgumentException("AppConfig cannot be null");
        }
        this.baseUrl = appConfig.getBackendServerUrl();
        
        OkHttpClient.Builder builder = new OkHttpClient.Builder()
            .connectTimeout(appConfig.getBackendApiTimeout(), TimeUnit.SECONDS)
            .readTimeout(appConfig.getBackendApiTimeout(), TimeUnit.SECONDS)
            .writeTimeout(appConfig.getBackendApiTimeout(), TimeUnit.SECONDS);
        
        // Handle self-signed certificates if configured
        // WARNING: This disables SSL certificate validation - use only for development/testing
        if (appConfig.isTrustSelfSignedCerts()) {
            try {
                TrustManager[] trustAllCerts = new TrustManager[]{
                    new X509TrustManager() {
                        @Override
                        public void checkClientTrusted(java.security.cert.X509Certificate[] chain, String authType) {
                        }
                        
                        @Override
                        public void checkServerTrusted(java.security.cert.X509Certificate[] chain, String authType) {
                        }
                        
                        @Override
                        public java.security.cert.X509Certificate[] getAcceptedIssuers() {
                            return new java.security.cert.X509Certificate[]{};
                        }
                    }
                };
                
                SSLContext sslContext = SSLContext.getInstance("TLS");
                sslContext.init(null, trustAllCerts, new java.security.SecureRandom());
                builder.sslSocketFactory(sslContext.getSocketFactory(), (X509TrustManager) trustAllCerts[0]);
                builder.hostnameVerifier((hostname, session) -> true);
            } catch (Exception e) {
                // Log error but continue without SSL trust override
            }
        }
        
        this.httpClient = builder.build();
    }
    
    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 && !sessionCookies.trim().isEmpty()) {
            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 {
        String url = baseUrl + endpoint;
        
        RequestBody body = RequestBody.create(
            requestBody.toString(),
            MediaType.parse("application/json; charset=utf-8")
        );
        
        Request.Builder requestBuilder = new Request.Builder()
            .url(url)
            .post(body)
            .addHeader("Content-Type", "application/json");
        
        // Add session cookies if available
        if (sessionCookies != null && !sessionCookies.trim().isEmpty()) {
            requestBuilder.addHeader("Cookie", sessionCookies);
        }
        
        Request request = requestBuilder.build();
        
        try (Response response = httpClient.newCall(request).execute()) {
            if (!response.isSuccessful()) {
                String errorBody = response.body() != null ? response.body().string() : "No error body";
                throw new IOException("Backend request failed: " + response.code() + " - " + errorBody);
            }
            
            String responseBody = response.body() != null ? response.body().string() : "{}";
            JsonObject jsonResponse = JsonParser.parseString(responseBody).getAsJsonObject();
            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;
            }
        }
    }
}

FidoOptionsHelper

The FidoOptionsHelper class provides a static method to transform backend responses into ArculusFidoOptionsAuthorizationResponse objects for use with authenticateCardOnly().

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 createFromBackendResponse(
            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;
    }
}

Desktop (Java)

BackendApiClient

The BackendApiClient class handles communication with your backend services, including session cookie management.

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

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;
            }
        }
    }
}

FidoOptionsHelper

The FidoOptionsHelper class provides a static method to transform backend responses into ArculusFidoOptionsAuthorizationResponse objects for use with authenticateCardOnly().

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;
    }
}

Related Documentation

• iOS SDK Integration - iOS SDK usage and integration guide

• Android SDK Integration - Android SDK usage and integration guide

• Desktop SDK Integration - Desktop SDK usage and integration guide

• iOS Sample Applications - Complete iOS sample applications

• Android Sample Applications - Complete Android sample applications

• Desktop Sample Applications - Complete Desktop sample applications