Split Authentication from User Detail Providing

Author: hannesdejager

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+### Upcoming release
+
+- **BREAKING**: Refactored `Authenticator` trait to be non-generic and return `Principal` instead of a generic `User` type. This decouples authentication (verifying credentials) from user detail retrieval (obtaining full user information).
+- Introduced `Principal` struct representing an authenticated user's identity (username). This is the minimal information returned by authentication.
+- Introduced `UserDetailProvider` trait to convert a `Principal` into a full `UserDetail` implementation. This allows authentication and user detail lookup to be separated.
+- Introduced `AuthenticationPipeline` struct that combines an `Authenticator` and a `UserDetailProvider` to provide a complete authentication flow.
+- Added `DefaultUserDetailProvider` implementation that returns `DefaultUser` for convenience.
+- **BREAKING**: Updated all `unftp-auth-*` crates (`unftp-auth-jsonfile`, `unftp-auth-pam`, `unftp-auth-rest`) to use the new non-generic `Authenticator` trait.
+- Updated all examples and tests to use the new authentication pattern.
+
 ### libunftp 0.22.0
 
 - Compile against Rust 1.92.0 in CI

crates/unftp-auth-jsonfile/src/lib.rs

@@ -150,7 +150,7 @@ use bytes::Bytes;
 use flate2::read::GzDecoder;
 use ipnet::Ipv4Net;
 use iprange::IpRange;
-use libunftp::auth::{AuthenticationError, Authenticator, DefaultUser};
+use libunftp::auth::{AuthenticationError, Authenticator, Principal};
 use ring::{
     digest::SHA256_OUTPUT_LEN,
     pbkdf2::{PBKDF2_HMAC_SHA256, verify},
@@ -343,17 +343,19 @@ impl JsonFileAuthenticator {
 }
 
 #[async_trait]
-impl Authenticator<DefaultUser> for JsonFileAuthenticator {
+impl Authenticator for JsonFileAuthenticator {
     #[tracing_attributes::instrument]
-    async fn authenticate(&self, username: &str, creds: &libunftp::auth::Credentials) -> Result<DefaultUser, AuthenticationError> {
+    async fn authenticate(&self, username: &str, creds: &libunftp::auth::Credentials) -> Result<Principal, AuthenticationError> {
         let res = if let Some(actual_creds) = self.credentials_map.get(username) {
             let client_cert = &actual_creds.client_cert;
             let certificate = &creds.certificate_chain.as_ref().and_then(|x| x.first());
 
             let ip_check_result = if !Self::ip_ok(creds, actual_creds) {
                 Err(AuthenticationError::IpDisallowed)
             } else {
-                Ok(DefaultUser {})
+                Ok(Principal {
+                    username: username.to_string(),
+                })
             };
 
             let cn_check_result = match (&client_cert, certificate) {
@@ -364,14 +366,18 @@ impl Authenticator<DefaultUser> for JsonFileAuthenticator {
                     (Some(cn), cert) => match cert.verify_cn(cn) {
                         Ok(is_authorized) => {
                             if is_authorized {
-                                Some(Ok(DefaultUser {}))
+                                Some(Ok(Principal {
+                                    username: username.to_string(),
+                                }))
                             } else {
                                 Some(Err(AuthenticationError::CnDisallowed))
                             }
                         }
                         Err(e) => Some(Err(AuthenticationError::with_source("verify_cn", e))),
                     },
-                    (None, _) => Some(Ok(DefaultUser {})),
+                    (None, _) => Some(Ok(Principal {
+                        username: username.to_string(),
+                    })),
                 },
                 (Some(_), None) => Some(Err(AuthenticationError::CnDisallowed)),
                 _ => None,
@@ -380,7 +386,9 @@ impl Authenticator<DefaultUser> for JsonFileAuthenticator {
             let pass_check_result = match &creds.password {
                 Some(given_password) => {
                     if Self::check_password(given_password, &actual_creds.password).is_ok() {
-                        Some(Ok(DefaultUser {}))
+                        Some(Ok(Principal {
+                            username: username.to_string(),
+                        }))
                     } else {
                         Some(Err(AuthenticationError::BadPassword))
                     }
@@ -484,18 +492,23 @@ mod test {
             json_authenticator
                 .authenticate("alice", &"this is the correct password for alice".into())
                 .await
-                .unwrap(),
-            DefaultUser
+                .unwrap()
+                .username,
+            "alice"
         );
         assert_eq!(
             json_authenticator
                 .authenticate("bella", &"this is the correct password for bella".into())
                 .await
-                .unwrap(),
-            DefaultUser
+                .unwrap()
+                .username,
+            "bella"
         );
-        assert_eq!(json_authenticator.authenticate("carol", &"not so secure".into()).await.unwrap(), DefaultUser);
-        assert_eq!(json_authenticator.authenticate("dan", &"".into()).await.unwrap(), DefaultUser);
+        assert_eq!(
+            json_authenticator.authenticate("carol", &"not so secure".into()).await.unwrap().username,
+            "carol"
+        );
+        assert_eq!(json_authenticator.authenticate("dan", &"".into()).await.unwrap().username, "dan");
         assert!(matches!(
             json_authenticator.authenticate("carol", &"this is the wrong password".into()).await,
             Err(AuthenticationError::BadPassword)
@@ -520,8 +533,9 @@ mod test {
                     },
                 )
                 .await
-                .unwrap(),
-            DefaultUser
+                .unwrap()
+                .username,
+            "dan"
         );
 
         match json_authenticator
@@ -679,8 +693,9 @@ mod test {
                     },
                 )
                 .await
-                .unwrap(),
-            DefaultUser
+                .unwrap()
+                .username,
+            "alice"
         );
 
         // correct password but missing certificate fails
@@ -711,8 +726,9 @@ mod test {
                     },
                 )
                 .await
-                .unwrap(),
-            DefaultUser
+                .unwrap()
+                .username,
+            "bob"
         );
 
         // certificate with incorrect CN and no password needed according to json file fails to authenticate
@@ -743,8 +759,9 @@ mod test {
                     },
                 )
                 .await
-                .unwrap(),
-            DefaultUser
+                .unwrap()
+                .username,
+            "dean"
         );
     }
 }

crates/unftp-auth-jsonfile/tests/main.rs

@@ -1,6 +1,6 @@
 #![allow(missing_docs)]
 
-use libunftp::auth::{Authenticator, DefaultUser};
+use libunftp::auth::Authenticator;
 use std::path::PathBuf;
 use unftp_auth_jsonfile::JsonFileAuthenticator;
 
@@ -17,21 +17,21 @@ async fn credentials_from_file_type_plain() {
     let path = input_file_path("cred.json".to_string());
 
     let json_auther = JsonFileAuthenticator::from_file(path).unwrap();
-    assert_eq!(json_auther.authenticate("testuser", &"testpassword".into()).await.unwrap(), DefaultUser);
+    assert_eq!(json_auther.authenticate("testuser", &"testpassword".into()).await.unwrap().username, "testuser");
 }
 
 #[tokio::test(flavor = "current_thread")]
 async fn credentials_from_file_type_gzipped() {
     let path = input_file_path("cred.json.gz".to_string());
 
     let json_auther = JsonFileAuthenticator::from_file(path).unwrap();
-    assert_eq!(json_auther.authenticate("testuser", &"testpassword".into()).await.unwrap(), DefaultUser);
+    assert_eq!(json_auther.authenticate("testuser", &"testpassword".into()).await.unwrap().username, "testuser");
 }
 
 #[tokio::test(flavor = "current_thread")]
 async fn credentials_from_file_type_gzipped_base64() {
     let path = input_file_path("cred.json.gz.b64".to_string());
 
     let json_auther = JsonFileAuthenticator::from_file(path).unwrap();
-    assert_eq!(json_auther.authenticate("testuser", &"testpassword".into()).await.unwrap(), DefaultUser);
+    assert_eq!(json_auther.authenticate("testuser", &"testpassword".into()).await.unwrap().username, "testuser");
 }

crates/unftp-auth-pam/src/lib.rs

@@ -6,7 +6,7 @@
 //! [`PAM`]: https://en.wikipedia.org/wiki/Pluggable_authentication_module
 
 use async_trait::async_trait;
-use libunftp::auth::*;
+use libunftp::auth::{AuthenticationError, Authenticator, Credentials, Principal};
 
 /// [`Authenticator`] implementation that authenticates against [`PAM`].
 ///
@@ -26,10 +26,10 @@ impl PamAuthenticator {
 }
 
 #[async_trait]
-impl Authenticator<DefaultUser> for PamAuthenticator {
+impl Authenticator for PamAuthenticator {
     #[allow(clippy::type_complexity)]
     #[tracing_attributes::instrument]
-    async fn authenticate(&self, username: &str, creds: &Credentials) -> Result<DefaultUser, AuthenticationError> {
+    async fn authenticate(&self, username: &str, creds: &Credentials) -> Result<Principal, AuthenticationError> {
         let username = username.to_string();
         let password = creds.password.as_ref().ok_or(AuthenticationError::BadPassword)?;
         let service = self.service.clone();
@@ -38,6 +38,6 @@ impl Authenticator<DefaultUser> for PamAuthenticator {
 
         auth.get_handler().set_credentials(&username, password);
         auth.authenticate().map_err(|e| AuthenticationError::with_source("pam error", e))?;
-        Ok(DefaultUser {})
+        Ok(Principal { username })
     }
 }

crates/unftp-auth-rest/src/lib.rs

@@ -7,7 +7,7 @@ use http_body_util::BodyExt;
 use hyper::{Method, Request, http::uri::InvalidUri};
 use hyper_util::client::legacy::Client;
 use hyper_util::rt::TokioExecutor;
-use libunftp::auth::{AuthenticationError, Authenticator, Credentials, DefaultUser};
+use libunftp::auth::{AuthenticationError, Authenticator, Credentials, Principal};
 use percent_encoding::{NON_ALPHANUMERIC, utf8_percent_encode};
 use regex::Regex;
 use serde_json::{Value, json};
@@ -222,9 +222,9 @@ impl TrimQuotes for String {
 }
 
 #[async_trait]
-impl Authenticator<DefaultUser> for RestAuthenticator {
+impl Authenticator for RestAuthenticator {
     #[tracing_attributes::instrument]
-    async fn authenticate(&self, username: &str, creds: &Credentials) -> Result<DefaultUser, AuthenticationError> {
+    async fn authenticate(&self, username: &str, creds: &Credentials) -> Result<Principal, AuthenticationError> {
         let username_url = utf8_percent_encode(username, NON_ALPHANUMERIC).collect::<String>();
         let password = creds.password.as_ref().ok_or(AuthenticationError::BadPassword)?.as_ref();
         let password_url = utf8_percent_encode(password, NON_ALPHANUMERIC).collect::<String>();
@@ -284,7 +284,9 @@ impl Authenticator<DefaultUser> for RestAuthenticator {
         };
 
         if self.regex.is_match(&parsed) {
-            Ok(DefaultUser {})
+            Ok(Principal {
+                username: username.to_string(),
+            })
         } else {
             Err(AuthenticationError::BadPassword)
         }

crates/unftp-sbe-fs/examples/cap-ftpd-worker.rs

@@ -23,7 +23,7 @@ mod auth {
     };
 
     use async_trait::async_trait;
-    use libunftp::auth::{AuthenticationError, Authenticator, DefaultUser, UserDetail};
+    use libunftp::auth::{AuthenticationError, Authenticator, Principal, UserDetail, UserDetailError, UserDetailProvider};
     use serde::Deserialize;
     use tokio::time::sleep;
 
@@ -114,14 +114,14 @@ mod auth {
     }
 
     #[async_trait]
-    impl Authenticator<User> for JsonFileAuthenticator {
+    impl Authenticator for JsonFileAuthenticator {
         #[tracing_attributes::instrument]
-        async fn authenticate(&self, username: &str, creds: &libunftp::auth::Credentials) -> Result<User, AuthenticationError> {
+        async fn authenticate(&self, username: &str, creds: &libunftp::auth::Credentials) -> Result<Principal, AuthenticationError> {
             let res = if let Some(actual_creds) = self.credentials_map.get(username) {
                 let pass_check_result = match &creds.password {
                     Some(given_password) => {
                         if Self::check_password(given_password, &actual_creds.password).is_ok() {
-                            Some(Ok(User::new(username, &actual_creds.home)))
+                            Some(Ok(()))
                         } else {
                             Some(Err(AuthenticationError::BadPassword))
                         }
@@ -133,9 +133,11 @@ mod auth {
                     None => Err(AuthenticationError::BadPassword),
                     Some(pass_res) => {
                         if pass_res.is_ok() {
-                            Ok(User::new(username, &actual_creds.home))
+                            Ok(Principal {
+                                username: username.to_string(),
+                            })
                         } else {
-                            pass_res
+                            Err(AuthenticationError::BadPassword)
                         }
                     }
                 }
@@ -156,11 +158,17 @@ mod auth {
     }
 
     #[async_trait]
-    impl Authenticator<DefaultUser> for JsonFileAuthenticator {
-        #[tracing_attributes::instrument]
-        async fn authenticate(&self, username: &str, creds: &libunftp::auth::Credentials) -> Result<DefaultUser, AuthenticationError> {
-            let _: User = self.authenticate(username, creds).await?;
-            Ok(DefaultUser {})
+    impl UserDetailProvider for JsonFileAuthenticator {
+        type User = User;
+
+        async fn provide_user_detail(&self, principal: &Principal) -> Result<User, UserDetailError> {
+            if let Some(creds) = self.credentials_map.get(&principal.username) {
+                Ok(User::new(&principal.username, &creds.home))
+            } else {
+                Err(UserDetailError::UserNotFound {
+                    username: principal.username.clone(),
+                })
+            }
         }
     }
 }
@@ -234,13 +242,14 @@ async fn main() {
 
     let control_sock = TcpStream::from_std(std_stream).unwrap();
 
-    let auth = Arc::new(JsonFileAuthenticator::from_file(args[1].clone()).unwrap());
+    let authenticator = Arc::new(JsonFileAuthenticator::from_file(args[1].clone()).unwrap());
+    let user_provider = authenticator.clone();
     // XXX This would be a lot easier if the libunftp API allowed creating the
     // storage just before calling service.
     let storage = Mutex::new(Some(Filesystem::new(std::env::temp_dir()).unwrap()));
     let sgen = Box::new(move || storage.lock().unwrap().take().unwrap());
 
-    let mut sb = libunftp::ServerBuilder::with_authenticator(sgen, auth);
+    let mut sb = libunftp::ServerBuilder::with_authenticator(sgen, authenticator).user_detail_provider(user_provider);
     cfg_if! {
         if #[cfg(target_os = "freebsd")] {
             // Safe because we're single-threaded

crates/unftp-sbe-gcs/src/lib.rs

@@ -37,13 +37,14 @@
 //! constructors of `Server` e.g.
 //!
 //! ```no_run
-//! use libunftp::Server;
+//! use libunftp::ServerBuilder;
 //! use unftp_sbe_gcs::{CloudStorage, options::AuthMethod};
 //! use std::path::PathBuf;
+//! use std::sync::Arc;
 //!
 //! #[tokio::main]
 //! pub async fn main() {
-//!     let server = libunftp::Server::new(
+//!     let server = libunftp::ServerBuilder::new(
 //!         Box::new(move || CloudStorage::with_bucket_root("my-bucket", PathBuf::from("/ftp-root"), AuthMethod::WorkloadIdentity(None)))
 //!       )
 //!       .greeting("Welcome to my FTP server")

src/auth/anonymous.rs

@@ -11,22 +11,24 @@ use async_trait::async_trait;
 /// ```rust
 /// # #[tokio::main]
 /// # async fn main() {
-/// use libunftp::auth::{Authenticator, AnonymousAuthenticator, DefaultUser};
+/// use libunftp::auth::{Authenticator, AnonymousAuthenticator, Principal};
 ///
 /// let my_auth = AnonymousAuthenticator{};
-/// assert_eq!(my_auth.authenticate("Finn", &"I ❤️ PB".into()).await.unwrap(), DefaultUser{});
+/// assert_eq!(my_auth.authenticate("Finn", &"I ❤️ PB".into()).await.unwrap().username, "Finn");
 /// # }
 /// ```
 ///
 #[derive(Debug)]
 pub struct AnonymousAuthenticator;
 
 #[async_trait]
-impl Authenticator<DefaultUser> for AnonymousAuthenticator {
+impl Authenticator for AnonymousAuthenticator {
     #[allow(clippy::type_complexity)]
     #[tracing_attributes::instrument]
-    async fn authenticate(&self, _username: &str, _password: &Credentials) -> Result<DefaultUser, AuthenticationError> {
-        Ok(DefaultUser {})
+    async fn authenticate(&self, username: &str, _password: &Credentials) -> Result<Principal, AuthenticationError> {
+        Ok(Principal {
+            username: username.to_string(),
+        })
     }
 
     async fn cert_auth_sufficient(&self, _username: &str) -> bool {