Integration Workflow
This page provides a step-by-step workflow for integrating Arculus FIDO2 authentication into your application as a third-level authentication factor or for transactional authorization (e.g., approving financial transactions in a banking app).
Overview
The integration process involves several key steps:
Planning and Architecture - Understand requirements and choose deployment pattern
Environment Setup - Set up local development environment
SDK Integration - Add SDK to your application
Implementation - Implement registration and authentication flows
Testing - Test with local FIDO2 server
Production Deployment - Deploy to production environment
Step 1: Planning and Architecture
Understand Your Requirements
Before starting, clarify:
Use case: Third-level authentication, transactional authorization, or passwordless login?
Platform: iOS, Android, Desktop, or Web?
Existing authentication: What authentication system are you integrating with? (OAuth2/OIDC provider, custom IAM, etc.)
Security requirements: What level of security isolation is needed? (See 1.2 Development Options (Security) for guidance)
User experience: When should FIDO2 be triggered? (After primary/secondary auth? During transactions?)
Choose Deployment Pattern
Decide between client-direct and backend-proxied patterns. See 1.2 Development Options (Security) for:
Detailed comparison of both approaches
Security implications of each pattern
Decision criteria to help you choose
Architecture diagrams and characteristics
Review Architecture
Review 1.1 System Architecture to understand component interactions and deployment patterns
Understand how FIDO2 fits into your existing authentication flow
Identify integration points with your OAuth2/OIDC provider or IAM system
Review 1.4 FIDO2 Core Concepts for essential terminology
Step 2: Environment Setup
Obtain Required Files
SDK Files:
Contact your Arculus representative to obtain the SDK for your platform:
iOS:
ArculusFidoSDKFramework.zip(XCFramework)Android:
ArculusFidoSDK.aar(AAR library)Desktop:
ArculusFidoSDK-1.0.0.jar(JAR file)Web:
arculusfido.js(JavaScript SDK)
FIDO2 Server Distribution Package:
Contact your Arculus representative to obtain the FIDO2 Server distribution package (ZIP file)
Required for local development and testing
Set Up Local Development Environment
Follow 3.3 Local Development for complete setup instructions, including:
Obtaining the distribution package
Docker Compose setup
Python direct execution options
Verification steps
Development tips and troubleshooting
Step 3: SDK Integration
Install SDK in Your Application
Follow the platform-specific installation guide:
Android: 2.3 Android SDK - Installation
Desktop: 2.4 Desktop SDK - Installation
Basic SDK Setup
For platform-specific installation and setup instructions, see:
Android: 2.3 Android SDK - Installation
Desktop: 2.4 Desktop SDK - Installation
Each guide includes complete installation steps, dependencies, and initial setup code.
Step 4: Implementation
Understand FIDO2 Concepts
Before implementing, review:
1.4 FIDO2 Core Concepts - Essential terminology
1.5 Authenticator Lifecycle - Registration and authentication flows
Start with Minimal Examples
Review the minimal examples in the appendix for your platform:
These show the essential code flow without UI scaffolding or error handling.
Implement Registration Flow
For Client-Direct Pattern:
Follow your platform SDK guide:
For Backend-Proxied Pattern:
Follow your platform SDK guide:
Note: Web SDK only supports client-direct pattern.
Implement Authentication Flow
For Client-Direct Pattern:
Follow your platform SDK guide:
For Backend-Proxied Pattern:
Follow your platform SDK guide:
Review Sequence Diagrams
For detailed flow understanding, review sequence diagrams in your platform SDK guide:
Implement Error Handling
Review 2.7 Error Codes for error code meanings
Implement appropriate error handling based on your platform's error handling patterns
Check sample applications for error handling examples
Integrate with Existing Authentication
For Third-Level Authentication:
User completes primary authentication (username/password, OAuth2, etc.)
User completes secondary authentication (if required)
Trigger FIDO2 authentication when third-level is needed
Validate FIDO2 authentication result
Grant access or approve transaction
For Transactional Authorization:
User initiates transaction (e.g., transfer funds)
User completes primary authentication if not already authenticated
Trigger FIDO2 authentication for transaction approval
Validate FIDO2 authentication result
Execute transaction if authentication succeeds
Step 5: Testing
Test with Local FIDO2 Server
Verify server is running: See 3.3 Local Development for verification steps
Test registration: Register a test user with your application
Test authentication: Authenticate the registered user
Verify in database: Check Mongo Express to see stored credentials
Test Scenarios
Test these scenarios to ensure robust error handling:
Successful registration: User registers with valid PIN and card
Successful authentication: User authenticates with registered credential
Invalid PIN: Test error handling for wrong PIN
Card not present: Test error handling when card is not detected
Network errors: Test error handling for server connectivity issues
Session expiration: Test handling of expired sessions (backend-proxied only)
Debugging
For debugging help, see:
2.7 Error Codes - Error code meanings and solutions
3.4 Troubleshooting - Common issues and solutions
Sample applications in 5. Appendix - Error handling examples
Step 6: Production Deployment
Deploy FIDO2 Server
Choose your deployment option:
AWS ECS: Follow 3.1 AWS ECS Configuration
Docker: Follow 3.2 Docker Configuration
Other platforms: See 3. Deployment for options
Configure Production Settings
Security: Review 4. Security and implement recommended security measures
4.1 Application Security - Application-level security (input validation, headers, CORS, etc.)
4.2 Deployment Security - Infrastructure security (TLS, secrets management, network security)
Multi-tenant: If needed, follow 1.3 Multi-Tenant Support for setup instructions
Monitoring: Set up health checks and logging (see deployment guides)
SSL/TLS: Ensure all communications use HTTPS (see 4.2 Deployment Security)
Update Application Configuration
Update FIDO2 server URLs from localhost to production endpoints
Configure production relying party IDs
Update any environment-specific settings
Test with production FIDO2 server before going live
Common Integration Patterns
Pattern 1: OAuth2/OIDC Integration
Flow:
User authenticates with OAuth2/OIDC provider (primary auth)
Provider returns access token and ID token
Application triggers FIDO2 authentication (third-level)
Application validates both OAuth2 and FIDO2 authentication
Grant access to protected resource
Implementation:
Use OAuth2 access token for API calls
Trigger FIDO2 authentication after OAuth2 success
Store FIDO2 credential ID with user session
Validate FIDO2 on sensitive operations
Pattern 2: Transactional Authorization
Flow:
User initiates transaction (e.g., transfer $10,000)
Application checks if user is authenticated
Application triggers FIDO2 authentication for transaction approval
Application validates FIDO2 authentication
Execute transaction if authentication succeeds
Implementation:
Trigger FIDO2 authentication before executing transaction
Include transaction details in authentication context (if needed)
Validate FIDO2 result before committing transaction
Log transaction with FIDO2 authentication timestamp
Pattern 3: Step-Up Authentication
Flow:
User accesses low-security resource (basic auth sufficient)
User attempts to access high-security resource
Application triggers FIDO2 authentication (step-up)
Application validates FIDO2 authentication
Grant access to high-security resource
Implementation:
Check user's current authentication level
Trigger FIDO2 when accessing high-security resources
Cache FIDO2 authentication result for session
Re-authenticate with FIDO2 if session expires
Timeline Estimate
Typical Integration Timeline:
Planning and Architecture: 1-2 days
Environment Setup: 1 day
SDK Integration: 1 day
Implementation (Registration + Authentication): 3-5 days
Testing: 2-3 days
Production Deployment: 2-3 days
Total: 10-15 days (depending on complexity and team experience)
Next Steps
After completing the integration workflow:
Review complete sample applications for production-ready patterns
Implement security best practices from 4. Security
Set up monitoring and logging for production
Document your integration
Last updated