authkestra-flow

High-level authentication flows for authkestra.

This crate orchestrates authentication flows such as OAuth2, Device Flow, Client Credentials, and direct credentials-based auth, providing a high-level API that is independent of web frameworks.

Features

OAuth2Flow: Orchestrates the Authorization Code flow (initiation and finalization).
DeviceFlow: Orchestrates the Device Authorization Flow (RFC 8628).
ClientCredentialsFlow: Orchestrates the Client Credentials Flow (RFC 6749 Section 4.4).
CredentialsFlow: Orchestrates direct credential-based authentication.
Support for UserMapper to integrate with local user databases.

Usage

Add this to your Cargo.toml:

[dependencies]
authkestra-flow = "0.1.2"

Relationship with `AuthkestraGuard`

authkestra-flow is responsible for the Login Flow (getting the user into the system). Once a user is logged in (e.g., a session is created), you use the AuthkestraGuard (from authkestra-guard) to protect your API routes.

Authkestra: Orchestrates providers, session stores, and token managers to handle login/logout.
AuthkestraGuard: Executes a chain of strategies (Session, Token, API Key) to authorize incoming requests.

Example: OAuth2 Flow

use authkestra_flow::OAuth2Flow;
use authkestra_providers_github::GitHubProvider;

// Setup provider and flow
let provider = GitHubProvider::new(client_id, client_secret, callback_url);
let flow = OAuth2Flow::new(provider);

// 1. Initiate login: Generate authorization URL and CSRF state
let (auth_url, csrf_state) = flow.initiate_login(&["user:email"], None);

// ... redirect user to auth_url, then receive code and state in callback ...

// 2. Finalize login: Exchange code for identity and tokens
let (identity, token, local_user) = flow.finalize_login(
    &code,
    &received_state,
    &expected_state,
    None // PKCE verifier
).await?;

Example: Device Flow

use authkestra_flow::DeviceFlow;

let flow = DeviceFlow::new(client_id, device_auth_url, token_url);

// 1. Initiate device authorization
let resp = flow.initiate_device_authorization(&["read", "write"]).await?;

println!("Go to {} and enter code: {}", resp.verification_uri, resp.user_code);

// 2. Poll for token
let token = flow.poll_for_token(&resp.device_code, resp.interval).await?;

Example: Client Credentials Flow

use authkestra_flow::ClientCredentialsFlow;

let flow = ClientCredentialsFlow::new(client_id, client_secret, token_url);

// Obtain an access token
let token = flow.get_token(Some(&["api:read"])).await?;

Example: Credentials Flow

use authkestra_flow::CredentialsFlow;
// Assuming a provider that implements CredentialsProvider
let flow = CredentialsFlow::new(my_credentials_provider);

let (identity, local_user) = flow.authenticate(my_credentials).await?;

Part of authkestra

This crate is part of the authkestra workspace.

authkestra-flow 0.1.2