Documentation
¶
Overview ¶
Package webauth handles authentication and session/csrf token management for the web interfaces (admin, account, mail).
Authentication of web requests is through a session token in a cookie. For API requests, and other requests where the frontend can send custom headers, a header ("x-mox-csrf") with a CSRF token is also required and verified to belong to the session token. For other form POSTS, a field "csrf" is required. Session tokens and CSRF tokens are different randomly generated values. Session cookies are "httponly", samesite "strict", and with the path set to the root of the webadmin/webaccount/webmail. Cookies set over HTTPS are marked "secure". Cookies don't have an expiration, they can be extended indefinitely by using them.
To login, a call to LoginPrep must first be made. It sets a random login token in a cookie, and returns it. The loginToken must be passed to the Login call, along with login credentials. If the loginToken is missing, the login attempt fails before checking any credentials. This should prevent third party websites from tricking a browser into logging in.
Sessions are stored server-side, and their lifetime automatically extended each time they are used. This makes it easy to invalidate existing sessions after a password change, and keeps the frontend free from handling long-term vs short-term sessions.
Sessions for the admin interface have a lifetime of 12 hours after last use, are only stored in memory (don't survive a server restart), and only 10 sessions can exist at a time (the oldest session is dropped).
Sessions for the account and mail interfaces have a lifetime of 24 hours after last use, are kept in memory and stored in the database (do survive a server restart), and only 100 sessions can exist per account (the oldest session is dropped).
Index ¶
- Variables
- func Check(ctx context.Context, log mlog.Log, sessionAuth SessionAuth, kind string, ...) (accountName string, sessionToken store.SessionToken, loginAddress string, ...)
- func Login(ctx context.Context, log mlog.Log, sessionAuth SessionAuth, ...) (store.CSRFToken, error)
- func LoginPrep(ctx context.Context, log mlog.Log, kind, cookiePath string, isForwarded bool, ...)
- func Logout(ctx context.Context, log mlog.Log, sessionAuth SessionAuth, ...) error
- func RemoteIP(log mlog.Log, isForwarded bool, r *http.Request) net.IP
- type SessionAuth
Constants ¶
This section is empty.
Variables ¶
var BadAuthDelay = time.Second
Delay before responding in case of bad authentication attempt.
Functions ¶
func Check ¶
func Check(ctx context.Context, log mlog.Log, sessionAuth SessionAuth, kind string, isForwarded bool, w http.ResponseWriter, r *http.Request, isAPI, requireCSRF, postFormCSRF bool) (accountName string, sessionToken store.SessionToken, loginAddress string, ok bool)
Check authentication for a request based on session token in cookie and matching csrf in case requireCSRF is set (from header, unless formCSRF is set). Also performs rate limiting.
If the returned boolean is true, the request is authenticated. If the returned boolean is false, an HTTP error response has already been returned. If rate limiting applies (after too many failed authentication attempts), an HTTP status 429 is returned. Otherwise, for API requests an error object with either code "user:noAuth" or "user:badAuth" is returned. Other unauthenticated requests result in HTTP status 403.
sessionAuth verifies login attempts and handles session management.
kind is used for the cookie name (webadmin, webaccount, webmail), and for logging/metrics.
func Login ¶
func Login(ctx context.Context, log mlog.Log, sessionAuth SessionAuth, kind, cookiePath string, isForwarded bool, w http.ResponseWriter, r *http.Request, loginToken, username, password string) (store.CSRFToken, error)
Login handles a login attempt, checking against the rate limiter, verifying the credentials through sessionAuth, and setting a session token cookie on the HTTP response and returning the associated CSRF token.
In case of a user error, a *sherpa.Error is returned that sherpa handlers can pass to panic. For bad credentials, the error code is "user:loginFailed".
func LoginPrep ¶
func LoginPrep(ctx context.Context, log mlog.Log, kind, cookiePath string, isForwarded bool, w http.ResponseWriter, r *http.Request, token string)
LoginPrep is an API call that returns a loginToken and also sets it as cookie with the same value. The loginToken must be passed to a subsequent call to Login, which will check that the loginToken and cookie are both present and match before checking the actual login attempt. This would prevent a third party site from triggering login attempts by the browser.
func Logout ¶
func Logout(ctx context.Context, log mlog.Log, sessionAuth SessionAuth, kind, cookiePath string, isForwarded bool, w http.ResponseWriter, r *http.Request, accountName string, sessionToken store.SessionToken) error
Logout removes the session token through sessionAuth, and clears the session cookie through the HTTP response.
Types ¶
type SessionAuth ¶
type SessionAuth interface {
// contains filtered or unexported methods
}
SessionAuth handles login and session storage, used for both account and admin authentication.
var Accounts SessionAuth = accountSessionAuth{}
AccountAuth is for user accounts, with username/password, and sessions stored in memory and in the database with lifetimes that are automatically extended.
var Admin SessionAuth = &adminSessionAuth{ sessions: map[store.SessionToken]adminSession{}, }
Admin is for admin logins, with authentication by password, and sessions only stored in memory only, with lifetime 12 hour after last use, with a maximum of 10 active sessions.
Source Files