Web SDK

The Arculus FIDO SDK for Web provides a JavaScript library (arculusfido.js) that simplifies integration with the Arculus FIDO2 Server using browser WebAuthn APIs. The SDK handles all complexity of WebAuthn API calls, session management, and server communication.

Key Features:

• Simple JavaScript API

• Browser WebAuthn API wrapper

• Automatic session cookie management

• CORS support for cross-origin deployments

• Built-in error handling

Obtaining the SDK

Contact your Arculus representative to obtain the Web SDK distribution package. The package includes:

Component	Description
arculusfido.js	JavaScript SDK for browser WebAuthn integration
Sample Applications	Complete web apps demonstrating SDK usage
Documentation	API documentation and integration guide

The Web SDK is distributed as a JavaScript file that can be included via script tag or ES module import. See 5.5 Web Sample Applications for complete sample code.

Note: The Web SDK uses browser WebAuthn APIs and works with any WebAuthn-compatible authenticator, including Arculus FIDO2 cards via USB readers. For mobile integration with NFC, use the iOS or Android SDKs.

2.6.1 Installation

Requirements

• Modern web browser with WebAuthn support (Chrome, Firefox, Safari, Edge)

• HTTPS (required for WebAuthn in production)

• Arculus FIDO2 Server accessible from your web application

Installation Methods

Method 1: Script Tag

Include the SDK in your HTML:

<script type="text/javascript" src="arculusfido.js"></script>

Method 2: ES Module Import

import * as arculusfido from './arculusfido.js';

2.6.2 Configuration

Set FIDO Policy

Configure authentication preferences before registration or authentication:

arculusfido.FidoSetPolicy(
  "none",           // attestation: "none", "direct", "indirect"
  "cross-platform", // attachment: "platform", "cross-platform", "all"
  "preferred",      // userVerification: "preferred", "required", "discouraged"
  0                 // credProtect level (0-3)
);

Parameter Details:

Parameter	Default	Options	Description
attestation	"none"	none, direct, indirect	Attestation conveyance preference
attachment	"all"	platform, cross-platform, all	Authenticator type preference
userVerification	"preferred"	preferred, required, discouraged	User verification requirement
credProtect	0	0-3	Credential protection level

Set Custom Endpoints

If your Arculus FIDO2 Server deployment uses custom endpoint paths (e.g., behind a reverse proxy or API gateway), you can configure them:

arculusfido.FidoSetEndpoints(
  "/fidoapi/register/begin",       // Registration begin
  "/fidoapi/register/complete",    // Registration complete
  "/fidoapi/authenticate/begin",   // Authentication begin
  "/fidoapi/authenticate/complete" // Authentication complete
);

Default Endpoints: If not configured, the SDK uses these default paths:

• Registration begin: fidoapi/certify/attestation/options

• Registration complete: fidoapi/certify/attestation/result

• Authentication begin: fidoapi/certify/assertion/options

• Authentication complete: fidoapi/certify/assertion/result

Note: The alias paths (/fidoapi/register/begin, etc.) are also supported by the FIDO2 Server. Only configure custom endpoints if your deployment uses different paths.

2.6.3 Registration

Client-Direct Pattern

The client-direct pattern allows your web application to communicate directly with the FIDO2 server.

Function Signature

async function RegisterUser(
  username,      // string: Unique username (typically email)
  displayname,   // string: Display name shown on authenticator
  keypair,       // object|string: Device metadata (optional)
  servlet,       // string: Server URL prefix (empty for same origin)
  parms,         // string: Additional query parameters
  addHeaders     // object: Additional HTTP headers (e.g., {"X-ArculusFido-RelyingParty": "example.com"})
)

Returns: Promise resolving to response object with status, result/error, and statuscode fields.

Note: The SDK parameter is displayname (lowercase 'n'), but JavaScript is case-insensitive for parameter names, so displayName also works.

Registration Sequence Diagram

Basic Registration

async function registerUser() {
  const username = document.getElementById("username").value;
  const displayName = document.getElementById("displayName").value;
  const deviceInfo = { deviceinfo: "User's Device" };
  
  // Set policy (optional - uses defaults if not set)
  arculusfido.FidoSetPolicy("none", "cross-platform", "preferred", 0);
  
  // Register the user
  const result = await arculusfido.RegisterUser(
    username,     // Unique username (typically email)
    displayName,  // Display name shown on authenticator
    deviceInfo,   // Device metadata (optional, can be object or string)
    "",           // Server URL prefix (empty for same origin)
    "",           // Additional query parameters
    {}            // Additional headers (e.g., {"X-ArculusFido-RelyingParty": "example.com"})
  );
  
  if (result.status) {
    console.log("Registration successful");
    // Handle success - redirect or show message
  } else {
    console.error("Registration failed:", result.error);
    // Handle failure
  }
}

Registration with Custom Server URL

When the FIDO2 Server is on a different domain:

const result = await arculusfido.RegisterUser(
  username,
  displayName,  // Note: SDK parameter is 'displayname' (lowercase n)
  deviceInfo,
  "https://fido.example.com",  // FIDO2 Server URL
  "",
  {}  // Additional headers
);

Registration with Additional Parameters

Pass tenant or session information via query parameters or headers:

// Using query parameters
const result = await arculusfido.RegisterUser(
  username,
  displayName,
  deviceInfo,
  "",
  "tenant=acme&session=abc123",  // Query parameters
  {}
);

// Using custom headers (e.g., for multi-tenant)
const result = await arculusfido.RegisterUser(
  username,
  displayName,
  deviceInfo,
  "",
  "",
  {"X-ArculusFido-RelyingParty": "example.com"}  // Custom headers
);

Registration Response

// Success
{
  "status": true,
  "result": "successful",
  "statuscode": 200
}

// Failure - Network/Server Error
{
  "status": false,
  "error": "Error message. *Does effective Domain match FIDO server [--domain example.com]?",
  "statuscode": undefined  // May not be present for network errors
}

// Failure - Server Response Error
{
  "status": false,
  "result": "unsuccessful [error details]",
  "statuscode": 400  // HTTP status code
}

Note: Error responses may contain either an error field (for network/parsing errors) or a result field (for server response errors), but not both.

2.6.4 Authentication

Client-Direct Pattern

Function Signature

async function AuthenticateUser(
  username,      // string: Username to authenticate
  servlet,       // string: Server URL prefix (empty for same origin)
  parms,         // string: Additional query parameters
  addHeaders     // object: Additional HTTP headers (e.g., {"X-ArculusFido-RelyingParty": "example.com"})
)

Returns: Promise resolving to response object with status, result, jwtToken (if present), and statuscode fields.

Authentication Sequence Diagram

Basic Authentication

async function authenticateUser() {
  const username = document.getElementById("username").value;
  
  // Set policy for authentication
  arculusfido.FidoSetPolicy("none", "cross-platform", "required", 0);
  
  // Authenticate the user
  const result = await arculusfido.AuthenticateUser(
    username,  // Username to authenticate
    "",        // Server URL prefix
    "",        // Additional query parameters
    {}         // Additional headers (e.g., {"X-ArculusFido-RelyingParty": "example.com"})
  );
  
  if (result.status) {
    console.log("Authentication successful");
    
    // Check for JWT token in response
    if (result.jwtToken) {
      // Store token for subsequent API calls
      localStorage.setItem("authToken", result.jwtToken);
    }
    
    // Redirect to authenticated area
    window.location.href = "/dashboard";
  } else {
    console.error("Authentication failed:", result.error);
    // Handle failure - show error message
  }
}

Authentication Response

// Success
{
  "status": true,
  "result": result,  // Full fetch Response object (not parsed JSON)
  "jwtToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."  // From Authorization header
}

// Failure - User not found
{
  "status": false,
  "result": "User NOT FOUND",
  "statuscode": 404
}

// Failure - Server Response Error
{
  "status": false,
  "result": result,  // Full fetch Response object
  "statuscode": 400
}

// Failure - Network/WebAuthn Error
{
  "status": false,
  "error": "Error message"
}

Important Notes:

• JWT Token: The jwtToken field is extracted from the HTTP Authorization response header, not from the response body. If the server does not include this header, jwtToken will be undefined.

• Result Field: On success, the result field contains the full fetch Response object, not parsed JSON. To access the response body, use await result.result.json().

• Error Format: Error responses may contain either a result field (for server responses) or an error field (for network/WebAuthn errors), but not both.

2.6.5 CORS Configuration

When your web application and FIDO2 Server are on different domains:

Server Requirements

The FIDO2 Server supports CORS with:

• Access-Control-Allow-Origin header

• Access-Control-Allow-Credentials: true

Client Requirements

Ensure fetch calls include credentials:

fetch(url, {
  method: "POST",
  credentials: "include",  // Required for cookies
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify(data)
});

2.6.6 Session Management

Cookie-Based Sessions

The SDK uses cookies to maintain session state between begin and complete calls:

• Cookies are sent with credentials: 'include'

• Server sets session cookie with SameSite=None; Secure

• Session expires after timeout (default 60 seconds)

Relying Party Header

For multi-tenant deployments, specify the relying party using the addHeaders parameter:

// Registration with relying party header
const result = await arculusfido.RegisterUser(
  username,
  displayName,
  deviceInfo,
  "",
  "",
  {"X-ArculusFido-RelyingParty": "example.com"}
);

// Authentication with relying party header
const result = await arculusfido.AuthenticateUser(
  username,
  "",
  "",
  {"X-ArculusFido-RelyingParty": "example.com"}
);

2.6.7 Error Handling

Common Errors and Solutions

Error	Cause	Solution
"Session expired"	Begin/complete took too long	Retry the flow from begin
"No account for user"	Username not registered	Direct user to registration
"Unknown relying party"	Invalid domain configuration	Check X-ArculusFido-RelyingParty header
"Domain mismatch"	Origin doesn't match RP ID	Ensure client domain matches server config
"Connection timeout"	Server unreachable	Check network and server status

Error Handling Pattern

async function handleFidoOperation(operation) {
  try {
    const result = await operation();
    
    if (result.status === false) {
      // FIDO operation failed
      if (result.statuscode === 404) {
        return { success: false, message: "User not found" };
      } else if (result.statuscode === 408) {
        return { success: false, message: "Session expired, please try again" };
      } else {
        // Check both error and result fields (SDK returns one or the other)
        return { success: false, message: result.error || result.result || "Operation failed" };
      }
    }
    
    return { success: true, data: result };
    
  } catch (error) {
    // Network or other error
    console.error("FIDO operation error:", error);
    return { success: false, message: "Connection error" };
  }
}

// Usage
const result = await handleFidoOperation(() => 
  arculusfido.AuthenticateUser(username, "", "", {})
);

if (result.success) {
  // Handle success
} else {
  showError(result.message);
}

For detailed error codes, see 2.7 Error Codes.

2.6.8 Complete Sample Applications

For complete web application examples, including HTML structure, error handling, multi-tenant support, and cross-origin configurations, see 5.5 Web Sample Applications in the Appendix.

2.6.9 Security Best Practices

Transport Security

• Always use HTTPS in production

• Validate SSL certificates

Origin Validation

• Server validates request origin against relying party

• Ensure client domain is registered

User Verification

• Use required for high-security operations

• Use preferred for balanced security/UX

Token Storage

• Store JWT tokens securely (HttpOnly cookies preferred)

• Implement token refresh mechanisms

Error Messages

• Don't expose internal errors to users

• Log detailed errors server-side