Crate axum_token_auth 

This crate implements middleware to authenticate requests to axum. Overall the aim is to provide simple, passwordless authentication for secure network communication. A session key is stored in a cookie and signed with a secret (using crypto implementations in the tower-cookies crate). Due to the signature, the session key cannot be modified. Aside from storing the secret, the system is stateless, requiring no storage on the server.

In the normal case, a token is provided out-of-band to the user. For example, the user will start the server from an SSH session and copy the token to their browser. Alternatively, if the connection is defined as trusted (see “Trusted connection flow”, below), authentication occurs without any check.

This is useful in cases where a user launches a server process and wants to achieve network-based control of the server without the server exposing this functionality to unauthenticated network connections. In this scenario, if the user provides the correct token in the URL upon initial connection, the server sets a cookie in the user’s browser and subsequent requests are automatically validated with no further token in the URL.

The user does not need an account, Passkey, OpenID Connect (OIDC), OAuth, OAuth2, FIDO U2F, FIDO2, WebAuthn, SAML, LDAP, Kerberos, RADIUS, or SSO credentials. The developer also does not need to configure these services. Rather, the user uses a URL with the correct token in the query parameters when initially connecting to the server.

Typical flow

1. A user starts or connects to a server and the user is given an initial authentication token, minted with AuthConfig::generate_token. (For example, the server prints or shows a QR code containing a URL. The URL includes the token.) The token is signed with the persistent secret and carries its own expiry, so the server validates it without storing any per-token state.
2. The user connects via a browser to the server. In the first HTTP request from the user, the token is included in the query parameter in the URL.
3. A new SessionKey is included as a new cookie in the HTTP response to the user. The cookie is stored by the user’s browser. On the server, the request is further processed by the next service with session key information being made available.
4. Subsequent requests from the user browser include the newly set cookie (and no longer include the token in the URL) and the middleware makes the session key information available to the next service.

Trusted connection flow

In case of a trusted connection, no token is required for initial authentication. The session key is still issued as above. A “trusted connection” is defined by setting AuthConfig::token_config to None. This is useful when the server is only accessible on a loopback interface.

Trusted networks (overlay VPNs)

Where setting AuthConfig::token_config to None trusts every connection, AuthConfig::trusted_networks trusts individual clients by their network address: a request whose immediate peer address falls in one of the configured ranges is authenticated without a token, just like a trusted connection.

This is intended for a server fronted by an authenticated, encrypted overlay network — for example Tailscale (whose addresses lie in 100.64.0.0/10) or a WireGuard subnet — where the overlay has already authenticated the peer, so an application token would be redundant. The peer address is taken from the ConnectInfo<SocketAddr> request extension, so the server must be run with into_make_service_with_connect_info; if that extension is absent the client is treated as untrusted.

Because the address checked is the immediate TCP peer, the configured ranges must not be reachable through an intermediate reverse proxy, which would make every client appear to originate from the proxy.

Session expiration and renewal

Session lifetime is controlled by AuthConfig::session_expires.

If it is None, issued sessions never expire on their own: a cookie’s signature is valid until the persistent secret is changed, and the cookie is a browser “session cookie” (no Expires attribute), saved only until the browser quits. To invalidate every session at once, change the persistent secret.

If it is Some(ttl), the issue time plus ttl is embedded in the (signed, tamper-proof) cookie and enforced by the server, so an expired cookie stops being accepted even if the client keeps presenting it. The same instant is written to the cookie’s browser-side Expires attribute. The expiry slides forward whenever a request arrives past the halfway point of the session’s lifetime, so a regularly-returning client keeps a valid session indefinitely without ever needing the token again — including past the ~400 day cap browsers place on any single cookie’s lifetime. A client that stays away longer than ttl must re-authenticate with a token.

Cookie security attributes

The session cookie’s Secure, HttpOnly, and SameSite attributes are configurable via AuthConfig::cookie_secure, AuthConfig::cookie_http_only, and AuthConfig::cookie_same_site. The defaults (HttpOnly on, SameSite=Strict, Secure off) are safe for the common loopback/HTTP deployment; set cookie_secure to true when serving over HTTPS.

Removing the token from the URL after login

A token left in the address bar can leak through browser history, bookmarks, or Referer headers. When AuthConfig::strip_token_redirect is enabled (the default), a top-level browser navigation (a GET whose Accept header includes text/html) that authenticates with a token in the query is answered with a redirect to the same location minus the token parameter. The session cookie is set on that redirect, so the follow-up request is already authenticated and never carries the token. Non-browser clients (which do not send Accept: text/html) are served normally, so callers that pass a token on every request are unaffected.

For more extensive needs

If this crate does not meet your needs, check axum-login.

Structs

AuthConfig

Configuration for AuthLayer and AuthMiddleware.

AuthLayer

Implements Layer for AuthMiddleware

AuthMiddleware

Middleware which checks if request is authenticated and, if so, extends the request to include SessionKey information.

CidrBlock

A CIDR network range — an IP address paired with a prefix length — used to populate AuthConfig::trusted_networks.

CidrParseError

Error returned when a string cannot be parsed as a CidrBlock.

Key

A cryptographic master key for use with Signed and/or Private jars.

SessionKey

Identifier for each session (one per client browser).

TokenConfig

Configuration for URI query parameters to implement token-based authentication.

ValidationErrors

One or more validation errors

Enums

SameSite

The SameSite cookie attribute.

Functions

generate_token

Mint a self-expiring authentication token valid for ttl from now, signed with secret.