feat: [#727] allow to authenticate API via authentication header

The API allos client authentication via a `token` parameter in the URL
query:

```console
curl http://0.0.0.0:1212/api/v1/stats?token=MyAccessToken | jq
```

Now it's also possible to do it via Authentication Header:

```console
curl -H "Authorization: Bearer MyAccessToken" http://0.0.0.0:1212/api/v1/stats | jq
```

This is to avoid leaking the token in logs, proxies, etc.

For now, it's only optional and recommendable. It could be mandatory in
future major API versions.

Author: josecelano

packages/axum-rest-tracker-api-server/src/v1/middlewares/auth.rs

@@ -1,7 +1,20 @@
 //! Authentication middleware for the API.
 //!
-//! It uses a "token" GET param to authenticate the user. URLs must be of the
-//! form:
+//! It uses a "token" to authenticate the user. The token must be one of the
+//! `access_tokens` in the tracker [HTTP API configuration](torrust_tracker_configuration::HttpApi).
+//!
+//! There are two ways to provide the token:
+//!
+//! 1. As a `Bearer` token in the `Authorization` header.
+//! 2. As a `token` GET param in the URL.
+//!
+//! Using the `Authorization` header:
+//!
+//! ```console
+//! curl -H "Authorization: Bearer MyAccessToken" http://<host>:<port>/api/v1/<context>
+//! ```
+//!
+//! Using the `token` GET param:
 //!
 //! `http://<host>:<port>/api/v1/<context>?token=<token>`.
 //!
@@ -21,6 +34,12 @@
 //! All the tokes have the same permissions, so it is not possible to have
 //! different permissions for different tokens. The label is only used to
 //! identify the token.
+//!
+//! NOTICE: The token is not encrypted, so it is recommended to use HTTPS to
+//! protect the token from being intercepted.
+//!
+//! NOTICE: If both the `Authorization` header and the `token` GET param are
+//! provided, the `Authorization` header will be used.
 use std::sync::Arc;
 
 use axum::extract::{self};
@@ -43,16 +62,26 @@ pub struct State {
     pub access_tokens: Arc<AccessTokens>,
 }
 
-/// Middleware for authentication using a "token" GET param.
+/// Middleware for authentication.
+///
 /// The token must be one of the tokens in the tracker [HTTP API configuration](torrust_tracker_configuration::HttpApi).
 pub async fn auth(
     extract::State(state): extract::State<State>,
     extract::Query(params): extract::Query<QueryParams>,
     request: Request<axum::body::Body>,
     next: Next,
 ) -> Response {
-    let Some(token) = params.token else {
-        return AuthError::Unauthorized.into_response();
+    let token_from_header = extract_token_from_header(&request);
+
+    let token_from_get_param = params.token.clone();
+
+    let provided_tokens = (token_from_header, token_from_get_param);
+
+    let token = match provided_tokens {
+        (Some(token_from_header), Some(_token_from_get_param)) => token_from_header,
+        (Some(token_from_header), None) => token_from_header,
+        (None, Some(token_from_get_param)) => token_from_get_param,
+        (None, None) => return AuthError::Unauthorized.into_response(),
     };
 
     if !authenticate(&token, &state.access_tokens) {
@@ -62,9 +91,21 @@ pub async fn auth(
     next.run(request).await
 }
 
+fn extract_token_from_header(request: &Request<axum::body::Body>) -> Option<String> {
+    let headers = request.headers();
+    headers
+        .get(axum::http::header::AUTHORIZATION)
+        .and_then(|header_value| header_value.to_str().ok())
+        .and_then(|header_str| {
+            // Check if the header starts with "Bearer " and extract the token
+            header_str.strip_prefix("Bearer ").map(std::string::ToString::to_string)
+        })
+}
+
 enum AuthError {
     /// Missing token for authentication.
     Unauthorized,
+
     /// Token was provided but it is not valid.
     TokenNotValid,
 }

packages/axum-rest-tracker-api-server/tests/server/v1/contract/authentication.rs

@@ -1,130 +1,169 @@
-use torrust_axum_rest_tracker_api_server::environment::Started;
-use torrust_rest_tracker_api_client::common::http::{Query, QueryParam};
-use torrust_rest_tracker_api_client::v1::client::{headers_with_request_id, Client};
-use torrust_tracker_test_helpers::logging::logs_contains_a_line_with;
-use torrust_tracker_test_helpers::{configuration, logging};
-use uuid::Uuid;
+mod given_that_the_token_is_only_provided_in_the_authentication_header {
+    use torrust_axum_rest_tracker_api_server::environment::Started;
+    use torrust_rest_tracker_api_client::common::http::Query;
+    use torrust_rest_tracker_api_client::v1::client::{headers_with_auth_token, Client};
+    use torrust_tracker_test_helpers::{configuration, logging};
 
-use crate::server::v1::asserts::{assert_token_not_valid, assert_unauthorized};
+    #[tokio::test]
+    async fn it_should_authenticate_requests_when_the_token_is_provided_in_the_authentication_header() {
+        logging::setup();
 
-#[tokio::test]
-async fn should_authenticate_requests_by_using_a_token_query_param() {
-    logging::setup();
+        let env = Started::new(&configuration::ephemeral().into()).await;
 
-    let env = Started::new(&configuration::ephemeral().into()).await;
+        let token = env.get_connection_info().api_token.unwrap();
 
-    let token = env.get_connection_info().api_token.unwrap();
+        let response = Client::new(env.get_connection_info())
+            .unwrap()
+            .get_request_with_query("stats", Query::default(), Some(headers_with_auth_token(&token)))
+            .await;
 
-    let response = Client::new(env.get_connection_info())
-        .unwrap()
-        .get_request_with_query("stats", Query::params([QueryParam::new("token", &token)].to_vec()), None)
-        .await;
+        assert_eq!(response.status(), 200);
 
-    assert_eq!(response.status(), 200);
-
-    env.stop().await;
+        env.stop().await;
+    }
 }
+mod given_that_the_token_is_only_provided_in_the_query_param {
 
-#[tokio::test]
-async fn should_not_authenticate_requests_when_the_token_is_missing() {
-    logging::setup();
+    use torrust_axum_rest_tracker_api_server::environment::Started;
+    use torrust_rest_tracker_api_client::common::http::{Query, QueryParam};
+    use torrust_rest_tracker_api_client::v1::client::{headers_with_request_id, Client};
+    use torrust_tracker_test_helpers::logging::logs_contains_a_line_with;
+    use torrust_tracker_test_helpers::{configuration, logging};
+    use uuid::Uuid;
 
-    let env = Started::new(&configuration::ephemeral().into()).await;
+    use crate::server::v1::asserts::assert_token_not_valid;
 
-    let request_id = Uuid::new_v4();
+    #[tokio::test]
+    async fn it_should_authenticate_requests_when_the_token_is_provided_as_a_query_param() {
+        logging::setup();
 
-    let response = Client::new(env.get_connection_info())
-        .unwrap()
-        .get_request_with_query("stats", Query::default(), Some(headers_with_request_id(request_id)))
-        .await;
+        let env = Started::new(&configuration::ephemeral().into()).await;
 
-    assert_unauthorized(response).await;
+        let token = env.get_connection_info().api_token.unwrap();
 
-    assert!(
-        logs_contains_a_line_with(&["ERROR", "API", &format!("{request_id}")]),
-        "Expected logs to contain: ERROR ... API ... request_id={request_id}"
-    );
+        let response = Client::new(env.get_connection_info())
+            .unwrap()
+            .get_request_with_query("stats", Query::params([QueryParam::new("token", &token)].to_vec()), None)
+            .await;
 
-    env.stop().await;
-}
+        assert_eq!(response.status(), 200);
 
-#[tokio::test]
-async fn should_not_authenticate_requests_when_the_token_is_empty() {
-    logging::setup();
+        env.stop().await;
+    }
 
-    let env = Started::new(&configuration::ephemeral().into()).await;
+    #[tokio::test]
+    async fn it_should_not_authenticate_requests_when_the_token_is_empty() {
+        logging::setup();
 
-    let request_id = Uuid::new_v4();
+        let env = Started::new(&configuration::ephemeral().into()).await;
 
-    let response = Client::new(env.get_connection_info())
-        .unwrap()
-        .get_request_with_query(
-            "stats",
-            Query::params([QueryParam::new("token", "")].to_vec()),
-            Some(headers_with_request_id(request_id)),
-        )
-        .await;
+        let request_id = Uuid::new_v4();
 
-    assert_token_not_valid(response).await;
+        let response = Client::new(env.get_connection_info())
+            .unwrap()
+            .get_request_with_query(
+                "stats",
+                Query::params([QueryParam::new("token", "")].to_vec()),
+                Some(headers_with_request_id(request_id)),
+            )
+            .await;
 
-    assert!(
-        logs_contains_a_line_with(&["ERROR", "API", &format!("{request_id}")]),
-        "Expected logs to contain: ERROR ... API ... request_id={request_id}"
-    );
+        assert_token_not_valid(response).await;
 
-    env.stop().await;
-}
+        assert!(
+            logs_contains_a_line_with(&["ERROR", "API", &format!("{request_id}")]),
+            "Expected logs to contain: ERROR ... API ... request_id={request_id}"
+        );
+
+        env.stop().await;
+    }
+
+    #[tokio::test]
+    async fn it_should_not_authenticate_requests_when_the_token_is_invalid() {
+        logging::setup();
+
+        let env = Started::new(&configuration::ephemeral().into()).await;
+
+        let request_id = Uuid::new_v4();
 
-#[tokio::test]
-async fn should_not_authenticate_requests_when_the_token_is_invalid() {
-    logging::setup();
+        let response = Client::new(env.get_connection_info())
+            .unwrap()
+            .get_request_with_query(
+                "stats",
+                Query::params([QueryParam::new("token", "INVALID TOKEN")].to_vec()),
+                Some(headers_with_request_id(request_id)),
+            )
+            .await;
 
-    let env = Started::new(&configuration::ephemeral().into()).await;
+        assert_token_not_valid(response).await;
 
-    let request_id = Uuid::new_v4();
+        assert!(
+            logs_contains_a_line_with(&["ERROR", "API", &format!("{request_id}")]),
+            "Expected logs to contain: ERROR ... API ... request_id={request_id}"
+        );
 
-    let response = Client::new(env.get_connection_info())
-        .unwrap()
-        .get_request_with_query(
-            "stats",
-            Query::params([QueryParam::new("token", "INVALID TOKEN")].to_vec()),
-            Some(headers_with_request_id(request_id)),
-        )
-        .await;
+        env.stop().await;
+    }
 
-    assert_token_not_valid(response).await;
+    #[tokio::test]
+    async fn it_should_allow_the_token_query_param_to_be_at_any_position_in_the_url_query() {
+        logging::setup();
 
-    assert!(
-        logs_contains_a_line_with(&["ERROR", "API", &format!("{request_id}")]),
-        "Expected logs to contain: ERROR ... API ... request_id={request_id}"
-    );
+        let env = Started::new(&configuration::ephemeral().into()).await;
 
-    env.stop().await;
+        let token = env.get_connection_info().api_token.unwrap();
+
+        // At the beginning of the query component
+        let response = Client::new(env.get_connection_info())
+            .unwrap()
+            .get_request(&format!("torrents?token={token}&limit=1"))
+            .await;
+
+        assert_eq!(response.status(), 200);
+
+        // At the end of the query component
+        let response = Client::new(env.get_connection_info())
+            .unwrap()
+            .get_request(&format!("torrents?limit=1&token={token}"))
+            .await;
+
+        assert_eq!(response.status(), 200);
+
+        env.stop().await;
+    }
 }
 
-#[tokio::test]
-async fn should_allow_the_token_query_param_to_be_at_any_position_in_the_url_query() {
-    logging::setup();
+mod given_that_not_token_is_provided {
+
+    use torrust_axum_rest_tracker_api_server::environment::Started;
+    use torrust_rest_tracker_api_client::common::http::Query;
+    use torrust_rest_tracker_api_client::v1::client::{headers_with_request_id, Client};
+    use torrust_tracker_test_helpers::logging::logs_contains_a_line_with;
+    use torrust_tracker_test_helpers::{configuration, logging};
+    use uuid::Uuid;
+
+    use crate::server::v1::asserts::assert_unauthorized;
 
-    let env = Started::new(&configuration::ephemeral().into()).await;
+    #[tokio::test]
+    async fn it_should_not_authenticate_requests_when_the_token_is_missing() {
+        logging::setup();
 
-    let token = env.get_connection_info().api_token.unwrap();
+        let env = Started::new(&configuration::ephemeral().into()).await;
 
-    // At the beginning of the query component
-    let response = Client::new(env.get_connection_info())
-        .unwrap()
-        .get_request(&format!("torrents?token={token}&limit=1"))
-        .await;
+        let request_id = Uuid::new_v4();
 
-    assert_eq!(response.status(), 200);
+        let response = Client::new(env.get_connection_info())
+            .unwrap()
+            .get_request_with_query("stats", Query::default(), Some(headers_with_request_id(request_id)))
+            .await;
 
-    // At the end of the query component
-    let response = Client::new(env.get_connection_info())
-        .unwrap()
-        .get_request(&format!("torrents?limit=1&token={token}"))
-        .await;
+        assert_unauthorized(response).await;
 
-    assert_eq!(response.status(), 200);
+        assert!(
+            logs_contains_a_line_with(&["ERROR", "API", &format!("{request_id}")]),
+            "Expected logs to contain: ERROR ... API ... request_id={request_id}"
+        );
 
-    env.stop().await;
+        env.stop().await;
+    }
 }

packages/rest-tracker-api-client/src/v1/client.rs

@@ -180,15 +180,36 @@ pub async fn get(path: Url, query: Option<Query>, headers: Option<HeaderMap>) ->
     builder.send().await.unwrap()
 }
 
-/// Returns a `HeaderMap` with a request id header
+/// Returns a `HeaderMap` with a request id header.
 ///
 /// # Panics
 ///
-/// Will panic if the request ID can't be parsed into a string.
+/// Will panic if the request ID can't be parsed into a `HeaderValue`.
 #[must_use]
 pub fn headers_with_request_id(request_id: Uuid) -> HeaderMap {
     let mut headers = HeaderMap::new();
-    headers.insert("x-request-id", request_id.to_string().parse().unwrap());
+    headers.insert(
+        "x-request-id",
+        request_id
+            .to_string()
+            .parse()
+            .expect("the request ID is not a valid header value"),
+    );
+    headers
+}
+
+/// Returns a `HeaderMap` with an authorization token.
+///
+/// # Panics
+///
+/// Will panic if the token can't be parsed into a `HeaderValue`.
+#[must_use]
+pub fn headers_with_auth_token(token: &str) -> HeaderMap {
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        "Authorization: Bearer",
+        token.to_string().parse().expect("the auth token is not a valid header value"),
+    );
     headers
 }