Forem: Simon Bittok

Implementing JWT Authentication in Rust using Axum – Part 5

Simon Bittok — Wed, 05 Nov 2025 08:30:54 +0000

This is part 5 of this series, where I implement JWT authentication using the Axum framework in Rust.

Series

Source Code

The entire source code is available on my GitHub.

Quick Recap

In the previous section, we learned how to pass state to handlers, create middleware using Tower, and generate JSON web tokens (JWTs). Now we'll put these pieces together to build a complete authentication system.

Introduction

In this chapter, we'll implement the core authentication flow: user registration and login. Our authentication strategy uses two types of tokens:

Access tokens (short-lived, 15 minutes) - sent in cookies and used for API authorization
Refresh tokens (long-lived, 1 month) - stored server-side in Redis and used to issue new access tokens

By storing refresh tokens in Redis, we gain the ability to explicitly revoke sessions, something that's impossible with stateless JWT tokens alone. When a user logs out, we simply delete their refresh token from Redis, immediately invalidating their session.

Token Storage and Retrieval

Let's extend our AppContext with methods to manage refresh tokens in Redis. Add the following implementation:

#[derive(Clone)]
pub struct AppContext {
    pub config: Config,
    pub auth: AuthContext,
    pub db: PgPool,
    pub redis: MultiplexedConnection,
}

impl AppContext {
    pub async fn store_refresh_token(&self, token_details: &TokenDetails) -> Result<(), Report> {
        let mut conn = self.redis.clone();
        let key = format!("refresh_token:{}", token_details.token_id);
        let value = serde_json::to_string(token_details)?;

        if let Some(expires_in) = token_details.expires_in {
            let ttl = (expires_in - chrono::Utc::now().timestamp()) as u64;
            conn.set_ex(&key, &value, ttl).await?;
        } else {
            conn.set(&key, &value).await?;
        }

        Ok(())
    }

    pub async fn revoke_refresh_token(&self, token_id: Uuid) -> Result<(), Report> {
        let mut conn = self.redis.clone();
        let key = format!("refresh_token:{}", token_id);

        conn.del(&key).await?;

        Ok(())
    }

    pub async fn try_from(config: &Config) -> Result<Self, Report> {
        let db = config.database().pool().await;
        let redis = config.redis().multiplexed_connection().await?;

        let auth = AuthContext {
            access: config.auth().access().try_into()?,
            refresh: config.auth().refresh().try_into()?,
        };

        Ok(Self {
            redis,
            db,
            auth,
            config: config.clone(),
        })
    }
}

Note on implementation: I converted the try_from method from a TryFrom<T> trait implementation to a regular async method. The trait version caused runtime panics because block_on was being called in an async context during application startup.

Here's how token storage works:

We serialize the entire TokenDetails struct to JSON and store it as a Redis string
The set_ex method automatically expires the token after its TTL (time-to-live), ensuring Redis cleans up stale tokens
The set method is a fallback that handles tokens without expiration (though this should rarely occur in practice)
For explicit logout, we use revoke_refresh_token to immediately delete the token from Redis

Database Models

With our token storage ready, let's create the user model that will interact with our PostgreSQL database. Create a model/ module and add a user.rs file:

use std::borrow::Cow;

use argon2::{
    Argon2, PasswordHash, PasswordVerifier,
    password_hash::{PasswordHasher, SaltString, rand_core::OsRng},
};
use chrono::{
    DateTime, FixedOffset,
    format::{DelayedFormat, StrftimeItems},
};
use serde::{Deserialize, Serialize};
use sqlx::{Encode, Executor, Postgres, prelude::FromRow};
use uuid::Uuid;

use crate::Result;

#[derive(Debug, Deserialize, Serialize, Clone)]
pub struct RegisterUser<'a> {
    email: Cow<'a, str>,
    name: Cow<'a, str>,
    password: Cow<'a, str>,
}

#[derive(Debug, Deserialize, Serialize, Clone)]
pub struct LoginUser<'a> {
    email: Cow<'a, str>,
    password: Cow<'a, str>,
}

impl LoginUser<'_> {
    pub fn email(&self) -> &str {
        &self.email
    }

    pub fn password(&self) -> &str {
        &self.password
    }
}

#[derive(Debug, Deserialize, Clone, FromRow, Encode)]
pub struct User {
    id: i32,
    pid: Uuid,
    email: String,
    name: String,
    password: String,
    created_at: DateTime<FixedOffset>,
    updated_at: DateTime<FixedOffset>,
}

impl User {
    pub async fn create_user<'e, C>(db: &C, new_user: &RegisterUser<'_>) -> Result<Self>
    where
        for<'a> &'a C: Executor<'e, Database = Postgres>,
    {
        let user = sqlx::query_as::<_, Self>(
            r"
           INSERT INTO users (email, name, password)
           VALUES ($1, $2, $3)
           RETURNING *
           ",
        )
        .bind(new_user.email.trim())
        .bind(new_user.name.trim())
        .bind(password_hash(&new_user.password)?)
        .fetch_one(db)
        .await?;
        Ok(user)
    }

    pub async fn find_by_email<'e, C>(db: &C, email: &str) -> Result<Option<Self>>
    where
        for<'a> &'a C: Executor<'e, Database = Postgres>,
    {
        sqlx::query_as(
            r"
            SELECT * FROM users WHERE email = $1
        ",
        )
        .bind(email.trim())
        .fetch_optional(db)
        .await
        .map_err(Into::into)
    }

    pub fn verify_password(&self, password: &str) -> Result<()> {
        let password_hash =
            PasswordHash::new(&self.password).map_err(crate::Error::PasswordHash)?;

        Argon2::default()
            .verify_password(password.as_bytes(), &password_hash)
            .map_err(|err| match err {
                argon2::password_hash::Error::Password => crate::Error::InvalidCredentials,
                _ => crate::Error::PasswordHash(err),
            })?;

        Ok(())
    }

    pub fn pid(&self) -> Uuid {
        self.pid
    }

    pub fn email(&self) -> &str {
        &self.email
    }

    pub fn name(&self) -> &str {
        &self.name
    }

    pub fn id(&self) -> i32 {
        self.id
    }

    pub fn created_at(&self) -> DelayedFormat<StrftimeItems<'_>> {
        self.created_at.format("%Y-%m-%d %H:%M")
    }
}

fn password_hash(plain_password: &str) -> Result<String> {
    let argon2 = Argon2::default();
    let salt = SaltString::generate(&mut OsRng);

    let hash = argon2
        .hash_password(plain_password.as_bytes(), &salt)
        .map_err(crate::Error::PasswordHash)?;

    Ok(hash.to_string())
}

A note on Cow<'a, str>: You'll notice we use Cow<'a, str> instead of String for the request structs. Cow (Clone on Write) is more memory-efficient because it can hold either a borrowed reference or an owned string. For deserialized JSON data that we only read from, this avoids unnecessary heap allocations. The actual User struct from the database uses owned String types since that data persists beyond the request lifecycle.

We use the argon2 crate for secure password hashing with randomly generated salts. The verify_password method compares submitted passwords against the stored hash, converting any password mismatch into our custom InvalidCredentials error.

Authentication Handlers

Now let's wire everything together with our HTTP handlers. Create a controllers module and add an auth.rs file:

use std::sync::Arc;

use axum::{
    Json, Router,
    body::Body,
    debug_handler,
    extract::State,
    http::{
        HeaderValue, StatusCode,
        header::{AUTHORIZATION, SET_COOKIE},
    },
    response::{IntoResponse, Response},
    routing::post,
};
use axum_extra::extract::cookie;
use serde_json::json;

use crate::{
    Result,
    context::AppContext,
    middlewares::AuthError,
    models::{LoginUser, RegisterUser, User},
};

#[debug_handler]
async fn register(
    State(ctx): State<Arc<AppContext>>,
    Json(params): Json<RegisterUser<'static>>,
) -> Result<Response> {
    let _new_user = User::create_user(&ctx.db, &params).await?;

    Ok((
        StatusCode::CREATED,
        Json(json! ({
            "message": "User created succesfully"
        })),
    )
        .into_response())
}

#[debug_handler]
async fn login(
    State(ctx): State<Arc<AppContext>>,
    Json(params): Json<LoginUser<'static>>,
) -> Result<Response> {
    let user = User::find_by_email(&ctx.db, params.email())
        .await?
        .ok_or(crate::Error::Auth(AuthError::WrongCredentials))?;

    user.verify_password(params.password())?;

    // Issue access & refresh tokens
    let access_token = ctx.auth.access.generate_token(user.pid())?;
    let refresh_token = ctx.auth.refresh.generate_token(user.pid())?;

    ctx.store_refresh_token(&refresh_token).await?;

    let access_token = access_token.token.unwrap();
    let refresh_token = refresh_token.token.unwrap();

    let access_cookie = cookie::Cookie::build(("access_token", &access_token))
        .path("/")
        .http_only(false)
        .max_age(time::Duration::seconds(ctx.auth.access.exp))
        .same_site(cookie::SameSite::Lax);

    let refresh_cookie = cookie::Cookie::build(("refresh_token", &refresh_token))
        .path("/")
        .http_only(true)
        .max_age(time::Duration::seconds(ctx.auth.refresh.exp))
        .same_site(cookie::SameSite::Lax);

    let mut res = Response::builder().status(StatusCode::OK).body(Body::from(
        json!({
            "access_token": &access_token,
            "name": user.name(),
            "created_at": user.created_at().to_string()
        })
        .to_string(),
    ))?;

    res.headers_mut().append(
        AUTHORIZATION,
        HeaderValue::from_str(access_token.as_str()).unwrap(),
    );
    res.headers_mut().append(
        SET_COOKIE,
        HeaderValue::from_str(access_cookie.to_string().as_str()).unwrap(),
    );
    res.headers_mut().append(
        SET_COOKIE,
        HeaderValue::from_str(refresh_cookie.to_string().as_str()).unwrap(),
    );

    Ok(res)
}

#[debug_handler]
async fn current(
    Extension(auth): Extension<TokenDetails>,
    State(ctx): State<Arc<AppContext>>,
) -> Result<Response> {
    let user = User::find_by_pid(&ctx.db, auth.user_pid).await?;
    Ok((
        StatusCode::OK,
        Json(json!({
            "name": user.name(),
            "pid": user.pid(),
            "email": user.email()
        })),
    )
        .into_response())
}

pub fn router(ctx: &Arc<AppContext>) -> Router {
    Router::new()
        .route("/register", post(register))
        .route("/login", post(login))
        .route(
            "/current",
            get(current)
                .layer(AuthLayer::new(ctx))
                .layer(RefreshLayer::new(ctx)),
        )
        .route(
            "/logout",
            post(logout)
                .layer(AuthLayer::new(ctx))
                .layer(RefreshLayer::new(ctx)),
        )
        .with_state(ctx.clone())
}

Understanding the login flow:

We verify the user's credentials against the database
Generate both access and refresh tokens containing the user's UUID
Store the refresh token details in Redis for later validation and revocation
Send both tokens as cookies to the client:
- Access token: http_only(false) so frontend JavaScript can read it and add it to the Authorization header for API requests
- Refresh token: http_only(true) to prevent JavaScript access, protecting against XSS attacks
Also include the access token in the response body for immediate use

The .unwrap() calls on the tokens are safe here because our token generation always produces a Some(String) value, the Option wrapper exists for other use cases in the token structure.

Fetching the Current User

We also need a way for authenticated users to retrieve their profile information. Add this handler above the router function:

#[debug_handler]
async fn current(
    Extension(auth): Extension<TokenDetails>,
    State(ctx): State<Arc<AppContext>>,
) -> Result<Response> {
    let user = User::find_by_pid(&ctx.db, auth.user_pid).await?;
    Ok((
        StatusCode::OK,
        Json(json!({
            "name": user.name(),
            "pid": user.pid(),
            "email": user.email()
        })),
    )
        .into_response())
}

This handler demonstrates how middleware can enrich our request context. Notice the Extension(auth): Extension<TokenDetails> parameter, this isn't something we extract from the request directly. Instead, our refresh middleware validates the refresh token and injects the decoded TokenDetails into the request extensions, making the authenticated user's information available to the handler.

The flow works like this:

Client sends request with access token in the Authorization header
AuthLayer middleware validates the token and extracts the token details
If the access token is expired, RefreshLayer attempts to refresh it using the refresh token from cookies
The validated TokenDetails (containing user_pid) is added to request extensions
Our handler extracts this data and fetches the full user profile from the database

Route protection with layered middleware: Notice how we apply both AuthLayer and RefreshLayer to the /current route. The order matters; RefreshLayer runs first to validate the refresh token, and if it access token is expired, issues a new one. AuthLayer validates the access token. This creates a seamless experience where users don't notice when their access tokens expire.

Registering Authentication Routes

Finally, let's mount our authentication routes in the main application. Update the run method in your app struct:

impl App {
    pub async fn run() -> Result<()> {
        HookBuilder::new().theme(if std::io::stderr().is_terminal() {
            Theme::dark()
        } else {
            Theme::new()
        });

        let config = Config::load()?;

        config.logger().setup()?;

        let ctx = Arc::new(AppContext::try_from(&config).await?);

        let router = Router::new()
            .route("/hello", get(|| async { "Hello from axum!" }))
            .nest("/auth", controllers::auth::router(&ctx))
            .layer(
                TraceLayer::new_for_http()
                    .make_span_with(middlewares::make_span_with)
                    .on_request(middlewares::on_request)
                    .on_response(middlewares::on_response)
                    .on_failure(middlewares::on_failure),
            );

        let listener = TcpListener::bind(config.server().address()).await?;

        tracing::info!("Listening on {}", config.server().url());

        axum::serve(listener, router).await.map_err(Into::into)
    }
}

The .nest() method mounts all our authentication routes under the /auth prefix. Since we're using Arc<AppContext>, cloning it only increments a reference counter rather than copying the entire structure—perfect for sharing state across handlers.

Testing the Authentication Flow

Let's verify everything works by registering and logging in a user.

Registering a User

Run your application, then in another terminal execute:

curl -X POST -H "Content-Type: application/json" \
  -d '{ "email": "test1@mail.com", "name": "Test One", "password": "Password" }' \
  http://127.0.0.1:7150/auth/register

You should receive this response:

{
  "message": "User created succesfully"
}

Signing In

Now authenticate with the user you just created:

curl -X POST -H "Content-Type: application/json" \
  -d '{ "email": "test1@mail.com", "password": "Password" }' \
  http://127.0.0.1:7150/auth/login

The response will include an access token, the user's name, and their account creation timestamp. Behind the scenes, the refresh token has been securely stored in Redis.

To verify the refresh token is in Redis, you can inspect your Redis volume:

sudo cat /var/lib/docker/volumes/axum-auth_redis_data/_data/dump.rdb

Replace axum-auth_redis_data with your actual Redis volume name. You should see the serialized token details stored with a key like refresh_token:<uuid>.

Testing the Current User Endpoint

With an active session, you can now fetch the authenticated user's profile. When making the request, you need to include both the Authorization header and the refresh token cookie:

curl -X GET \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Cookie: refresh_token=<your_refresh_token>" \
  http://127.0.0.1:7150/auth/current

This will return the authenticated user's profile:

{
  "name": "Test One",
  "pid": "550e8400-e29b-41d4-a716-446655440000",
  "email": "test1@mail.com"
}

Why both tokens are needed: The access token in the Authorization header is validated first by AuthLayer. If it has expired (after 15 minutes), RefreshLayer checks for the refresh token cookie, validates it against Redis, and issues a new access token. The refresh token cookie is essential for this automatic token renewal to work. Without it, an expired access token would simply result in an authentication error.

Testing Logout

To test the logout functionality, make sure you're authenticated (you should have both tokens from the login response), then execute:

curl -X POST \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Cookie: refresh_token=<your_refresh_token>" \
  http://127.0.0.1:7150/auth/logout

You should receive a success response:

{
  "message": "Logout success"
}

After logout, if you try to access the /current endpoint again with the same tokens, you'll receive an authentication error. The refresh token has been deleted from Redis, so even though you still have the cookie, it can no longer be used to generate new access tokens. The old access token will continue to work until it expires (within 15 minutes), but this short window is an acceptable trade-off for the performance benefits of stateless JWT validation.

We now have a working authentication system with user registration and login! The access tokens enable short-lived API access, while refresh tokens stored in Redis give us explicit control over session revocation.

This Series

Part 1: Project Setup & Configuration
Part 2: Implementing Logging
Part 3: Database Setup with SQLx and PostgreSQL.
Part 4: JWTs & Middlewares
Part 5: Creating & Authenticating Users (You are here)

Implementing JWT Authentication in Rust using Axum – Part 4

Simon Bittok — Tue, 04 Nov 2025 09:19:47 +0000

This is part 4 of this series, where I implement JWT authentication using the Axum framework in Rust.

The previous part is here.

Source Code

The repository is here

Quick Recap

In the previous chapter we added database and JWT configurations. We created an application context, which is initialised once and shared throughout the application.

Introduction

In this chapter we will see how to create middlewares in Axum using Tower. The middlewares here will be used for authentication purposes. We will use the argon2 crate added in the previous section to hash passwords; the jsonwebtoken crate will provide methods to sign and verify tokens.

Dependencies:

Add the following deps.

cargo add time -F serde
cargo add axum-extra -F "cookie, typed-header, typed-routing"
cargo add futures_util
cargo add tower -F "tracing, tokio"

Sharing State with Handlers.

Add the AppContext we created in the previous chapters to our router.

// src/app.rs
        let ctx = Arc::new(AppContext::try_from(&config)?);

        let router = Router::new()
            .route("/hello", get(|| async { "Hello from axum!" }))
// We will the share the state with handlers i.e.
// .route("/auth", auth::routers(&ctx))
            .layer(
                TraceLayer::new_for_http()
                    .make_span_with(middlewares::make_span_with)
                    .on_request(middlewares::on_request)
                    .on_response(middlewares::on_response)
                    .on_failure(middlewares::on_failure),
            );

Signing & Verifying JWTs.

Let's create functions and data structures that will encode and decode tokens. Inside the model module, create a token.rs file and add the following contents.

use serde::{Deserialize, Serialize};
use uuid::Uuid;

/// The token string deserialises to this struct
/// The `sub` field will be the user's pid
#[derive(Debug, Deserialize, Serialize, Clone)]
pub struct TokenClaims {
    pub sub: String,
    pub id: String,
    pub exp: i64,
    pub iat: i64,
    pub nbf: i64,
}

/// This struct will let us store our token in Redis
#[derive(Debug, Deserialize, Serialize, Clone)]
pub struct TokenDetails {
    pub token: Option<String>,
    pub token_id: Uuid,
    pub user_pid: Uuid,
    pub expires_in: Option<i64>,
}

Understanding Token Details

The TokenDetails struct serves as a bridge between our JWT implementation and Redis storage. For refresh tokens, which need to persist across sessions, we can store the TokenDetails in Redis using the token_id as the key. This allows us to:

Track Active Sessions: Store long-lived refresh tokens to track user sessions.
Enable Token Revocation: Delete a token from Redis to immediately invalidate it, even before expiration.
Link Tokens to Users: Use the user_pid to find all active tokens for a specific user.
Automatic Cleanup: expires_in lets us implement Redis TTL (time-to-live).

In our context.rs file, add this implementation to the JwtContext.

impl JwtContext {
    pub fn generate_token(&self, sub: Uuid) -> Result<TokenDetails, Report> {
        let now = chrono::Utc::now();

        let mut token_details = TokenDetails {
            user_pid: sub,
            token_id: Uuid::new_v4(),
            expires_in: Some((now + chrono::Duration::seconds(self.exp)).timestamp()),
            token: None,
        };

        let claims = TokenClaims {
            sub: token_details.user_pid.to_string(),
            id: token_details.token_id.to_string(),
            exp: token_details.expires_in.ok_or(crate::Error::TokenError)?,
            iat: now.timestamp(),
            nbf: now.timestamp(),
        };

        let header = Header::new(Algorithm::RS256); // import from jsonwebtoken

        let token = jsonwebtoken::encode(&header, &claims, &self.encoding_key)?;

        token_details.token = Some(token);

        Ok(token_details)
    }

    pub fn verify_token(&self, token: &str) -> Result<TokenDetails, Report> {
        let validation = Validation::new(Algorithm::RS256);

        let token_data =
            jsonwebtoken::decode::<TokenClaims>(token, &self.decoding_key, &validation)?;

        let user_pid = Uuid::parse_str(&token_data.claims.sub)?; // import from uuid
        let token_id = Uuid::parse_str(&token_data.claims.id)?;

        Ok(TokenDetails {
            token: None,
            token_id,
            user_pid,
            expires_in: None,
        })
    }
}

Change the type of the exp field to i64.

Understanding Generating & Verifying Tokens.

The generate_token method creates a new JWT by initialising token metadata (TokenDetails) and building JWT claims (TokenClaims). You can read more about claims here. Then we create a token, which is a base64 string, using the encoding key (private key).

The verify_token method is pretty simple; we use the decoding key (public key) to decode the string and then deserialise it to the TokenClaims struct. But since the user_pid and token_id are of type Uuid we parse them to that type.

Middlewares

Middlewares are functions which usually run before a request is processed by a handler. Therefore they are perfect for checking if a user is authenticated and authorised, etc.

Inside the middlewares module create auth.rs and refresh.rs files and add the following contents:

auth.rs

/// This module contains middleware code to check if a user is authenticated.
/// It uses `tower::Service` and `tower::Layer` to create Request middleware.
use std::{
    convert::Infallible,
    sync::Arc,
    task::{Context, Poll},
};

use axum::{
    RequestPartsExt,
    body::Body,
    http::{Request, Response},
    response::IntoResponse,
};
use axum_extra::{
    TypedHeader,
    headers::{Authorization, Cookie, authorization::Bearer},
    typed_header::TypedHeaderRejectionReason,
};
use futures_util::future::BoxFuture;
use tower::{Layer, Service};

use crate::{context::AppContext, middlewares::AuthError};

#[derive(Clone)]
pub struct AuthLayer {
    ctx: Arc<AppContext>,
}

impl AuthLayer {
    pub fn new(ctx: &Arc<AppContext>) -> Self {
        Self { ctx: ctx.clone() }
    }
}

impl<S> Layer<S> for AuthLayer {
    type Service = AuthService<S>;

    fn layer(&self, inner: S) -> Self::Service {
        Self::Service {
            inner,
            ctx: self.ctx.clone(),
        }
    }
}

#[derive(Clone)]
pub struct AuthService<S> {
    inner: S,
    ctx: Arc<AppContext>,
}

impl<S, B> Service<Request<B>> for AuthService<S>
where
    S: Service<Request<B>, Response = Response<Body>, Error = Infallible> + Clone + Send + 'static,
    S::Future: Send + 'static,
    B: Send + 'static,
{
    type Response = S::Response;
    type Error = S::Error;

    type Future = BoxFuture<'static, Result<Self::Response, Self::Error>>;

    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        self.inner.poll_ready(cx)
    }

    fn call(&mut self, req: Request<B>) -> Self::Future {
        let ctx = self.ctx.clone();
        let clone = self.inner.clone();

        // Take the service that is ready
        let mut inner = std::mem::replace(&mut self.inner, clone);

        Box::pin(async move {
            let (mut parts, body) = req.into_parts();

            let access_token = match parts.extract::<TypedHeader<Authorization<Bearer>>>().await {
                Ok(header) => Some(header.token().to_string()),
                Err(err) => {
                    // Access Token not in authorisation header; so check cookies
                    if matches!(err.reason(), TypedHeaderRejectionReason::Missing) {
                        parts.extract::<TypedHeader<Cookie>>().await.ok().and_then(
                            |TypedHeader(cookies)| {
                                cookies.get("access_token").map(ToString::to_string)
                            },
                        )
                    } else {
                        // The reason why we wrap the return value in Ok despite it being an error
                        // is beacause middlewares in Axum cannot return Errors i.e `Error =
                        // Infallible`
                        return Ok::<Response<Body>, Self::Error>(
                            AuthError::InvalidToken.into_response(),
                        );
                    }
                }
            };

            let Some(access_token) = access_token else {
                return Ok(AuthError::MissingCredentials.into_response());
            };

            // verify the access token
            let _token_details = match ctx.auth.access.verify_token(&access_token) {
                Ok(details) => details,
                Err(err) => return Ok(err.into_response()),
            };

            // Reconstuct the Request and insert the token details into it.

            let req = Request::from_parts(parts, body);

            inner.call(req).await
        })
    }
}

refresh.rs

/// This module contains middleware code to refresh a user's expired access token.
/// It uses `tower::Service` and `tower::Layer` to create Request middleware.
use std::{
    convert::Infallible,
    sync::Arc,
    task::{Context, Poll},
};

use axum::{
    RequestPartsExt,
    body::Body,
    http::{
        HeaderValue, Request, Response,
        header::{AUTHORIZATION, SET_COOKIE},
    },
    response::IntoResponse,
};
use axum_extra::{
    TypedHeader,
    extract::cookie,
    headers::{Authorization, Cookie, authorization::Bearer},
    typed_header::TypedHeaderRejectionReason,
};
use futures_util::future::BoxFuture;
use redis::AsyncCommands as _;
use tower::{Layer, Service};

use crate::{context::AppContext, middlewares::AuthError, models::token::TokenDetails};

#[derive(Clone)]
pub struct RefreshLayer {
    ctx: Arc<AppContext>,
}

impl RefreshLayer {
    pub fn new(ctx: &Arc<AppContext>) -> Self {
        Self { ctx: ctx.clone() }
    }
}

impl<S> Layer<S> for RefreshLayer {
    type Service = RefreshService<S>;

    fn layer(&self, inner: S) -> Self::Service {
        Self::Service {
            inner,
            ctx: self.ctx.clone(),
        }
    }
}

#[derive(Clone)]
pub struct RefreshService<S> {
    inner: S,
    ctx: Arc<AppContext>,
}

impl<S, B> Service<Request<B>> for RefreshService<S>
where
    S: Service<Request<B>, Response = Response<Body>, Error = Infallible> + Clone + Send + 'static,
    S::Future: Send + 'static,
    B: Send + 'static,
{
    type Response = S::Response;
    type Error = S::Error;

    type Future = BoxFuture<'static, Result<Self::Response, Self::Error>>;

    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        self.inner.poll_ready(cx)
    }

    fn call(&mut self, req: Request<B>) -> Self::Future {
        let ctx = self.ctx.clone();
        let clone = self.inner.clone();

        let mut inner = std::mem::replace(&mut self.inner, clone);

        Box::pin(async move {
            let (mut parts, body) = req.into_parts();

            let refresh_token = match parts.extract::<TypedHeader<Cookie>>().await {
                Ok(cookies) => cookies.get("refresh_token").map(ToString::to_string),
                Err(_) => return Ok(AuthError::MissingCredentials.into_response()),
            };

            let Some(refresh_token) = refresh_token else {
                return Ok(AuthError::MissingCredentials.into_response());
            };

            let access_token = match parts.extract::<TypedHeader<Authorization<Bearer>>>().await {
                Ok(header) => Some(header.token().to_string()),
                Err(err) => {
                    // extract from the cookie object
                    if matches!(err.reason(), TypedHeaderRejectionReason::Missing) {
                        parts.extract::<TypedHeader<Cookie>>().await.ok().and_then(
                            |TypedHeader(cookies)| {
                                cookies.get("access_token").map(ToString::to_string)
                            },
                        )
                    } else {
                        // The reason why we wrap the return value in Ok despite it being an error
                        // is beacause middlewares in Axum cannot return Errors i.e `Error =
                        // Infallible`
                        return Ok::<Response<Body>, Self::Error>(
                            AuthError::InvalidToken.into_response(),
                        );
                    }
                }
            };

            // Verify the refresh token and get the user's pid
            let refresh_token_details = match ctx.auth.refresh.verify_token(&refresh_token) {
                Ok(details) => details,
                Err(err) => return Ok(err.into_response()),
            };

            // Check if the Refresh Token is in cache
            let mut redis_conn = ctx.redis.clone();
            let redis_key = format!("refresh_token:{}", refresh_token_details.token_id);

            let stored_token: Result<String, crate::Error> = redis_conn
                .get(&redis_key)
                .await
                .map_err(crate::Error::Redis);

            let stored_details = match stored_token {
                Ok(token) => match serde_json::from_str::<TokenDetails>(&token)
                    .map_err(crate::Error::SerdeJson)
                {
                    Ok(details) => details,
                    Err(err) => return Ok(err.response()),
                },
                Err(err) => return Ok(err.response()),
            };

            // if access token is missing we issue a new one.
            let new_access_token: String;
                       if let Some(token) = access_token {
                // Verify if the existing access token is still valid
                match ctx.auth.access.verify_token(&token) {
                    Ok(_) => new_access_token = token,
                    Err(_) => {
                        // Token is invalid for whatever reason
                        match ctx.auth.access.generate_token(stored_details.user_pid) {
                            Ok(details) => new_access_token = details.token.unwrap(),
                            Err(e) => return Ok(e.into_response()),
                        }
                    }
                }
            } else {
                // No access token present; probably expired and got expelled from cookies
                match ctx.auth.access.generate_token(stored_details.user_pid) {
                    Ok(details) => {
                        new_access_token = details.token.unwrap();
                    }
                    Err(e) => return Ok(e.into_response()),
                }
            }


            let access_cookie = cookie::Cookie::build(("access_token", &new_access_token))
                .path("/")
                .max_age(time::Duration::seconds(ctx.auth.access.exp))
                .same_site(cookie::SameSite::Lax)
                .http_only(true)
                .to_string();

            let mut req = Request::from_parts(parts, body);
            req.headers_mut().append(
                AUTHORIZATION,
                HeaderValue::from_str(format!("Bearer {}", &new_access_token).as_str()).unwrap(),
            );
            req.headers_mut().append(
                SET_COOKIE,
                HeaderValue::from_str(access_cookie.as_str()).unwrap(),
            );

            inner.call(req).await
        })
    }
}

Understanding The Middleware

This is usually how we implement middleware functions in Axum. You may notice its implemetation is quite familiar with the Future trait from the standard library that is because the Service job is to produce a Future.

Layer is a factory for middleware; It takes an inner service and produces a wrapped service. This is how we compose middleware at the router.
Service> for T is the middleware itself. axum treat HTTP handling as calling a Service that returns a Response. Implementing Service is the canonical, low-level way to make middleware.

Authentication Errors

Create an error.rs file inside the middleware module & add the following contents.

use axum::{
    Json,
    http::StatusCode,
    response::{IntoResponse, Response},
};
use serde_json::json;

#[derive(Debug, thiserror::Error)]
pub enum AuthError {
    #[error("Invalid token")]
    InvalidToken,
    #[error("Credentials missing from request")]
    MissingCredentials,
    #[error("Token creation failed")]
    TokenCreation,
    #[error("Wrong credentials")]
    WrongCredentials,
}

pub type AuthResult<T, E = AuthError> = Result<T, E>;

impl IntoResponse for AuthError {
    fn into_response(self) -> Response {
        self.response()
    }
}

impl AuthError {
    pub fn response(&self) -> Response {
        let (status, message) = match self {
            Self::InvalidToken => (StatusCode::UNAUTHORIZED, "Invalid token"),
            Self::MissingCredentials => {
                (StatusCode::BAD_REQUEST, "Credentials missing from request")
            }
            Self::TokenCreation => (StatusCode::INTERNAL_SERVER_ERROR, "Internal server error"),
            Self::WrongCredentials => (StatusCode::UNAUTHORIZED, "Wrong credentials"),
        };

        let body = Json(json!({
            "error": message
        }));

        (status, body).into_response()
    }
}

Then add the AuthError to the main Error enum in error/mod.rs

use std::{
    env::VarError,
    fmt::{self, Display},
};

use argon2::password_hash::Error as PasswordHashError;
use axum::{
    Json,
    http::StatusCode,
    response::{IntoResponse, Response},
};
use serde_json::json;
use tracing_subscriber::filter::FromEnvError;

use crate::{middlewares::AuthError, models::ModelError};

#[derive(Debug)]
pub struct Report(pub color_eyre::Report);

impl IntoResponse for Report {
    fn into_response(self) -> Response {
        let err = self.0;
        let err_string = format!("{:?}", &err);

        tracing::error!("An error occured {}", err_string);

        if let Some(error) = err.downcast_ref::<Error>() {
            return error.response();
        }

        // backup response
        (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(json!({"error": "Something went wrong on our end."})),
        )
            .into_response()
    }
}

impl<E> From<E> for Report
where
    E: Into<color_eyre::Report>,
{
    fn from(err: E) -> Self {
        Self(err.into())
    }
}

impl Display for Report {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.0.fmt(f)
    }
}

pub type Result<T, E = Report> = std::result::Result<T, E>;

#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error(transparent)]
    Axum(#[from] axum::Error),
    #[error(transparent)]
    Config(#[from] config::ConfigError),
    #[error(transparent)]
    DirectiveParseError(#[from] tracing_subscriber::filter::ParseError),
    #[error(transparent)]
    EnvFilter(#[from] VarError),
    #[error(transparent)]
    FromEnv(#[from] FromEnvError),
    #[error(transparent)]
    IOError(#[from] std::io::Error),
    #[error(transparent)]
    TryInit(#[from] tracing_subscriber::util::TryInitError),
    #[error(transparent)]
    Migrate(#[from] sqlx::migrate::MigrateError),
    #[error(transparent)]
    Redis(#[from] redis::RedisError),
    #[error(transparent)]
    JsonWebToken(#[from] jsonwebtoken::errors::Error),
    #[error("{0}")]
    Argon2(argon2::Error),
    #[error("{0}")]
    PasswordHash(argon2::password_hash::Error),
    #[error("Invalid email or password")]
    InvalidCredentials,
    #[error("Error occured when signing or verifying token")]
    TokenError,
    #[error(transparent)]
    SerdeJson(#[from] serde_json::error::Error),
    #[error(transparent)]
    Auth(#[from] AuthError),
    #[error(transparent)]
    Model(#[from] ModelError),
}

impl From<argon2::Error> for Error {
    fn from(err: argon2::Error) -> Self {
        Self::Argon2(err)
    }
}

impl From<PasswordHashError> for Error {
    fn from(err: PasswordHashError) -> Self {
        match err {
            PasswordHashError::Password => Self::InvalidCredentials,
            _ => Self::PasswordHash(err),
        }
    }
}

impl Error {
    pub fn response(&self) -> Response {
        let (status, message) = match self {
            Self::InvalidCredentials => (StatusCode::UNAUTHORIZED, "Invalid email or password"),
            Self::Auth(err) => return err.response(),
            Self::Model(err) => return err.response(),
            _ => (StatusCode::INTERNAL_SERVER_ERROR, "Internal Server Error"),
        };

        let body = Json(json!({
            "error": message
        }));

        (status, body).into_response()
    }
}

That concludes this part, where we have seen how to generate and verify JWTs, create middlewares in Axum using tower crate.

In the following section I will show you how to use the above code to create, sign-in & sign-out users.

This Series

Part 1: Project Setup & Configuration
Part 2: Implementing Logging
Part 3: Database Setup with SQLx and PostgreSQL.
Part 4: JWTs & Middlewares (You are here)
Part 5: Creating & Authenticating Users

Implementing JWT Authentication in Rust using Axum

Simon Bittok — Sun, 02 Nov 2025 08:08:01 +0000

This is part 3 of this series.

Previous: Part 2: Implementing Logging

Source Code

The github repository is here.

Quick Recap

In Part 1, we set up our Rust project with Axum, configured environment-based settings, and created a basic error handling system.
In Part 2, we set up our tracing system, which logs HTTP lifecycle using event spans. Now we'll set up our database both PostgreSQL & Redis.

Dependencies

Add the following dependencies to the project.

cargo add sqlx -F "runtime-tokio-rustls, postgres, macros, uuid, chrono"
cargo add uuid -F "serde,v4"
cargo add chrono -F serde
cargo add redis -F tokio-comp
cargo add argon2
cargo add jsonwebtoken -F rust_crypto

Then install sqlx-cli using cargo i.e. cargo install --locked sqlx-cli or cargo binstall sqlx-cli.

Database Infrastructure

We will use Docker to spin up these containers quickly. To get started, create a compose.yaml file in the root directory of the project and add configure it as follows.

services:
  postgres:
    image: postgres:latest-alpine
    container_name: auth-postgres
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  redis:
    image: redis:latest-alpine
    container_name: auth-redis
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - redis_data:/data
    ports:
      - "6379:6379"

volumes:
  postgres_data:
  redis_data:

Create a .env file again at the root and add the following variables.

POSTGRES_USER = postgres
POSTGRES_PASSWORD = postgres
POSTGRES_DB = postgres

DATABASE_URL = postgresql://postgres:postgres@localhost:5432/postgres

REDIS_URL = redis://localhost:6379

Then at the root of the file run the command docker compose up -d. This will pull the images from docker hub then build and start your containers. To tear them down you can run at the root docker compose down -v.

SQLx and Migrations

Run source .env. This will set the DATABASE_URL environment varialble needed by sqlx-cli. Then check that the variable has been set echo $DATABASE_URL it should print this postgresql://postgres:postgres@localhost:5432/postgres.

To create a pair of 'down-up' migrations run this at the root of your project.

sqlx migrate add -r init

This will create a new folder migrations with two SQL files.
In the up SQL file add the following.

-- Add up migration script here
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

CREATE TABLE "users" (
    id SERIAL PRIMARY KEY,
    pid UUID NOT NULL UNIQUE DEFAULT uuid_generate_v4(),
    email VARCHAR(255) NOT NULL UNIQUE,
    name VARCHAR(255) NOT NULL,
    password VARCHAR(255) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_user_email ON users(email);
CREATE INDEX idx_user_pid ON users(pid);


CREATE OR REPLACE FUNCTION update_timestamp()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_at = NOW();
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER update_user_updated_at_trigger
BEFORE UPDATE ON users
FOR EACH ROW
EXECUTE FUNCTION update_timestamp();

and in the down file add this.

-- Add down migration script here

-- Triggers
DROP TRIGGER IF EXISTS update_user_updated_at_trigger ON users;

-- Indices
DROP INDEX IF EXISTS idx_user_pid;
DROP INDEX IF EXISTS idx_user_email;

-- Tables
DROP TABLE IF EXISTS users;

-- Functions
DROP FUNCTION IF EXISTS update_timestamp;

-- Extensions
DROP EXTENSION IF EXISTS "uuid-ossp";

The up migration will create a "users" table in the database when we run the migration script and the down will revert drop the same table along with all the other scripts we created.

Now run the migration.

sqlx migrate run

To check if your migration has been applied you can run the following command.

 docker exec -it auth-postgres psql -U postgres

This will open the psql shell. Run this command after the postgres=# prompt: \dt. You should see two table an _sqlx_migrations and then your users one.

To exit \q.

Storage Configuration.

In the configuration files add the database and redis configs.

# Other config
database:
  uri: postgresql://postgres:postgres@localhost:5432/postgres
  username: postgres
  password: postgres
  host: localhost
  port: 5432
  database: postgres
  ssl: false

redis:
  uri: redis://localhost:6379

Create a db.rs file inside the config module. Then add the following configuration.

use redis::{Client, aio::MultiplexedConnection};
use serde::{Deserialize, Serialize};
use sqlx::{
    ConnectOptions, PgPool,
    postgres::{PgConnectOptions, PgSslMode},
};
use tracing::log::LevelFilter;

use crate::Result;

#[derive(Debug, Deserialize, Serialize, Clone)]
pub struct DatabaseConfig {
    uri: String,
    username: String,
    host: String,
    password: String,
    database: String,
    port: u16,
    ssl: bool,
}

impl DatabaseConfig {
    pub async fn pool(&self) -> PgPool {
        let ssl_mode = if self.ssl {
            PgSslMode::Require
        } else {
            PgSslMode::Prefer
        };

        let mut options = PgConnectOptions::new()
            .host(&self.host)
            .username(&self.username)
            .password(&self.password)
            .port(self.port)
            .ssl_mode(ssl_mode)
            .database(&self.database);

        options = options.log_statements(LevelFilter::Debug);

        PgPool::connect_lazy_with(options)
    }

    pub fn url(&self) -> &str {
        &self.uri
    }
}

#[derive(Debug, Deserialize, Serialize, Clone)]
pub struct RedisConfig {
    uri: String,
}

impl RedisConfig {
    pub fn client(&self) -> Result<Client> {
        Client::open(self.uri()).map_err(Into::into)
    }

    pub async fn multiplexed_connection(&self) -> Result<MultiplexedConnection> {
        self.client()?
            .get_multiplexed_async_connection()
            .await
            .map_err(Into::into)
    }

    pub fn uri(&self) -> &str {
        &self.uri
    }
}

In our Config struct add the database & redis fields.

#[derive(Debug, Deserialize, Clone)]
pub struct Config {
    database: DatabaseConfig,
    redis: RedisConfig,
}

impl Config {
   // Rest of the code.

    pub fn redis(&self) -> &RedisConfig {
        &self.redis
    }

    pub fn database(&self) -> &DatabaseConfig {
        &self.database
    }

}

Expand the errors inside error module.

#[derive(Debug, thiserror::Error)]
 pub enum Error{
   // Other errors
   #[error(transparent)]
    Sqlx(#[from] sqlx::Error),
    #[error(transparent)]
    Migrate(#[from] sqlx::migrate::MigrateError),
    #[error(transparent)]
    Redis(#[from] redis::RedisError),
}

Authentication Configuration

Before we start signing up users, we require the necessary infrastructure to provide authentication. Remember we will be using JWT with Asymmetic RSA keys to sign and verify keys. Lets generate the keys into a security dir inside the config dir.

Generating Keys.

At the root of the project run this command.

mkdir -p config/security/keys

This will create those two new directories 'security' and 'keys'.

Now to generate the access key pair and the refresh ones we will use openssl command found in Linux & MacOs. Run this command.

openssl genrsa -out config/security/keys/access_key.pem 4096
openssl rsa -in config/security/keys/access_key.pem -pubout -out config/security/keys/access_key_pub.pem

The first command will generate a private key and store it inside the access_key.pem file. The 2nd command will extract the public key from the private key file and write it to the access_key_pub.pem file.

Now to generate the refresh keys just repeat the same command but replace all occurrences of access with refresh.

In your gitignore file add the key format: *.pem. This will not include any of your secret files inside your repo.

AuthConfig

In the configuration yaml file add the following contents.

auth:
  access:
    # Path to the keys relative to Cargo.toml file.
    private_key: config/security/keys/access_key.pem
    public_key: config/security/keys/access_key_pub.pem
    exp: 900 # Seconds 15 minutes
  refresh:
    private_key: config/security/keys/refresh_key.pem
    public_key: config/security/keys/refresh_key_pub.pem
    exp: 2419200 # Seconds 4 Weeks

Inside the config module. Create a auth.rs file and add the following contents.

use std::path::PathBuf;

use jsonwebtoken::{DecodingKey, EncodingKey};
use serde::Deserialize;

use crate::Result;

#[derive(Debug, Deserialize, Clone)]
pub struct RsaJwtConfig {
    private_key: PathBuf,
    public_key: PathBuf,
    exp: i64,
}

impl RsaJwtConfig {
    pub fn encoding_key(&self) -> Result<EncodingKey> {
        let contents = std::fs::read_to_string(&self.private_key)?;

        EncodingKey::from_rsa_pem(contents.as_bytes()).map_err(Into::into)
    }

    pub fn decoding_key(&self) -> Result<DecodingKey> {
        let contents = std::fs::read_to_string(&self.public_key)?;

        DecodingKey::from_rsa_pem(contents.as_bytes()).map_err(Into::into)
    }

    pub fn exp(&self) -> i64 {
        self.exp
    }
}

#[derive(Debug, Deserialize, Clone)]
pub struct AuthConfig {
    access: RsaJwtConfig,
    refresh: RsaJwtConfig,
}

impl AuthConfig {
    pub fn access(&self) -> &RsaJwtConfig {
        &self.access
    }

    pub fn refresh(&self) -> &RsaJwtConfig {
        &self.refresh
    }
}

Then, like we have already done with the errors and Config struct derive from jsonwebtoken::error::Error and add an auth field with a getter method.

AppContext

In a web application with JWT authentication, we need several shared resources that are:

Expensive to create - Database connection pools, Redis connections, and cryptographic keys take time to initialize.
Used across many requests - Every authenticated request needs access to JWT keys, database, and Redis.
Thread-safe and clonable - Web servers handle requests concurrently, so these resources must be safely shared.

The AppContext struct solves the above issues by bundling these resources together.

Create a context.rs module inside the src directory and add the following contents.

use jsonwebtoken::{DecodingKey, EncodingKey};
use redis::aio::MultiplexedConnection;
use sqlx::PgPool;

use crate::{
    config::{Config, RsaJwtConfig},
    error::Report,
};

#[derive(Clone)]
pub struct AppContext {
    pub config: Config,
    pub auth: AuthContext,
    pub db: PgPool,
    pub redis: MultiplexedConnection,
}

impl TryFrom<&Config> for AppContext {
    type Error = Report;

    fn try_from(config: &Config) -> Result<Self, Self::Error> {
        let db =
            tokio::runtime::Handle::current().block_on(async { config.database().pool().await });

        let auth = AuthContext {
            access: config.auth().access().try_into()?,
            refresh: config.auth().refresh().try_into()?,
        };
        let redis = tokio::runtime::Handle::current()
            .block_on(async { config.redis().multiplexed_connection().await })?;

        Ok(Self {
            config: config.clone(),
            db,
            auth,
            redis,
        })
    }
}

#[derive(Clone)]
pub struct AuthContext {
    pub access: JwtContext,
    pub refresh: JwtContext,
}

#[derive(Clone)]
pub struct JwtContext {
    pub encoding_key: EncodingKey,
    pub decoding_key: DecodingKey,
    pub exp: u64,
}

impl TryFrom<&RsaJwtConfig> for JwtContext {
    type Error = Report;

    fn try_from(config: &RsaJwtConfig) -> Result<Self, Self::Error> {
        let encoding_key = config.encoding_key()?;
        let decoding_key = config.decoding_key()?;

        let exp = config.exp() as u64;

        Ok(Self {
            encoding_key,
            decoding_key,
            exp,
        })
    }
}

Understanding the AppContext.

Why Clone Trait? - Modern Rust web frameworks (like Axum or Actix) pass state to handlers by cloning. These types use Arc internally, making clones cheap (just incrementing the reference count rather than duplicating connections).

You might wonder why we use Handle::current().block_on() from tokio. That is because TryFrom is a synchronous trait but initialising the Database and Redis connections is asynchronous in nature. This conversion typically occurs once during application startup, before the async runtime begins serving requests. The one-time blocking cost is acceptable because; it only happens at startup (not per-request).

Conclusion

In the next chapter I will show you how to sign up, sign in and sign out users using the stateless JWTs.

This Series

Part 1: Project Setup & Configuration
Part 2: Implementing Logging
Part 3: Database Setup with SQLx and PostgreSQL (You are Here).
Part 4: JWTs & Middlewares
Next Part 5: Creating & Authenticating Users (Comming Soon)

Implementing JWT Authentication in Rust with Axum.

Simon Bittok — Fri, 31 Oct 2025 09:07:30 +0000

This is Part 2 of the "Implementing JWT Authentication in Rust" series.

Previous: Part 1: Project Setup and Configuration

Quick Recap

In Part 1, we set up our Rust project with Axum, configured environment-based settings, and created a basic error handling system. Now we'll add logging capabilities.

Introduction

Picking up from where we left off in Part 1, we will focus on setting up the infrastructure layer: logging with the tracing ecosystem.

Step 1: Install dependencies.

We will use the tracing ecosystem since they do provide the best logging facilities for asynchronous systems.

cargo add tracing-subscriber -F "env-filter, serde, tracing, json"
cargo add tracing -F log
cargo add tracing-error
cargo add tower-http -F "cors, trace"

Dependencies Overview

tower-http: Provides middleware utilities.
tracing: Provides structured, event-based, data collection and logging.
tracing-subscriber: Provides a subscriber for logging traces with reasonable defaults.
tracing-error: Utilities for enriching error handling with tracing diagnostic information.

Setting up Logging

Add the following to our development.yaml

log:
  level: debug # off, trace, debug, info, warn, error
  format: pretty # compacy, full, json, pretty
  crates:
    - auth # name of the project
    - axum
    - tower-http
    - tower

Create a config/log.rs file and add the following contents.

use std::{
    env::VarError,
    error::Error as _,
    fmt::{self, Display},
    io::IsTerminal,
    str::FromStr,
};

use serde::{Deserialize, Serialize};
use tracing::Subscriber;
use tracing_error::ErrorLayer;
use tracing_subscriber::{
    EnvFilter, Layer, filter::Directive, fmt::Layer as FmtLayer, layer::SubscriberExt,
    registry::LookupSpan, util::SubscriberInitExt,
};

use crate::{Error, Result};

#[derive(Debug, Deserialize, Serialize, Clone, Default)]
pub enum Level {
    #[serde(rename = "off")]
    Off,
    #[serde(rename = "trace")]
    Trace,
    #[serde(rename = "debug")]
    Debug,
    #[serde(rename = "info")]
    #[default]
    Info,
    #[serde(rename = "warn")]
    Warn,
    #[serde(rename = "error")]
    Error,
}

impl Display for Level {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "{}",
            match self {
                Self::Off => "off",
                Self::Trace => "trace",
                Self::Debug => "debug",
                Self::Info => "info",
                Self::Warn => "warn",
                Self::Error => "error",
            }
        )
    }
}

#[derive(Debug, Deserialize, Serialize, Clone, Default)]
pub enum Format {
    #[serde(rename = "compact")]
    Compact,
    #[serde(rename = "full")]
    Full,
    #[serde(rename = "json")]
    Json,
    #[serde(rename = "pretty")]
    #[default]
    Pretty,
}

impl Display for Format {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "{}",
            match self {
                Self::Compact => "compact",
                Self::Full => "full",
                Self::Json => "json",
                Self::Pretty => "pretty",
            }
        )
    }
}

#[derive(Debug, Deserialize, Clone)]
pub struct Logger {
    level: Level,
    format: Format,
    crates: Vec<String>,
}

impl Logger {
    pub fn setup(&self) -> Result<()> {
        let env_filter_layer = self.env_filter()?;
        let registry = tracing_subscriber::registry()
            .with(env_filter_layer)
            .with(ErrorLayer::default());

        match self.format {
            Format::Compact => registry.with(self.compact_fmt_layer()).try_init()?,
            Format::Full => registry.with(self.base_fmt_layer()).try_init()?,
            Format::Json => registry.with(self.json_fmt_layer()).try_init()?,
            Format::Pretty => registry.with(self.pretty_fmt_layer()).try_init()?,
        }

        Ok(())
    }

    fn env_filter(&self) -> Result<EnvFilter> {
        let mut env_filter = match EnvFilter::try_from_default_env() {
            Ok(env_filter) => env_filter,
            Err(from_env_err) => {
                if let Some(err) = from_env_err.source() {
                    match err.downcast_ref::<VarError>() {
                        Some(VarError::NotPresent) => (),
                        Some(other) => return Err(Error::EnvFilter(other.clone()).into()), // Converts into crate::Report
                        _ => return Err(Error::FromEnv(from_env_err).into()),
                    }
                }

                if self.crates.is_empty() {
                    EnvFilter::try_new(format!("{}={}", env!("CARGO_PKG_NAME"), &self.level))?
                } else {
                    EnvFilter::try_new("")?
                }
            }
        };

        let directives = self.directives()?;

        for directive in directives {
            env_filter = env_filter.add_directive(directive);
        }

        Ok(env_filter)
    }

    fn base_fmt_layer<S>(&self) -> FmtLayer<S>
    where
        S: Subscriber + for<'a> LookupSpan<'a>,
    {
        FmtLayer::new()
            .with_ansi(std::io::stderr().is_terminal())
            // TODO: Implement other writers
            .with_writer(std::io::stdout)
    }

    fn pretty_fmt_layer<S>(&self) -> impl Layer<S>
    where
        S: Subscriber + for<'a> LookupSpan<'a>,
    {
        self.base_fmt_layer().pretty()
    }

    fn json_fmt_layer<S>(&self) -> impl Layer<S>
    where
        S: Subscriber + for<'a> LookupSpan<'a>,
    {
        self.base_fmt_layer().json()
    }

    fn compact_fmt_layer<S>(&self) -> impl Layer<S>
    where
        S: Subscriber + for<'a> LookupSpan<'a>,
    {
        self.base_fmt_layer()
            .compact()
            .with_target(false)
            .with_thread_ids(false)
            .with_thread_names(false)
            .with_file(false)
            .with_line_number(false)
    }

    pub fn level(&self) -> &Level {
        &self.level
    }

    pub fn format(&self) -> &Format {
        &self.format
    }

    pub fn directives(&self) -> Result<Vec<Directive>> {
        self.crates
            .iter()
            .map(|c| -> Result<Directive> {
                let str_directive = format!("{}={}", c, &self.level);
                Ok(Directive::from_str(&str_directive)?)
            })
            .collect()
    }
}

The log module provides three key components:

Level & Format enums: Define log verbosity and output styling
Logger struct: Configures the tracing subscriber based on your YAML settings
env_filter(): Handles environment variable overrides for log levels.

The crates field specifies which crates to log. Without this, you'd see logs from ALL dependencies, creating noise. List only the crates you care about.

Now in our config struct add the log field as shown below.

#[derive(Debug, Deserialize, Clone)]
pub struct Config {
    server: ServerConfig,
    log: Logger,
}

impl Config {
// snip

 pub fn log(&self) -> &Logger {
     self.log
 }
}

Go to the Error enum and add the following variants.

#[derive(Debug, thiserror::Error)]
pub enum Error {
// rest of the content
    #[error(transparent)]
    DirectiveParseError(#[from] tracing_subscriber::filter::ParseError),
    #[error(transparent)]
    EnvFilter(#[from] std::env::VarError),
    #[error(transparent)]
    FromEnv(#[from] tracing_subscriber::filter::FromEnvError),
    #[error(transparent)]
    TryInit(#[from] tracing_subscriber::util::TryInitError),
}

Logging Middleware

Next create a middleware module directory & add a trace.rs file with the following content.
This middleware captures HTTP request/response details. It uses tracing "spans" to track the lifecycle of each request and records timing, status codes, and errors.

use std::{net::SocketAddr, time::Duration};

use axum::{
    body::Body,
    extract::ConnectInfo,
    http::{Request, Response},
};
use tower_http::classify::ServerErrorsFailureClass;
use tracing::{Span, field};

pub fn make_span_with(request: &Request<Body>) -> Span {
    tracing::error_span!(
        "<->",
        version = field::debug(request.version()),
        uri = field::display(request.uri()),
        method = field::display(request.method()),
        source = field::Empty,
        status = field::Empty,
        latency = field::Empty,
        error = field::Empty
    )
}

pub fn on_request(request: &Request<Body>, span: &Span) {
    span.record(
        "source",
        request
            .extensions()
            .get::<ConnectInfo<SocketAddr>>()
            .map_or_else(
                || field::display(String::from("<unkown>")),
                |connect_info| field::display(connect_info.ip().to_string()),
            ),
    );

    tracing::info!("Request");
}

pub fn on_response(response: &Response<Body>, latency: Duration, span: &Span) {
    span.record("status", field::display(response.status()));
    span.record(
        "latency",
        field::display(format!("{}µs", latency.as_millis())),
    );

    tracing::info!("Response");
}

pub fn on_failure(error: ServerErrorsFailureClass, latency: Duration, span: &Span) {
    span.record("error", field::display(error.to_string()));
    span.record(
        "latency",
        field::display(format!("{}µs", latency.as_millis())),
    );

    tracing::error!("Error on request");
}

Logging Layer.

Axum uses the .layer() method to attatch middlewares to routes. So head to the app.rs file, initialise the logger and starting logging HTTP Requests and Responses.

use std::io::IsTerminal;

use axum::{Router, routing::get};
use color_eyre::config::{HookBuilder, Theme};
use tokio::net::TcpListener;
use tower_http::trace::TraceLayer;

use crate::{Result, config::Config, middlewares::trace};

pub struct App;

impl App {
    pub async fn run() -> Result<()> {
        HookBuilder::default().theme(if std::io::stderr().is_terminal() {
            Theme::dark()
        } else {
            Theme::new()
        });

        let config = Config::load()?;

        config.log().setup()?;

        let router = Router::new()
            .route("/hello", get(|| async { "Hello World!" }))
            .layer(
                TraceLayer::new_for_http()
                    .make_span_with(trace::make_span_with)
                    .on_request(trace::on_request)
                    .on_response(trace::on_response)
                    .on_failure(trace::on_failure),
            );

        let listener = TcpListener::bind(config.server().address()).await?;

        tracing::info!("Listening on {}", config.server().url());

        axum::serve(listener, router).await.map_err(Into::into)
    }
}

The HookBuilder type uses a dark theme if the standard error is your terminal. The setup on the log initialises your log level (info, debug, error, etc) and format type (json, full, etc) and the crates you want to log their spans.

The TraceLayer uses four callbacks:
- make_span_with: Creates a new span for each request
- on_request: Records when a request arrives
- on_response: Logs successful responses with timing
- on_failure: Captures errors with diagnostic info

Restart your dev server and make a HTTP request to http://127.0.0.1:7150. If you have done everything right you should have logs like these.

You can play around with the log levels and formats, but for production environments, info level and JSON format is recommended written to an output file (might implement later).

What's Next?

With logging in place, we can now track our application's behavior. In Part 3, we'll set up PostgreSQL for user storage and implement the database layer.

This Series

Part 1: Project Setup & Configuration
Part 2: Implementing Logging (You are here)
Part 3: Database Setup with SQLx and PostgreSQL

Implementing JWT Authentication in Rust with Axum.

Simon Bittok — Thu, 30 Oct 2025 13:07:42 +0000

In this series, we'll build a backend service in Rust with JWT (JSON Web Token) authentication. We'll use the Axum framework for routing and SQLx for persistent storage with PostgreSQL.

I'll demonstrate how to implement RSA (Rivest-Shamir-Adleman) encryption to create both access and refresh tokens for route protection. RSA uses asymmetric cryptography with a public-private key pair to sign and verify tokens, providing robust security for your authentication system.

Implementation

Full source code is here

Part 1: Project Setup and Configuration

Getting Started

First, create a new project using Cargo:

cargo new axum-auth

I prefer organizing my project by placing main.rs inside a src/bin/ directory and creating a lib.rs file in the src/ directory to hold module declarations. This separation keeps the codebase organized as it grows.

Next install the required dependencies.

cargo add axum -F macros
cargo add tokio -F full
cargo add color-eyre
cargo add config -F yaml
cargo add thiserror
cargo add serde -F derive
cargo add serde-json
cargo add tracing -F log
cargo add tracing-subscriber -F "env-filter, serde, tracing, json"
cargo add tracing-error

Dependency Overview

axum: Web framework with the macros feature for routing utilities
tokio: Async runtime with the full feature set
color-eyre: Enhanced error reporting
thiserror: Ergonomic error type derivation
config: Read configuration files & deserialize to Rust data structures.
serde: A serialization/deserialization library.
tracing, tracing-subscriber, tracing-error: Will provide logging utilities.

Setting up Error Handling

We need a unified error handling for our project. Create an error/mod.rs file and add the following code.

use std::fmt::{self, Display};

#[derive(Debug)]
pub struct Report(pub color_eyre::Report);

impl<E> From<E> for Report
where
    E: Into<color_eyre::Report>,
{
    fn from(err: E) -> Self {
        Self(err.into())
    }
}

impl Display for Report {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.0.fmt(f)
    }
}

pub type Result<T, E = Report> = std::result::Result<T, E>;

#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error(transparent)]
    Axum(#[from] axum::Error),
    #[error(transparent)]
    Config(#[from] config::ConfigError),
    #[error(transparent)]
    IOError(#[from] std::io::Error),
}

The thiserror crate provides the Error trait, which automatically implements both the Display trait and From<E> conversions for our error types. This gives us easy and efficient (ergonomic) error handling with automatic conversion from underlying error types.

The color_eyre::Report type serves as our catch-all error wrapper. It can accept any error that implements std::error::Error, providing enhanced error reporting with backtraces and color-formatted output. By wrapping it in our own Report struct, we can handle both our explicitly defined errors (in the Error enum) and any other errors from third-party libraries without compilation issues.

Exporting Error & Result Type

In the lib.rs file add the following content after your module declarations.

pub use self::error::{Error, Result};

Configuration

The 12 factor app methodology recommends we seperate configuration from code, so that we can easily modify without recompilation, especially taking into account Rust compile time ;).

We will read configs from environment-specific configuration files. This approach allows us to maintain different configurations for development, production, and testing environments.

Create a config folder parallel to the src/ directory then, create a development.yaml file inside it and add the following content.

server:
  protocol: http
  host: 127.0.0.1
  port: 7150

Next create a config/mod.rs inside the src/ dir and add the following.

use serde::Deserialize;

use crate::Result;

#[derive(Debug, Deserialize, Clone)]
pub struct ServerConfig {
    protocol: String,
    host: String,
    port: u16,
}

impl ServerConfig {
    pub fn address(&self) -> String {
        format!("{}:{}", &self.host, &self.port)
    }

    pub fn url(&self) -> String {
        format!("{}://{}", &self.protocol, self.address())
    }
}

#[derive(Debug, Deserialize, Clone)]
pub struct Config {
    server: ServerConfig,
}

impl Config {
    pub fn load() -> Result<Self> {
        let env = Environment::current();
        Self::from_env(&env)
    }

    /// Load configuration for a specific environment
    ///
    /// If environment variables are set with prefix APP_, it will also read them
    /// e.g. APP_CONFIG__PORT=5000
    pub fn from_env(env: &Environment) -> Result<Self> {
        let base_dir = std::env::current_dir()?;
        let config_dir = base_dir.join("config");

        let file_name = format!("{}.yaml", env);

        let settings = config::Config::builder()
            .add_source(config::File::from(config_dir.join(file_name)))
            .add_source(
                config::Environment::with_prefix("APP")
                    .separator("__")
                    .prefix_separator("_"),
            )
            .build()?;

        settings.try_deserialize::<Self>().map_err(Into::into)
    }

    pub fn server(&self) -> &ServerConfig {
        &self.server
    }
}

#[derive(Debug, Deserialize, Clone, Default)]
pub enum Environment {
    #[default]
    Development,
    Production,
    Testing,
    Other(String),
}

impl Environment {
    /// Get the current environment from environment variables
    ///
    /// Checks `APP_ENVIRONMENT` then `APP_ENV`, defaults to Development
    pub fn current() -> Self {
        std::env::var("APP_ENVIRONMENT")
            .or_else(|_| std::env::var("APP_ENV"))
            .map(|s| Self::from(s.as_str()))
            .unwrap_or_default()
    }
}

impl From<&str> for Environment {
    fn from(s: &str) -> Self {
        match s.to_lowercase().trim() {
            "development" | "dev" => Environment::Development,
            "production" | "prod" => Environment::Production,
            "testing" | "test" => Environment::Testing,
            other => Environment::Other(other.into()),
        }
    }
}

impl std::fmt::Display for Environment {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "{}",
            match self {
                Self::Development => "development",
                Self::Production => "production",
                Self::Testing => "testing",
                Self::Other(other) => other.as_str(),
            }
        )
    }
}

Understanding the Configuration System.

ServerConfig struct holds the server connection details. It provides two helper methods: address() which formats the host and port for binding (e.g., 127.0.0.1:7150), and url() which creates the full server URL (e.g., http://127.0.0.1:7150).

Config struct is the root configuration container. The load() method automatically detects the current environment and loads the appropriate configuration file. The from_env() method loads configuration from a YAML file based on the environment name and can be overridden by environment variables prefixed with APP_ (using double underscores as separators, e.g., APP_SERVER__PORT=8080). As the app grows we will add more fields to this struct.

Environment enum represents the application's runtime environment. The current() method reads the environment from APP_ENVIRONMENT or APP_ENV environment variables, defaulting to Development if neither is set. The From<&str> implementation provides flexible parsing, accepting variations like "dev"/"development" or "prod"/"production", and includes an Other variant for custom environment names.

The App struct

Create a new file app.rs inside src/ and add the following.

use axum::{Router, routing::get};
use tokio::net::TcpListener;

use crate::{Result, config::Config};

pub struct App;

impl App {
    pub async fn run() -> Result<()> {
        let config = Config::load()?;

        let router = Router::new().route("/hello", get(|| async { "Hello World!" }));

        let listener = TcpListener::bind(config.server().address()).await?;

        axum::serve(listener, router).await.map_err(Into::into)
    }
}

Export App Struct

Inside the lib.rs export the App type like so.

pub use self::{
    app::App,
    error::{Error, Result},
};

Run the App

Then call the App::run function inside the bin/main.rs file.

use auth::{App, Result}; //ensure to export App & Result from the lib.rs file

#[tokio::main]
async fn main() -> Result<()> {
    App::run().await
}

With that now we no longer need to touch our main.rs file.

Run the application and then test the endpoint using cURL or the browser at http:127.0.0.1:7150/hello. You should get response Hello from axum.

In the next part we will implement logging.

This Series

Part 1: Project Setup & Configuration (you are here)

Create Animated Borders Using Only CSS.

Simon Bittok — Mon, 27 Oct 2025 13:11:43 +0000

I first noticed animated borders on deno.com a while back. Their feature cards had these smooth, glowing green lines moving around the edges. I thought to myself,

“Wow… that must be some incredibly complex Javascript magic.”

I promised myself that one day I’d learn how to build something just as cool.

Turns out… you can create animated borders using only HTML and CSS and it’s way easier than I expected.

Before we embark on this will be our final product.

Starting Up

Lets begin with some basic HTML.

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Animated Borders</title>
    </head>
    <body>
        <div class="card"></div>
    </body>

</html>

Create a CSS file, link it to our HTML and some basic styling to the body & the box:

<link rel="stylesheet" href="index.css" >

body {
    background: oklch(0.1743 0.0227 283.7998);
    margin: 0;
    padding: 0;
    height: 100svh;
    display: flex;
    justify-content: center;
    align-items: center;
}

.card {
    height: 400px;
    aspect-ratio: 1/1;
    background: oklch(0.2284 0.0384 282.9324);
    border-radius: 12px;
}

CSS After & Before Pseudo Elements

MDN docs by mozilla says the following about CSS pseudo elements.

A CSS pseudo-element is a keyword added to a selector that lets you style a specific part of the selected element(s).

So from my understanding pseudo elements help you to style specific elements without additional HTML.

We'll create a new visual layer behind the card using ::before

.card::before {
    content: "";
    height: 100%;
    width: 100%;
    background: conic-gradient(
        from 0deg at center,
        red,
        orange,
        blue,
        purple,
        red
    );
    position: absolute;
    z-index: -2;
    border-radius: inherit;
    padding: 2px;

}

.card {
/* add the following styles to the card */
    position: relative;
    display: flex;
    justify-content: center;
    align-items: center;

}

The padding on the ::before pseudo element serves as our border, you can make it as thick as you wish (or as thin). You will now see a colourful border around the card.

Now to make the "border" animated we now employ the sibling to ::before pseudo element, the ::after pseudo element.

The latter works exactly as the former element, so just add it to the existing ::before element and separate them with a comma.

We will use it to give our 'border' a softer glow.

.card::before, .card::after {}
.card::after {
    filter: blur(8px); /* gives a softer effect. */
}

@propery rule

We define a CSS variable --angle for controlling the gradient rotation:

@property --angle {
    syntax: "<angle>";
    initial-value: 0deg;
    inherits: true;

}

.card::before, .card::after {
    background: conic-gradient(
        from var(--angle) at center,
        red,
        orange,
        blue,
        purple,
        red
    );
/* as it were */
}

@keyframes rule

The conic gradient now rotates a full circle every 4 seconds!
Feel free to tweak the speed or colours to your heart desires.

.card::before, .card::after {
/* as it were */
    animation: rotate 4s linear infinite;
}

@keyframes rotate {
    to {
        --angle: 360deg;
    }

}

Note

The @property rule is currently best supported in Chromium browsers. If you need broader compatibility, you can animate using other techniques such as transform or animating a mask.

Full Source Code

Source code

If you build something cool with this idea, drop a link.
I’d love to check it out!
If you also have any suggestions or recommendations feel free to reach out.
Follow me for more beginner-friendly CSS UI tricks