axum_authentik_auth/
lib.rs

1//! # axum-authentik-auth
2//!
3//! An [axum](https://crates.io/crates/axum) extractor and middleware for
4//! [authentik](https://goauthentik.io/) Proxy Provider forward authentication.
5//!
6//! ## Overview
7//!
8//! When using authentik's Proxy Provider with forward auth (single application),
9//! authentik sits in front of your application via a reverse proxy (like Nginx).
10//! After authenticating the user, it forwards user identity information through
11//! HTTP headers such as:
12//!
13//! - `X-authentik-username`
14//! - `X-authentik-email`
15//! - `X-authentik-name`
16//! - `X-authentik-uid`
17//! - `X-authentik-groups`
18//!
19//! This crate parses those headers into a typed [`AuthentikUser`] struct and
20//! provides ergonomic extractors for axum handlers.
21//!
22//! ## Quick Start
23//!
24//! ```ignore
25//! use axum::{routing::get, Router, Json};
26//! use axum_authentik_auth::AuthentikUser;
27//!
28//! async fn me(user: AuthentikUser) -> Json<AuthentikUser> {
29//!     Json(user)
30//! }
31//!
32//! #[tokio::main]
33//! async fn main() {
34//!     let app = Router::new()
35//!         .route("/api/me", get(me));
36//!
37//!     let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
38//!         .await
39//!         .unwrap();
40//!     axum::serve(listener, app).await.unwrap();
41//! }
42//! ```
43//!
44//! ## Extractor variants
45//!
46//! - `AuthentikUser` — requires authentication, returns 401 if missing
47//! - `Option<AuthentikUser>` — optional authentication, returns `None` if missing
48//! - [`require_group`] / [`require_all_groups`] / [`require_any_group`] — handler wrappers for group-based access control
49//!
50//! ## Custom header prefix
51//!
52//! If your reverse proxy uses a different header prefix, use the tower layer
53//! (requires `layer` feature):
54//!
55//! ```ignore
56//! use axum_authentik_auth::layer::{AuthentikLayer, AuthentikConfig};
57//!
58//! let app = Router::new()
59//!     .route("/api/me", get(me))
60//!     .layer(AuthentikLayer::with_config(
61//!         AuthentikConfig {
62//!             header_prefix: "x-myproxy".to_string(),
63//!             require_auth: true,
64//!         }
65//!     ));
66//! ```
67//!
68//! ## Feature flags
69//!
70//! - `layer`: Enables the tower [`Layer`](tower::Layer) / middleware for custom header prefix injection.
71
72#![forbid(unsafe_code)]
73#![deny(missing_docs)]
74
75mod error;
76mod extractor;
77mod user;
78
79#[cfg(feature = "layer")]
80/// Tower middleware and configuration for custom authentik header prefixes.
81///
82/// Enabled by the `layer` feature flag. When the authentik reverse proxy uses
83/// a header prefix other than the default `x-authentik`, inject the custom
84/// prefix via [`AuthentikLayer`] into each request's extensions.
85pub mod layer;
86
87/// Permission guards for group-based access control.
88///
89/// Provides handler wrappers ([`require_group`], [`require_all_groups`],
90/// [`require_any_group`]) that enforce group membership before the wrapped
91/// handler executes. The extractor [`RequireGroup`] wraps [`AuthentikUser`]
92/// and implements `Deref` for transparent access.
93pub mod guard;
94
95// Re-export the primary types for convenience
96pub use error::AuthentikError;
97pub use guard::{GroupGuard, RequireGroup, require_all_groups, require_any_group, require_group};
98pub use user::AuthentikUser;
axum_authentik_auth/lib.rs

axum_authentik_auth/
lib.rs
