3 releases
0.1.2 | Oct 11, 2024 |
---|---|
0.1.1 | Jan 21, 2024 |
0.1.0 | Jan 20, 2024 |
#234 in Authentication
860 downloads per month
22KB
315 lines
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
- 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.)
- 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.
- 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.
- 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
.
Dependencies
~9–16MB
~208K SLoC