oauth2-passkey

A framework-agnostic core library for OAuth2 and WebAuthn/passkey authentication in Rust applications.

This library provides the essential authentication logic and coordination functions that can be integrated into any Rust web framework. It handles complex authentication flows while leaving web framework integration to separate crates.

Features

Framework-Agnostic: Core authentication logic independent of web frameworks
OAuth2 Support: Google OAuth2/OIDC authentication with extensible provider system
WebAuthn/Passkey: FIDO2-compliant passwordless authentication
Secure Session Management: Redis and in-memory session storage with secure cookies
Flexible Storage: SQLite and PostgreSQL database support
CSRF Protection: Built-in protection against cross-site request forgery
Security-First Design: Timing-attack resistant with cryptographically secure randomness

Web Framework Integrations

This core library is designed to be used with framework-specific integration crates:

oauth2-passkey-axum - Axum web framework integration
Other frameworks - Additional integration crates can be built using this core library

For most users: Use the framework-specific integration crates rather than this core library directly.

Core API

The library exposes coordination functions for authentication flows:

use oauth2_passkey::{
    init, 
    handle_start_authentication_core,
    handle_finish_authentication_core,
    handle_start_registration_core, 
    handle_finish_registration_core,
    prepare_oauth2_auth_request,
    is_authenticated_basic,
    get_user_from_session,
};

// Initialize the authentication system
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    init().await?;
    
    // Use authentication functions in your web framework handlers
    // See "Building Framework Integrations" section below for examples
    Ok(())
}

Configuration

Configure the library via environment variables:

# Required: Base URL of your application
ORIGIN=https://yourdomain.com

# Database configuration
GENERIC_DATA_STORE_TYPE=sqlite
GENERIC_DATA_STORE_URL=sqlite:data/auth.db

# Cache configuration  
GENERIC_CACHE_STORE_TYPE=redis
GENERIC_CACHE_STORE_URL=redis://localhost:6379

# OAuth2 providers
OAUTH2_GOOGLE_CLIENT_ID=your_google_client_id
OAUTH2_GOOGLE_CLIENT_SECRET=your_google_client_secret

# Optional: Server secret for token signing (32+ characters recommended)
AUTH_SERVER_SECRET=your_32_character_secret_key_here

# Optional: Session configuration
SESSION_COOKIE_NAME=__Host-SessionId
SESSION_COOKIE_MAX_AGE=600

Architecture

The library is organized into modular components that work together:

coordination - High-level authentication flow coordination functions
oauth2 - OAuth2 provider interactions and token handling
passkey - WebAuthn/FIDO2 passkey operations and verification
session - Session management, validation, and security
userdb - User account storage and management
storage - Database and cache abstractions with multiple backend support

Building Framework Integrations

To integrate with a web framework, implement HTTP handlers that call the coordination functions:

use oauth2_passkey::{prepare_oauth2_auth_request, get_user_and_csrf_token_from_session, AuthUser};
use http::{HeaderMap, StatusCode};

// Example: OAuth2 authentication endpoint
async fn handle_oauth2_auth(headers: HeaderMap) -> Result<String, StatusCode> {
    let (auth_url, response_headers) = prepare_oauth2_auth_request(headers, None)
        .await
        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;
    
    // Framework integration should:
    // 1. Set response_headers on the HTTP response
    // 2. Redirect to auth_url
    Ok(auth_url)
}

// Example: Extract user from session cookie
async fn get_session_user(session_cookie: &str) -> Result<AuthUser, StatusCode> {
    let (session_user, csrf_token) = get_user_and_csrf_token_from_session(session_cookie)
        .await
        .map_err(|_| StatusCode::UNAUTHORIZED)?;
    
    // Convert to framework-specific user type
    let mut auth_user = AuthUser::from(session_user);
    auth_user.csrf_token = csrf_token.as_str().to_string();
    Ok(auth_user)
}

Complete Example: See the oauth2-passkey-axum source code for a full framework integration implementation.

Security Features

Secure cookie implementation with Secure, HttpOnly, SameSite=Lax attributes and __Host- prefix
Constant-time CSRF comparison using subtle::ConstantTimeEq to prevent timing attacks
Cryptographically secure randomness via ring::rand::SystemRandom for session IDs and tokens
CSRF protection with secure token generation and validation
Session timeout management with configurable expiration
Host-locked cookies using __Host-SessionId prefix for enhanced security

Note: For a comprehensive security analysis and verification status of all claims, see Security Documentation.

Examples

Complete working examples are available in the repository:

Basic Integration - Simple authentication setup
OAuth2 Demo - Google OAuth2 integration
Passkey Demo - WebAuthn/passkey authentication

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

oauth2-passkey 0.1.0