server: clean up authentication handler code a bit

Including
- more comments
- rename `maybeAuthMux` to `authenticatedUIHandler`
- move `authHandler` down near where it's initialized

Release note: None

pkg/server/authentication.go

@@ -327,6 +327,13 @@ type authenticationMux struct {
 	server *authenticationServer
 	inner  http.Handler
 
+	// allowAnonymous, if true, indicates that the authentication mux should
+	// call its inner HTTP handler even if the request doesn't have a valid
+	// session. If there is a valid session, the mux calls its inner handler
+	// with a context containing the username and session ID.
+	//
+	// If allowAnonymous is false, the mux returns an error if there is no
+	// valid session.
 	allowAnonymous bool
 }
 

pkg/server/server.go

@@ -1254,11 +1254,6 @@ func (s *Server) Start(ctx context.Context) error {
 	gwCtx, gwCancel := context.WithCancel(s.AnnotateCtx(context.Background()))
 	s.stopper.AddCloser(stop.CloserFn(gwCancel))
 
-	var authHandler http.Handler = gwMux
-	if s.cfg.RequireWebSession() {
-		authHandler = newAuthenticationMux(s.authentication, authHandler)
-	}
-
 	// Setup HTTP<->gRPC handlers.
 	c1, c2 := net.Pipe()
 
@@ -1584,9 +1579,13 @@ func (s *Server) Start(ctx context.Context) error {
 	log.Info(ctx, "serving sql connections")
 	// Start servicing SQL connections.
 
-	// Serve UI assets. This needs to be before the gRPC handlers are registered, otherwise
-	// the `s.mux.Handle("/", ...)` would cover all URLs, allowing anonymous access.
-	maybeAuthMux := newAuthenticationMuxAllowAnonymous(
+	// Serve UI assets.
+	//
+	// The authentication mux used here is created in "allow anonymous" mode so that the UI
+	// assets are served up whether or not there is a session. If there is a session, the mux
+	// adds it to the context, and it is templated into index.html so that the UI can show
+	// the username of the currently-logged-in user.
+	authenticatedUIHandler := newAuthenticationMuxAllowAnonymous(
 		s.authentication,
 		ui.Handler(ui.Config{
 			ExperimentalUseLogin: s.cfg.EnableWebSessionAuthentication,
@@ -1599,7 +1598,13 @@ func (s *Server) Start(ctx context.Context) error {
 			},
 		}),
 	)
-	s.mux.Handle("/", maybeAuthMux)
+	s.mux.Handle("/", authenticatedUIHandler)
+
+	// Register gRPC-gateway endpoints used by the admin UI.
+	var authHandler http.Handler = gwMux
+	if s.cfg.RequireWebSession() {
+		authHandler = newAuthenticationMux(s.authentication, authHandler)
+	}
 
 	s.mux.Handle(adminPrefix, authHandler)
 	// Exempt the health check endpoint from authentication.

pkg/ui/ui.go

@@ -112,7 +112,9 @@ type Config struct {
 	GetUser              func(ctx context.Context) *string
 }
 
-// Handler returns an http.Handler that serves the UI.
+// Handler returns an http.Handler that serves the UI,
+// including index.html, which has some login-related variables
+// templated into it, as well as static assets.
 func Handler(cfg Config) http.Handler {
 	fileServer := http.FileServer(&assetfs.AssetFS{
 		Asset:     Asset,