1/*

2Package webauth handles authentication and session/csrf token management for

3the web interfaces (admin, account, mail).

4

5Authentication of web requests is through a session token in a cookie. For API

6requests, and other requests where the frontend can send custom headers, a

7header ("x-mox-csrf") with a CSRF token is also required and verified to belong

8to the session token. For other form POSTS, a field "csrf" is required. Session

9tokens and CSRF tokens are different randomly generated values. Session cookies

10are "httponly", samesite "strict", and with the path set to the root of the

11webadmin/webaccount/webmail. Cookies set over HTTPS are marked "secure".

12Cookies don't have an expiration, they can be extended indefinitely by using

13them.

14

15To login, a call to LoginPrep must first be made. It sets a random login token

16in a cookie, and returns it. The loginToken must be passed to the Login call,

17along with login credentials. If the loginToken is missing, the login attempt

18fails before checking any credentials. This should prevent third party websites

19from tricking a browser into logging in.

20

21Sessions are stored server-side, and their lifetime automatically extended each

22time they are used. This makes it easy to invalidate existing sessions after a

23password change, and keeps the frontend free from handling long-term vs

24short-term sessions.

25

26Sessions for the admin interface have a lifetime of 12 hours after last use,

27are only stored in memory (don't survive a server restart), and only 10

28sessions can exist at a time (the oldest session is dropped).

29

30Sessions for the account and mail interfaces have a lifetime of 24 hours after

31last use, are kept in memory and stored in the database (do survive a server

32restart), and only 100 sessions can exist per account (the oldest session is

33dropped).

34*/

35package webauth

36

37import (

38 "context"

39 "encoding/json"

40 "fmt"

41 "log/slog"

42 "net"

43 "net/http"

44 "net/url"

45 "strings"

46 "time"

47

48 "golang.org/x/text/unicode/norm"

49

50 "github.com/mjl-/sherpa"

51

52 "github.com/mjl-/mox/metrics"

53 "github.com/mjl-/mox/mlog"

54 "github.com/mjl-/mox/mox-"

55 "github.com/mjl-/mox/store"

56)

57

58// Delay before responding in case of bad authentication attempt.

59var BadAuthDelay = time.Second

60

61// SessionAuth handles login and session storage, used for both account and

62// admin authentication.

63type SessionAuth interface {

64 // Login verifies the password. Valid indicates the attempt was successful. If

65 // disabled is true, the error must be non-nil and contain details.

66 login(ctx context.Context, log mlog.Log, username, password string) (valid bool, disabled bool, accountName string, rerr error)

67

68 // Add a new session for account and login address.

69 add(ctx context.Context, log mlog.Log, accountName string, loginAddress string) (sessionToken store.SessionToken, csrfToken store.CSRFToken, rerr error)

70

71 // Use an existing session. If csrfToken is empty, no CSRF check must be done.

72 // Otherwise the CSRF token must be associated with the session token, as returned

73 // by add. If the token is not valid (e.g. expired, unknown, malformed), an error

74 // must be returned.

75 use(ctx context.Context, log mlog.Log, accountName string, sessionToken store.SessionToken, csrfToken store.CSRFToken) (loginAddress string, rerr error)

76

77 // Removes a session, invalidating any future use. Must return an error if the

78 // session is not valid.

79 remove(ctx context.Context, log mlog.Log, accountName string, sessionToken store.SessionToken) error

80}

81

82// loginAttempt initializes a loginAttempt, for adding to the store after filling in the results and other details.

83func loginAttempt(r *http.Request, protocol, authMech string) store.LoginAttempt {

84 remoteIP, _, _ := net.SplitHostPort(r.RemoteAddr)

85 if remoteIP == "" {

86 remoteIP = r.RemoteAddr

87 }

88

89 return store.LoginAttempt{

90 RemoteIP: remoteIP,

91 TLS: store.LoginAttemptTLS(r.TLS),

92 Protocol: protocol,

93 AuthMech: authMech,

94 UserAgent: r.UserAgent(),

95 Result: store.AuthError, // Replaced by caller.

96 }

97}

98

99// Check authentication for a request based on session token in cookie and matching

100// csrf in case requireCSRF is set (from header, unless formCSRF is set). Also

101// performs rate limiting.

102//

103// If the returned boolean is true, the request is authenticated. If the returned

104// boolean is false, an HTTP error response has already been returned. If rate

105// limiting applies (after too many failed authentication attempts), an HTTP status

106// 429 is returned. Otherwise, for API requests an error object with either code

107// "user:noAuth" or "user:badAuth" is returned. Other unauthenticated requests

108// result in HTTP status 403.

109//

110// sessionAuth verifies login attempts and handles session management.

111//

112// kind is used for the cookie name (webadmin, webaccount, webmail), and for

113// logging/metrics.

114func 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) {

115 // Respond with an authentication error.

116 respondAuthError := func(code, msg string) {

117 if isAPI {

118 w.Header().Set("Content-Type", "application/json; charset=utf-8")

119 var result = struct {

120 Error sherpa.Error `json:"error"`

121 }{

122 sherpa.Error{Code: code, Message: msg},

123 }

124 err := json.NewEncoder(w).Encode(result)

125 log.Check(err, "writing error response")

126 } else {

127 http.Error(w, "403 - forbidden - "+msg, http.StatusForbidden)

128 }

129 }

130

131 // The frontends cannot inject custom headers for all requests, e.g. images loaded

132 // as resources. For those, we don't require the CSRF and rely on the session

133 // cookie with samesite=strict.

134 // todo future: possibly get a session-tied value to use in paths for resources, and verify server-side that it matches the session token.

135 var csrfValue string

136 if requireCSRF && postFormCSRF {

137 csrfValue = r.PostFormValue("csrf")

138 } else {

139 csrfValue = r.Header.Get("x-mox-csrf")

140 }

141 csrfToken := store.CSRFToken(csrfValue)

142 if requireCSRF && csrfToken == "" {

143 respondAuthError("user:noAuth", "missing required csrf header")

144 return "", "", "", false

145 }

146

147 // Cookies are named "webmailsession", "webaccountsession", "webadminsession".

148 cookie, _ := r.Cookie(kind + "session")

149 if cookie == nil {

150 respondAuthError("user:noAuth", fmt.Sprintf("no session for %q web interface", strings.TrimPrefix(kind, "web")))

151 return "", "", "", false

152 }

153

154 ip := RemoteIP(log, isForwarded, r)

155 if ip == nil {

156 respondAuthError("user:noAuth", "cannot find ip for rate limit check (missing x-forwarded-for header?)")

157 return "", "", "", false

158 }

159 start := time.Now()

160 if !mox.LimiterFailedAuth.Add(ip, start, 1) {

161 metrics.AuthenticationRatelimitedInc(kind)

162 http.Error(w, "429 - too many auth attempts", http.StatusTooManyRequests)

163 return

164 }

165

166 la := loginAttempt(r, kind, "websession")

167 defer func() {

168 store.LoginAttemptAdd(context.Background(), log, la)

169 }()

170

171 // Cookie values are of the form: token SP accountname.

172 // For admin sessions, the accountname is empty (there is no login address either).

173 t := strings.SplitN(cookie.Value, " ", 2)

174 if len(t) != 2 {

175 time.Sleep(BadAuthDelay)

176 respondAuthError("user:badAuth", "malformed session")

177 return "", "", "", false

178 }

179 sessionToken = store.SessionToken(t[0])

180

181 var err error

182 accountName, err = url.QueryUnescape(t[1])

183 if err != nil {

184 time.Sleep(BadAuthDelay)

185 respondAuthError("user:badAuth", "malformed session account name")

186 return "", "", "", false

187 }

188 la.AccountName = accountName

189

190 loginAddress, err = sessionAuth.use(ctx, log, accountName, sessionToken, csrfToken)

191 if err != nil {

192 la.Result = store.AuthBadCredentials

193 time.Sleep(BadAuthDelay)

194 respondAuthError("user:badAuth", err.Error())

195 return "", "", "", false

196 }

197 la.LoginAddress = loginAddress

198

199 mox.LimiterFailedAuth.Reset(ip, start)

200 la.Result = store.AuthSuccess

201

202 // Add to HTTP logging that this is an authenticated request.

203 if lw, ok := w.(interface{ AddAttr(a slog.Attr) }); ok {

204 lw.AddAttr(slog.String("authaccount", accountName))

205 }

206 return accountName, sessionToken, loginAddress, true

207}

208

209func RemoteIP(log mlog.Log, isForwarded bool, r *http.Request) net.IP {

210 if isForwarded {

211 s := r.Header.Get("X-Forwarded-For")

212 ipstr := strings.TrimSpace(strings.Split(s, ",")[0])

213 return net.ParseIP(ipstr)

214 }

215

216 host, _, _ := net.SplitHostPort(r.RemoteAddr)

217 return net.ParseIP(host)

218}

219

220func isHTTPS(isForwarded bool, r *http.Request) bool {

221 if isForwarded {

222 return r.Header.Get("X-Forwarded-Proto") == "https"

223 }

224 return r.TLS != nil

225}

226

227// LoginPrep is an API call that returns a loginToken and also sets it as cookie

228// with the same value. The loginToken must be passed to a subsequent call to

229// Login, which will check that the loginToken and cookie are both present and

230// match before checking the actual login attempt. This would prevent a third party

231// site from triggering login attempts by the browser.

232func LoginPrep(ctx context.Context, log mlog.Log, kind, cookiePath string, isForwarded bool, w http.ResponseWriter, r *http.Request, token string) {

233 // todo future: we could sign the login token, and verify it on use, so subdomains cannot set it to known values.

234

235 http.SetCookie(w, &http.Cookie{

236 Name: kind + "login",

237 Value: token,

238 Path: cookiePath,

239 Secure: isHTTPS(isForwarded, r),

240 HttpOnly: true,

241 SameSite: http.SameSiteStrictMode,

242 MaxAge: 30, // Only for one login attempt.

243 })

244}

245

246// Login handles a login attempt, checking against the rate limiter, verifying the

247// credentials through sessionAuth, and setting a session token cookie on the HTTP

248// response and returning the associated CSRF token.

249//

250// In case of a user error, a *sherpa.Error is returned that sherpa handlers can

251// pass to panic. For bad credentials, the error code is "user:loginFailed".

252func 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) {

253 loginCookie, _ := r.Cookie(kind + "login")

254 if loginCookie == nil || loginCookie.Value != loginToken {

255 msg := "missing login token cookie"

256 if isForwarded && loginCookie == nil {

257 msg += " (hint: reverse proxy must keep path, for login cookie)"

258 }

259 return "", &sherpa.Error{Code: "user:error", Message: msg}

260 }

261

262 ip := RemoteIP(log, isForwarded, r)

263 if ip == nil {

264 return "", fmt.Errorf("cannot find ip for rate limit check (missing x-forwarded-for header?)")

265 }

266 start := time.Now()

267 if !mox.LimiterFailedAuth.Add(ip, start, 1) {

268 metrics.AuthenticationRatelimitedInc(kind)

269 return "", &sherpa.Error{Code: "user:error", Message: "too many authentication attempts"}

270 }

271

272 username = norm.NFC.String(username)

273 valid, disabled, accountName, err := sessionAuth.login(ctx, log, username, password)

274 la := loginAttempt(r, kind, "weblogin")

275 la.LoginAddress = username

276 la.AccountName = accountName

277 defer func() {

278 store.LoginAttemptAdd(context.Background(), log, la)

279 }()

280 if disabled {

281 la.Result = store.AuthLoginDisabled

282 return "", &sherpa.Error{Code: "user:loginFailed", Message: err.Error()}

283 } else if err != nil {

284 la.Result = store.AuthError

285 return "", fmt.Errorf("evaluating login attempt: %v", err)

286 } else if !valid {

287 time.Sleep(BadAuthDelay)

288 la.Result = store.AuthBadCredentials

289 return "", &sherpa.Error{Code: "user:loginFailed", Message: "invalid credentials"}

290 }

291 la.Result = store.AuthSuccess

292 mox.LimiterFailedAuth.Reset(ip, start)

293

294 sessionToken, csrfToken, err := sessionAuth.add(ctx, log, accountName, username)

295 if err != nil {

296 la.Result = store.AuthError

297 log.Errorx("adding session after login", err)

298 return "", fmt.Errorf("adding session: %v", err)

299 }

300

301 // Add session cookie.

302 http.SetCookie(w, &http.Cookie{

303 Name: kind + "session",

304 // Cookies values are ascii only, so we keep the account name query escaped.

305 Value: string(sessionToken) + " " + url.QueryEscape(accountName),

306 Path: cookiePath,

307 Secure: isHTTPS(isForwarded, r),

308 HttpOnly: true,

309 SameSite: http.SameSiteStrictMode,

310 // We don't set a max-age. These makes cookies per-session. Browsers are rarely

311 // restarted nowadays, and they have "continue where you left off", keeping session

312 // cookies. Our sessions are only valid for max 1 day. Convenience can come from

313 // the browser remembering the password.

314 })

315 // Remove cookie used during login.

316 http.SetCookie(w, &http.Cookie{

317 Name: kind + "login",

318 Path: cookiePath,

319 Secure: isHTTPS(isForwarded, r),

320 HttpOnly: true,

321 SameSite: http.SameSiteStrictMode,

322 MaxAge: -1, // Delete cookie

323 })

324 return csrfToken, nil

325}

326

327// Logout removes the session token through sessionAuth, and clears the session

328// cookie through the HTTP response.

329func 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 {

330 err := sessionAuth.remove(ctx, log, accountName, sessionToken)

331 if err != nil {

332 return fmt.Errorf("removing session: %w", err)

333 }

334

335 http.SetCookie(w, &http.Cookie{

336 Name: kind + "session",

337 Path: cookiePath,

338 Secure: isHTTPS(isForwarded, r),

339 HttpOnly: true,

340 SameSite: http.SameSiteStrictMode,

341 MaxAge: -1, // Delete cookie.

342 })

343 return nil

344}

345