Authkestra

authkestra is a modular, framework-agnostic authentication orchestration system designed to be idiomatic to Rust, emphasizing explicit control flow, strong typing, and composability over dynamic middleware strategies common in other ecosystems.

📦 Getting Started

The easiest way to use Authkestra is via the authkestra facade crate. It re-exports all sub-crates behind feature flags, allowing you to manage your authentication stack from a single dependency.

Add this to your Cargo.toml:

[dependencies]
# Use the facade with the features you need
authkestra = { version = "0.3", features = ["axum", "github"] }

For advanced users, individual crates are still available and can be used independently if preferred.

🔐 TLS backend

Authkestra talks to identity providers over HTTPS, so it needs a TLS backend. It is selected by a feature flag rather than by reqwest's defaults, so you can choose the crypto provider yourself:

Feature	Backend	Notes
rustls-aws-lc-rs	rustls + aws-lc-rs	Default. Compiles C and assembly, so it needs a C toolchain.
rustls-no-provider	rustls, provider chosen by you	Pure-Rust builds (ring), *-unknown-linux-musl, cargo-deny policies that ban aws-lc-rs.

The default keeps the historical behaviour, so no change is needed unless you want to get off aws-lc-rs. To do that, turn the default off and install a provider yourself:

[dependencies]
authkestra = { version = "0.3", default-features = false, features = ["axum", "github", "rustls-no-provider"] }
rustls = { version = "0.23", default-features = false, features = ["ring", "std", "tls12", "logging"] }

// Must run before any Authkestra call that builds an HTTP client,
// otherwise reqwest panics at client construction.
rustls::crypto::ring::default_provider()
    .install_default()
    .expect("failed to install rustls crypto provider");

Every Authkestra crate that speaks HTTPS exposes the same two features and forwards them to authkestra-engine. Cargo features are additive, so if any crate in your graph still enables rustls-aws-lc-rs, aws-lc-rs comes back — check with cargo tree -i aws-lc-rs -e features.

🚀 Features

• Modular & Unified Core: Following our RFC-001 architecture, core concerns are unified in authkestra-engine while adapters like authkestra-axum and authkestra-actix provide seamless framework integrations.
• Stateless OAuth: OAuth state and nonce are stored securely in encrypted cookies—never in your database—keeping your architecture clean and horizontally scalable.
• Performant OIDC Discovery: OIDC discovery documents are cached via background tokio::spawn tasks, completely eliminating per-request latency for fetching keys.
• Database Agnostic: Authkestra never enforces schemas. All data access is strictly defined via traits (e.g., UserStore, SessionStore), allowing you to use any database or ORM.
• Flexible Chaining: Chain multiple authentication strategies (Token, Session, Basic, Custom) seamlessly.
• OpenID Connect Provider (OP): Build your own identity provider and authorization server using authkestra-op.
• Session Management: Built-in support for in-memory, Redis, and SQL via sqlx.

📦 Workspace Crates

Crate	Description
authkestra	Primary Facade: Re-exports all other crates behind features.
authkestra-engine	Foundational types, traits and the Engine orchestrator.
authkestra-resource	Resource server enforcement and validation (JWT, etc).
authkestra-providers	Concrete implementation for OAuth providers (GitHub, Google, Discord).
authkestra-axum	Axum-specific integration, including AuthSession extractors.
authkestra-actix	Actix-specific integration, including State macro support.
authkestra-oidc	OpenID Connect discovery and provider support.
authkestra-op	OpenID Connect Provider (OP) implementation.
authkestra-devsig	Device-bound signature authentication (proof-of-possession + Issuer attestation).
authkestra-macros	Procedural macros for simplifying Authkestra integration.

🛠️ Usage

Authkestra utilizes a powerful Typestate Builder Pattern (Engine::builder()). This enforces at compile-time that certain methods are only available if their prerequisites are met (e.g., you can only call session methods if a SessionStore was provided).

Quick Start Example

use authkestra::flow::{Engine, OAuth2Flow};
use authkestra_providers::github::GithubProvider;

// The builder ensures compile-time safety for your authentication stack
let github_provider = GithubProvider::new(client_id, client_secret, redirect_uri);

let auth_engine = Engine::builder()
    .provider(OAuth2Flow::new(github_provider))
    .session_store(session_store)
    .build();

To see complete, runnable examples for various frameworks and flows, check out the examples directory inside each crate:

• Axum Basic Setup: cargo run -p authkestra-axum --example basic_setup
• Actix Basic Setup: cargo run -p authkestra-actix --example basic_setup
• Axum with GitHub OAuth: cargo run -p authkestra-axum --example oauth2_github
• Axum with Google OIDC: cargo run -p authkestra-axum --example oidc_google
• Axum with Redis Session: cargo run -p authkestra-axum --example session_redis
• Axum with SQL Store: cargo run -p authkestra-axum --example sql_store
• Client Credentials Flow: cargo run -p authkestra-engine --example client_credentials
• Device Flow: cargo run -p authkestra-engine --example device_flow
• Axum Resource Server: cargo run -p authkestra-axum --example resource_server
• Axum OP Server: cargo run -p authkestra-axum --example op_server
• Axum MFA Server (TOTP + WebAuthn): cargo run -p authkestra-axum --example mfa_server

🏗️ Technical Design Principles

Our architecture enforces strict design principles to guarantee compile-time safety and optimal Developer Experience (DX):

• Typestate Builder Pattern: The Engine::builder() uses Rust's typestate pattern. This makes misconfigurations a compile-time error rather than a runtime surprise.
• Trait Objects over Generics: For I/O bound paths, we prefer Box<dyn Trait> (e.g., Box<dyn AuthMethod>) over heavy monomorphized generics. This drastically optimizes compilation times without sacrificing meaningful runtime performance.
• Framework Agnostic Core: The authkestra-engine is pure Rust logic. Axum and Actix integrations are entirely isolated in separate adapter crates, utilizing explicit Extractors like AuthSession(session).
• Plugin Interfaces: We extend functionality via strict plugin interfaces (AuthMethod, Flow) rather than opaque, ordering-dependent middleware.
• Production-Ready Tracing: Every handler, endpoint, and logical branch is deeply instrumented with the tracing crate, ensuring request flows and errors are fully visible in production without code changes.

📜 License

This project is dual-licensed under either:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.