Merge #1367: New API feature: allow API clients to authenticate via authentication header

34f2f43 refactor: [#727] use the Authentication header in the API client (Jose Celano)
084beb2 feat: [#727] allow to authenticate API via authentication header (Jose Celano)

Pull request description:

  The API allows 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 an `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, etc.

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

  The API client uses by default the `Authentication Header`. It could be a breaking change if you use the newer client witn an old API that does not support it. However we have not released any crate for the API client yet. And [we are still using a different client in the Index](torrust/torrust-index#806).

ACKs for top commit:
  josecelano:
    ACK 34f2f43

Tree-SHA512: 94e83465f0f105200ea4257aa9a8e1f15b810410fd421e30f286cbea4bd47f3917a83088337ca6608f572f828f82f5a90aa18298763821c1c5e0da7e02c7ea6a

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};
@@ -32,6 +51,8 @@ use torrust_tracker_configuration::AccessTokens;
 
 use crate::v1::responses::unhandled_rejection_response;
 
+pub const AUTH_BEARER_TOKEN_HEADER_PREFIX: &str = "Bearer";
+
 /// Container for the `token` extracted from the query params.
 #[derive(Deserialize, Debug)]
 pub struct QueryParams {
@@ -43,16 +64,29 @@ 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 = match extract_bearer_token_from_header(&request) {
+        Ok(token) => token,
+        Err(err) => return err.into_response(),
+    };
+
+    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,18 +96,50 @@ pub async fn auth(
     next.run(request).await
 }
 
+fn extract_bearer_token_from_header(request: &Request<axum::body::Body>) -> Result<Option<String>, AuthError> {
+    let headers = request.headers();
+
+    let header_value = headers
+        .get(axum::http::header::AUTHORIZATION)
+        .and_then(|header_value| header_value.to_str().ok());
+
+    match header_value {
+        None => Ok(None),
+        Some(header_value) => {
+            if header_value == AUTH_BEARER_TOKEN_HEADER_PREFIX {
+                // Empty token
+                return Ok(Some(String::new()));
+            }
+
+            if !header_value.starts_with(&format!("{AUTH_BEARER_TOKEN_HEADER_PREFIX} ").to_string()) {
+                // Invalid token type. Missing "Bearer" prefix.
+                return Err(AuthError::UnknownTokenProvided);
+            }
+
+            Ok(header_value
+                .strip_prefix(&format!("{AUTH_BEARER_TOKEN_HEADER_PREFIX} ").to_string())
+                .map(std::string::ToString::to_string))
+        }
+    }
+}
+
 enum AuthError {
     /// Missing token for authentication.
     Unauthorized,
+
     /// Token was provided but it is not valid.
     TokenNotValid,
+
+    /// Token was provided but it is not in a format that the server can't understands.
+    UnknownTokenProvided,
 }
 
 impl IntoResponse for AuthError {
     fn into_response(self) -> Response {
         match self {
             AuthError::Unauthorized => unauthorized_response(),
             AuthError::TokenNotValid => token_not_valid_response(),
+            AuthError::UnknownTokenProvided => unknown_auth_data_provided_response(),
         }
     }
 }
@@ -93,3 +159,12 @@ pub fn unauthorized_response() -> Response {
 pub fn token_not_valid_response() -> Response {
     unhandled_rejection_response("token not valid".to_string())
 }
+
+/// `500` error response when the provided token type is not valid.
+///
+/// The client has provided authentication information that the server does not
+/// understand.
+#[must_use]
+pub fn unknown_auth_data_provided_response() -> Response {
+    unhandled_rejection_response("unknown token provided".to_string())
+}