Quickstart

This guide will walk you through the fastest way to get a working GitHub OAuth2 login flow using Authkestra. We provide unified integrations for both Axum and Actix-web.

Prerequisites

Add the authkestra facade crate to your Cargo.toml. The facade re-exports all sub-crates behind feature flags, allowing you to easily opt-in to the framework and identity providers you need.

Axum

[dependencies]
authkestra = { version = "0.9", features = ["axum", "session", "github"] }
authkestra-engine = { version = "0.9", features = ["session", "memory"] }
tower-cookies = "0.11"
tokio = { version = "1", features = ["full"] }

Actix-web

[dependencies]
authkestra = { version = "0.9", features = ["actix", "session", "github"] }
authkestra-engine = { version = "0.9", features = ["session", "memory"] }
actix-web = "4"

Setting Up the Engine

The core logic of Authkestra is identical regardless of which web framework you choose. First, initialize the Identity Provider (GithubProvider), wrap it in an OAuth2Flow, and construct the Engine using the Typestate Builder Pattern (Authkestra::builder()).

use authkestra::Authkestra;
use authkestra::providers::github::GithubProvider;
use authkestra_engine::store::memory::MemoryStore;
use authkestra_engine::{OAuth2Flow, SessionStore};
use std::sync::Arc;

// 1. Initialize the GitHub Provider
let github_provider = GithubProvider::new(
    "YOUR_CLIENT_ID".to_string(),
    "YOUR_CLIENT_SECRET".to_string(),
    "http://localhost:3000/auth/callback/github".to_string()
);

// 2. Setup the Session Store
let session_store: Arc<dyn SessionStore> = Arc::new(MemoryStore::default());

// 3. Build the Authkestra Engine
let auth_engine = Authkestra::builder()
    // `.provider()` takes a `Flow`, not a bare provider — wrap it in `OAuth2Flow`.
    .provider(OAuth2Flow::new(github_provider))
    .session_store(session_store)
    .build();

Note

.session_store() expects an Arc<dyn SessionStore>. The explicit type annotation above is what coerces the concrete MemoryStore into that trait object; without it the call will not resolve.

Wiring the Router

Once the engine is built, integrate it into your web framework’s routing layer. Authkestra provides specialized adapters (authkestra-axum and authkestra-actix) that automatically map standard authentication endpoints.

Axum

use authkestra::axum::{AxumExt, AxumState};
use authkestra::core::AkWebAppEngine;
use authkestra::providers::github::GithubProvider;
use authkestra::Authkestra;
use authkestra_engine::store::memory::MemoryStore;
use authkestra_engine::{OAuth2Flow, SessionStore};
use axum::Router;
use std::sync::Arc;
use tower_cookies::CookieManagerLayer;

#[derive(Clone, AxumState)]
struct AppState {
    #[authkestra(engine)]
    auth: AkWebAppEngine,
}

#[tokio::main]
async fn main() {
    let session_store: Arc<dyn SessionStore> = Arc::new(MemoryStore::default());

    let auth_engine = Authkestra::builder()
        .provider(OAuth2Flow::new(GithubProvider::new(
            "YOUR_CLIENT_ID".to_string(),
            "YOUR_CLIENT_SECRET".to_string(),
            "http://localhost:3000/auth/callback/github".to_string(),
        )))
        .session_store(session_store)
        .build();

    let state = AppState { auth: auth_engine.clone() };

    let app = Router::new()
        // `axum_router()` wires `/auth/login/{provider}`, `/auth/callback/{provider}`
        // and `/auth/logout`.
        .merge(auth_engine.axum_router())
        .layer(CookieManagerLayer::new())
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

The full version of this example is runnable from the repository:

cargo run -p authkestra --example axum_oauth2_github --all-features

Actix-web

use actix_web::{web, App, HttpServer};
use authkestra::actix::{ActixExt, ActixState};
use authkestra::core::AkWebAppEngine;
use authkestra::providers::github::GithubProvider;
use authkestra::Authkestra;
use authkestra_engine::store::memory::MemoryStore;
use authkestra_engine::{OAuth2Flow, SessionStore};
use std::sync::Arc;

#[derive(Clone, ActixState)]
struct AppState {
    #[authkestra(engine)]
    auth: AkWebAppEngine,
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    let session_store: Arc<dyn SessionStore> = Arc::new(MemoryStore::default());

    let auth_engine = Authkestra::builder()
        .provider(OAuth2Flow::new(GithubProvider::new(
            "YOUR_CLIENT_ID".to_string(),
            "YOUR_CLIENT_SECRET".to_string(),
            "http://localhost:3000/auth/callback/github".to_string(),
        )))
        .session_store(session_store)
        .build();

    let state = AppState { auth: auth_engine };

    HttpServer::new(move || {
        let app_state = state.clone();
        let config_state = app_state.clone();
        App::new()
            // `configure_authkestra` (from `ActixState`) registers the session store
            // and config as app data so the extractors can find them.
            .configure(move |cfg| config_state.configure_authkestra(cfg))
            // `actix_scope()` mounts `/auth/login/{provider}`,
            // `/auth/callback/{provider}` and `/auth/logout`.
            .service(app_state.auth.actix_scope())
    })
    .bind("0.0.0.0:3000")?
    .run()
    .await
}

The full version of this example is runnable from the repository:

cargo run -p authkestra --example actix_oauth2_github --all-features

With just these few lines of code, your application is now fully equipped to handle OAuth logins, validate responses, and issue secure sessions!