axum-token-auth

axum-token-auth is middleware to authenticate requests to axum.

More information about this crate can be found in the crate documentation.

License

This project is licensed under the MIT license.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in axum-token-auth by you, shall be licensed as MIT, without any additional terms or conditions.

lib.rs:

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 (e.g. if it is a loopback connection), 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. (For example, the server prints or shows a QR code containing a URL. The URL includes the token.)
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.

Cookie expiration

The cookies stored on the clients' browser can be persisted (the response sets a cookie with an Expires field) or they can be "session cookies". If the expires field in [AuthConfig] is set to None, a successful auth will set a "session cookie", meaning the cookie does not contain an Expires or Max-age key. Otherwise, when the expires field is set, browsers will store the cookie persistently. (Note that this expiry information cannot be used for security purposes as it is entirely controlled by the clients' browser.)

Session Key expiration

The signature on the cookies containing session keys is valid until the persistent secret is changed. (If you need to invalidate keys, switch the persistent secret or use a more full-featured authentication middleware.)

For more extensive needs

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