Merge pull request #9 from linuxfoundation/html-error-page

HTML error pages

Author: emsearcy

.cspell.json

@@ -53,6 +53,7 @@
   ],
   "ignorePaths": [
     ".cspell.json",
+    ".mega-linter.yml",
     "LICENSE",
     "LICENSE-docs",
     "megalinter-reports"

.mega-linter.yml

@@ -2,6 +2,9 @@
 # SPDX-License-Identifier: MIT
 ---
 DISABLE_LINTERS:
+  # Skipping for now.
+  - HTML_DJLINT
+  - HTML_HTMLHINT
   # Revive covers this, plus golangci-lint has trouble with newer go toolchains
   # in go.mod.
   - GO_GOLANGCI_LINT

Dockerfile

@@ -33,5 +33,6 @@ USER nonroot
 EXPOSE 8080
 
 COPY --from=builder /go/bin/auth0-cas-server-go /auth0-cas-server-go
+COPY --from=builder /build/templates /templates
 
 ENTRYPOINT ["/auth0-cas-server-go", "-p=8080"]

ERROR_PAGES.md

@@ -0,0 +1,107 @@
+# Error Pages Documentation
+
+## Overview
+
+This document describes the error page system implemented in the auth0-cas-server-go service. The system provides user-friendly HTML error pages with embedded CSS styling, while maintaining fallback support for plain text errors. The system differentiates between user-facing routes and CAS protocol routes.
+
+## Architecture
+
+1. **HTML Template** (`templates/error.html`): Responsive error page template with embedded CSS styling and conditional "Go Back" button
+2. **Error Wrapper Functions** (`responses.go`): Template rendering with different behaviors for user vs callback routes
+3. **CAS Protocol Error Handler**: Uses existing `outputFailure` function for XML/JSON responses
+
+## Route Classification
+
+### User-Facing Routes (with "Go Back" button)
+- `/cas/login` - CAS login page
+- `/cas/logout` - CAS logout page
+
+### User-Facing Callbacks (without "Go Back" button)
+- `/cas/oidc_callback` - OAuth2 callback handler
+
+### CAS Protocol Routes (use `outputFailure`)
+- `/cas/serviceValidate` - CAS service validation
+- `/cas/p3/serviceValidate` - CAS protocol 3 service validation
+- `/cas/proxyValidate` - CAS proxy validation
+- `/cas/p3/proxyValidate` - CAS protocol 3 proxy validation
+- `/cas/proxy` - CAS proxy ticket granting
+
+## Build Process
+
+The error template uses embedded CSS and requires no build process. The template is self-contained with all styling included inline.
+
+### Dependencies
+
+- **Go html/template**: Standard library package for template rendering
+
+## Usage
+
+### Error Rendering Functions
+
+Different functions are used based on route type:
+
+```go
+// User-facing routes (shows "Go Back" button)
+renderUserErrorPage(r.Context(), w, http.StatusBadRequest, "Service parameter is required")
+
+// Callback routes (no "Go Back" button)
+renderCallbackErrorPage(r.Context(), w, http.StatusBadRequest, "Invalid request")
+
+// CAS protocol routes (use existing outputFailure for XML/JSON)
+outputFailure(r.Context(), w, err, "INVALID_REQUEST", "service parameter is required", useJSON)
+```
+
+### Template Data Structure
+
+```go
+type ErrorPageData struct {
+    StatusCode     int    // HTTP status code (e.g., 400, 500)
+    Message        string // User-friendly error message
+    ShowBackButton bool   // Whether to show the "Go Back" button
+}
+```
+
+### Conditional Back Button
+
+The template includes conditional logic for the back button:
+
+```html
+{{if .ShowBackButton}}
+<button onclick="history.back()" class="back-button">
+    <svg class="back-icon" ...>...</svg>
+    Go Back
+</button>
+{{end}}
+```
+
+### Fallback Behavior
+
+1. **Template Available**: Renders HTML error page with embedded styling
+2. **Template Missing**: Falls back to plain text error response
+3. **Template Error**: Logs error and continues with partial content
+4. **CAS Protocol Routes**: Always use XML/JSON responses via `outputFailure`
+
+### Template Modifications
+
+The error template supports standard Go template syntax with conditional logic:
+
+```html
+<h1 class="error-title">Error {{.StatusCode}}</h1>
+<p class="error-message">{{.Message}}</p>
+{{if .ShowBackButton}}
+<button onclick="history.back()" class="back-button">
+    <svg class="back-icon" ...>...</svg>
+    Go Back
+</button>
+{{end}}
+```
+
+### Adding New Routes
+
+When adding new routes:
+
+1. Determine if it's user-facing, callback, or CAS protocol
+2. Use the appropriate error function:
+   - `renderUserErrorPage()` for user-facing with back button
+   - `renderCallbackErrorPage()` for user-facing without back button
+   - `outputFailure()` for CAS protocol routes

cas.go

@@ -62,26 +62,26 @@ func casLogin(w http.ResponseWriter, r *http.Request) {
 	service := params.Get("service")
 	if service == "" {
 		appLogger(r.Context()).Warn("service parameter is required")
-		http.Error(w, "service parameter is required", http.StatusBadRequest)
+		renderUserErrorPage(r.Context(), w, http.StatusBadRequest, "Service parameter is required")
 		return
 	}
 
 	if _, err := url.Parse(service); err != nil {
 		// We don't use this now, but better to catch here than in oauth2Callback.
 		appLogger(r.Context()).Warn("invalid service URL")
-		http.Error(w, "invalid service URL", http.StatusBadRequest)
+		renderUserErrorPage(r.Context(), w, http.StatusBadRequest, "Invalid service URL")
 		return
 	}
 
 	casClient, err := getAuth0ClientByService(r.Context(), service)
 	if err != nil {
 		appLogger(r.Context()).Error("error looking up service", "error", err)
-		http.Error(w, "error looking up service", http.StatusInternalServerError)
+		renderUserErrorPage(r.Context(), w, http.StatusInternalServerError, "Error looking up service")
 		return
 	}
 	if casClient == nil {
 		appLogger(r.Context()).Warn("unknown service")
-		http.Error(w, "unknown service", http.StatusForbidden)
+		renderUserErrorPage(r.Context(), w, http.StatusForbidden, "Unknown service")
 		return
 	}
 
@@ -104,17 +104,17 @@ func casLogin(w http.ResponseWriter, r *http.Request) {
 	session, _ := store.Get(r, "cas-shim")
 	session.Values[state] = service
 	err = session.Save(r, w)
-	if err != nil && err.Error() == "securecookie: the value is too long" {
+	if err != nil && strings.HasPrefix(err.Error(), "securecookie: the value is too long") {
 		// The cookie can get too big if the user tries 10+ logins in the day
 		// without returning from any of them.
-		appLogger(r.Context()).Warn("cookie too large (bot or other bad client)")
+		appLogger(r.Context()).Warn("cookie too large", "error", err)
 		w.Header().Set("Retry-After", "86400")
-		http.Error(w, "429 too many requests", http.StatusTooManyRequests)
+		renderUserErrorPage(r.Context(), w, http.StatusTooManyRequests, "Session size limit reached. Either the URL you are logging into is too long, or you had too many unsuccessful logins in the last 24 hours.")
 		return
 	}
 	if err != nil {
 		appLogger(r.Context()).Error("error saving session", "error", err)
-		http.Error(w, "500 internal server error", http.StatusInternalServerError)
+		renderUserErrorPage(r.Context(), w, http.StatusInternalServerError, "Error saving session")
 		return
 	}
 
@@ -320,9 +320,7 @@ func casServiceValidate(w http.ResponseWriter, r *http.Request) {
 	}
 	output, err := validationResponse(&success, nil, useJSON)
 	if err != nil {
-		appLogger(r.Context()).Error("error generating validation response", "error", err, "success", success)
-		w.WriteHeader(http.StatusInternalServerError)
-		http.Error(w, "error generating validation response", http.StatusInternalServerError)
+		outputFailure(r.Context(), w, err, "INTERNAL_ERROR", "error generating validation response", useJSON)
 		return
 	}
 
@@ -395,27 +393,27 @@ func oauth2Callback(w http.ResponseWriter, r *http.Request) {
 		// Consider this a warning-level error for logging purposes.
 		err := fmt.Errorf("%s: %s", errParam, errDescription)
 		appLogger(r.Context()).Warn("login aborted", "error", err)
-		http.Error(w, err.Error(), http.StatusBadRequest)
+		renderCallbackErrorPage(r.Context(), w, http.StatusBadRequest, "Login was cancelled")
 		return
 	}
 	if errParam != "" {
 		err := fmt.Errorf("%s: %s", errParam, errDescription)
 		appLogger(r.Context()).Error("login error", "error", err)
-		http.Error(w, err.Error(), http.StatusBadRequest)
+		renderCallbackErrorPage(r.Context(), w, http.StatusBadRequest, "Login error occurred")
 		return
 	}
 
 	code := params.Get("code")
 	if code == "" {
 		appLogger(r.Context()).Warn("invalid request")
-		http.Error(w, "invalid request", http.StatusBadRequest)
+		renderCallbackErrorPage(r.Context(), w, http.StatusBadRequest, "Invalid request")
 		return
 	}
 
 	state := params.Get("state")
 	if state == "" {
 		appLogger(r.Context()).Warn("missing state")
-		http.Error(w, "missing state", http.StatusBadRequest)
+		renderCallbackErrorPage(r.Context(), w, http.StatusBadRequest, "Missing state parameter")
 		return
 	}
 
@@ -424,7 +422,7 @@ func oauth2Callback(w http.ResponseWriter, r *http.Request) {
 	var ok bool
 	if service, ok = session.Values[state].(string); !ok {
 		appLogger(r.Context()).Warn("session missing or expired")
-		http.Error(w, "session missing or expired", http.StatusBadRequest)
+		renderCallbackErrorPage(r.Context(), w, http.StatusBadRequest, "Session missing or expired")
 		return
 	}
 
@@ -434,7 +432,7 @@ func oauth2Callback(w http.ResponseWriter, r *http.Request) {
 	serviceURL, err := url.Parse(service)
 	if err != nil {
 		appLogger(r.Context()).Warn("invalid service URL")
-		http.Error(w, "invalid service URL", http.StatusBadRequest)
+		renderCallbackErrorPage(r.Context(), w, http.StatusBadRequest, "Invalid service URL")
 		return
 	}
 
@@ -524,33 +522,3 @@ func getLogoutParams(ctx context.Context, returnTo string) *url.Values {
 
 	return nil
 }
-
-// outputFailure handles a common case of reporting a problem to the
-// /cas/serviceValidate URL, which is expected to return a properly-formatted
-// error. This logs the issue, and formats and outputs the response (default
-// 200 status code). If the response cannot be formatted, an additional error
-// is logged and a plain-text message and 500 response is output.
-func outputFailure(ctx context.Context, w http.ResponseWriter, err error, code, description string, useJSON bool) {
-	switch {
-	case err != nil:
-		appLogger(ctx).Error(description, "error", err)
-	default:
-		appLogger(ctx).Warn(description)
-	}
-
-	failure := casAuthenticationFailure{code, description}
-	output, err := validationResponse(nil, &failure, useJSON)
-	if err != nil {
-		appLogger(ctx).Error("error generating validation response", "error", err, "failure", failure)
-		w.WriteHeader(http.StatusInternalServerError)
-		http.Error(w, "error generating validation response", http.StatusInternalServerError)
-		return
-	}
-	switch useJSON {
-	case true:
-		w.Header().Set("Content-Type", "application/json;charset=UTF-8")
-	default:
-		w.Header().Set("Content-Type", "application/xml;charset=UTF-8")
-	}
-	fmt.Fprintf(w, "%s\n", output)
-}

docker-compose.yaml

@@ -1,7 +1,6 @@
 # Copyright The Linux Foundation and its contributors.
 # SPDX-License-Identifier: MIT
 ---
-version: "2"
 services:
   # Auth0 CAS server.
   auth0-cas-server-go:

go.mod

@@ -3,20 +3,20 @@
 
 module github.com/linuxfoundation/auth0-cas-server-go
 
-go 1.25.0
+go 1.25.3
 
 require (
 	github.com/bmatcuk/doublestar/v4 v4.9.1
 	github.com/gorilla/sessions v1.4.0
 	github.com/joho/godotenv v1.5.1
 	github.com/patrickmn/go-cache v2.1.0+incompatible
-	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.62.0
-	go.opentelemetry.io/otel v1.37.0
-	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.37.0
-	go.opentelemetry.io/otel/sdk v1.37.0
-	go.opentelemetry.io/otel/trace v1.37.0
-	golang.org/x/oauth2 v0.30.0
-	golang.org/x/text v0.28.0
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.63.0
+	go.opentelemetry.io/otel v1.38.0
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.38.0
+	go.opentelemetry.io/otel/sdk v1.38.0
+	go.opentelemetry.io/otel/trace v1.38.0
+	golang.org/x/oauth2 v0.32.0
+	golang.org/x/text v0.30.0
 )
 
 require (
@@ -26,15 +26,15 @@ require (
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/gorilla/securecookie v1.1.2 // indirect
-	github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.1 // indirect
-	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
-	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.37.0 // indirect
-	go.opentelemetry.io/otel/metric v1.37.0 // indirect
-	go.opentelemetry.io/proto/otlp v1.7.1 // indirect
-	golang.org/x/net v0.43.0 // indirect
-	golang.org/x/sys v0.35.0 // indirect
-	google.golang.org/genproto/googleapis/api v0.0.0-20250818200422-3122310a409c // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20250818200422-3122310a409c // indirect
-	google.golang.org/grpc v1.75.0 // indirect
-	google.golang.org/protobuf v1.36.7 // indirect
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.3 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.38.0 // indirect
+	go.opentelemetry.io/otel/metric v1.38.0 // indirect
+	go.opentelemetry.io/proto/otlp v1.8.0 // indirect
+	golang.org/x/net v0.46.0 // indirect
+	golang.org/x/sys v0.37.0 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20251020155222-88f65dc88635 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20251020155222-88f65dc88635 // indirect
+	google.golang.org/grpc v1.76.0 // indirect
+	google.golang.org/protobuf v1.36.10 // indirect
 )