Minor improvements to the HTTP authentication middleware change

- In our case a shallow copy of the HTTP request using .Context()
  instead of .Clone() is sufficient.
- Do a better job at explaining how the cookie encryption key is
  computed.
- Leave a 'reserved' marker in place for the 'listen_address' field, to
  make it easier for people to figure out how to migrate.

pkg/http/authenticating_handler.go

@@ -32,6 +32,6 @@ func (h *authenticatingHandler) ServeHTTP(w http.ResponseWriter, r *http.Request
 		// not write a response to the client (e.g., emit a
 		// redirect). Forward the request to the underlying
 		// handler.
-		h.handler.ServeHTTP(w, r.Clone(auth.NewContextWithAuthenticationMetadata(r.Context(), metadata)))
+		h.handler.ServeHTTP(w, r.WithContext(auth.NewContextWithAuthenticationMetadata(r.Context(), metadata)))
 	}
 }

pkg/http/authenticator.go

@@ -62,7 +62,7 @@ func NewAuthenticatorFromConfiguration(policy *configuration.AuthenticationPolic
 	case *configuration.AuthenticationPolicy_Oidc:
 		// Select a name and encryption key for the session
 		// state cookie. Even though the configuration has a
-		// dedicted cookie seed field, we include the rest of
+		// dedicated cookie seed field, we include the rest of
 		// the configuration message as well. This ensures that
 		// any changes to the configuration automatically
 		// invalidate existing sessions.
@@ -74,6 +74,10 @@ func NewAuthenticatorFromConfiguration(policy *configuration.AuthenticationPolic
 			return nil, status.Error(codes.InvalidArgument, "Failed to marshal configuration to compute OIDC cookie seed")
 		}
 		cookieSeedHash := sha256.Sum256(fullCookieSeed)
+
+		// Let the first 128 bits of the seed hash be the name
+		// of the cookie, while the last 128 bits are used as
+		// the AES key for encrypting/signing the cookie value.
 		cookieName := base64.RawURLEncoding.EncodeToString(cookieSeedHash[:sha256.Size/2])
 		cookieCipher, err := aes.NewCipher(cookieSeedHash[sha256.Size/2:])
 		if err != nil {

pkg/http/oidc_authenticator.go

@@ -42,7 +42,16 @@ type oidcAuthenticator struct {
 // requests are authorized by an OAuth2 server. Authentication metadata
 // is constructed by obtaining claims through the OpenID Connect user
 // info endpoint, and transforming it using a JMESPath expression.
-func NewOIDCAuthenticator(oauth2Config *oauth2.Config, userInfoURL string, metadataExtractor *jmespath.JMESPath, httpClient *http.Client, randomNumberGenerator random.ThreadSafeGenerator, cookieName string, cookieAEAD cipher.AEAD, clock clock.Clock) (Authenticator, error) {
+func NewOIDCAuthenticator(
+	oauth2Config *oauth2.Config,
+	userInfoURL string,
+	metadataExtractor *jmespath.JMESPath,
+	httpClient *http.Client,
+	randomNumberGenerator random.ThreadSafeGenerator,
+	cookieName string,
+	cookieAEAD cipher.AEAD,
+	clock clock.Clock,
+) (Authenticator, error) {
 	// Extract the path in the redirect URL of the OAuth2
 	// configuration, as we need to match it in incoming HTTP
 	// requests.

pkg/http/server.go

@@ -10,9 +10,9 @@ import (
 )
 
 // NewServersFromConfigurationAndServe spawns HTTP servers as part of a
-// program.Group, based on a configuration specification. The web
-// servers are automatically terminated if the context associated with
-// the group is canceled.
+// program.Group, based on a configuration message. The web servers are
+// automatically terminated if the context associated with the group is
+// canceled.
 func NewServersFromConfigurationAndServe(configurations []*configuration.ServerConfiguration, handler http.Handler, group program.Group) error {
 	for _, configuration := range configurations {
 		authenticator, err := NewAuthenticatorFromConfiguration(configuration.AuthenticationPolicy)

pkg/proto/configuration/global/global.proto

@@ -241,10 +241,14 @@ message Configuration {
 }
 
 message DiagnosticsHTTPServerConfiguration {
+  // Was 'listen_address'. The listen address of the diagnostics HTTP
+  // server can now be configured through the 'http_servers' option.
+  reserved 1;
+
   // Default endpoints:
   // - /-/healthy: Returns HTTP 200 OK if the application managed to
   //               start successfully.
-  repeated buildbarn.configuration.http.ServerConfiguration http_servers = 1;
+  repeated buildbarn.configuration.http.ServerConfiguration http_servers = 5;
 
   // Enables endpoints:
   // - /debug/pprof/*: Endpoints for Go's pprof debug tool.

pkg/proto/configuration/http/http.proto

@@ -121,6 +121,10 @@ message OIDCAuthenticationPolicy {
   // service returns refresh tokens. This permits the HTTP server to
   // continue sessions with fewer redirects to the authorization
   // service.
+  //
+  // A list of commonly used scopes can be found in the OpenID Connect
+  // specification:
+  // https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims
   repeated string scopes = 8;
 
   // A random seed of how cookies containing session state are named,