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.6", 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:

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.6", 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.
• SD-JWT (Selective Disclosure): Issue a single JWT carrying selectively disclosable claims (draft-ietf-oauth-selective-disclosure-jwt); the holder decides, per presentation, which claims to reveal to each verifier.

📦 Workspace Crates

🛠️ 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::Authkestra;
use authkestra_engine::store::memory::MemoryStore;
use authkestra_engine::{OAuth2Flow, SessionStore};
use authkestra_providers::github::GithubProvider;
use std::sync::Arc;

// The builder ensures compile-time safety for your authentication stack
let github_provider = GithubProvider::new(client_id, client_secret, redirect_uri);
let session_store: Arc<dyn SessionStore> = Arc::new(MemoryStore::default());

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

Every runnable example lives in the facade crate, under crates/authkestra/examples/, so a single cargo run -p authkestra --example <name> covers both frameworks. Each example's own module docs list the environment variables it needs.

The Actix counterparts follow the same naming (actix_oauth2_github, actix_op_server, actix_devsig, …). Three protocol-level examples live in authkestra-engine instead, because they need no web framework at all:

• Client Credentials Flow: cargo run -p authkestra-engine --example client_credentials
• Device Flow: cargo run -p authkestra-engine --example device_flow
• SD-JWT (Selective Disclosure): cargo run -p authkestra-engine --example sd_jwt

🏗️ 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.