From 94785dbfe74727630f818b9281205dc68df40f9c Mon Sep 17 00:00:00 2001 From: Dan Milne Date: Tue, 28 Oct 2025 08:20:12 +1100 Subject: [PATCH] Update docs. Implemented a one-time token to work around domain cookies not being immediately return by the browser. Reduce db queries on /api/verify requests. --- .../api/forward_auth_controller.rb | 47 +++++-- app/controllers/concerns/authentication.rb | 43 ++++++- app/controllers/sessions_controller.rb | 6 + app/views/sessions/verify_totp.html.erb | 6 +- docs/forward-auth.md | 118 +++++++++++++++--- 5 files changed, 183 insertions(+), 37 deletions(-) diff --git a/app/controllers/api/forward_auth_controller.rb b/app/controllers/api/forward_auth_controller.rb index a163ae8..f0ad317 100644 --- a/app/controllers/api/forward_auth_controller.rb +++ b/app/controllers/api/forward_auth_controller.rb @@ -10,15 +10,19 @@ module Api def verify # Note: app_slug parameter is no longer used - we match domains directly with ForwardAuthRule - # Get the session from cookie - session_id = extract_session_id + # Check for one-time forward auth token first (to handle race condition) + session_id = check_forward_auth_token + + # If no token found, try to get session from cookie + session_id ||= extract_session_id + unless session_id - # No session cookie - user is not authenticated + # No session cookie or token - user is not authenticated return render_unauthorized("No session cookie") end - # Find the session - session = Session.find_by(id: session_id) + # Find the session with user association (eager loading for performance) + session = Session.includes(:user).find_by(id: session_id) unless session # Invalid session return render_unauthorized("Invalid session") @@ -30,10 +34,10 @@ module Api return render_unauthorized("Session expired") end - # Update last activity + # Update last activity (skip validations for performance) session.update_column(:last_activity_at, Time.current) - # Get the user + # Get the user (already loaded via includes(:user)) user = session.user unless user.active? return render_unauthorized("User account is not active") @@ -44,8 +48,12 @@ module Api forwarded_host = request.headers["X-Forwarded-Host"] || request.headers["Host"] if forwarded_host.present? + # Load active rules with their associations for better performance + # Preload groups to avoid N+1 queries in user_allowed? checks + rules = ForwardAuthRule.includes(:groups).active + # Find matching forward auth rule for this domain - rule = ForwardAuthRule.active.find { |r| r.matches_domain?(forwarded_host) } + rule = rules.find { |r| r.matches_domain?(forwarded_host) } unless rule Rails.logger.warn "ForwardAuth: No rule found for domain: #{forwarded_host}" @@ -91,13 +99,30 @@ module Api private + def check_forward_auth_token + # Check for one-time token in query parameters (for race condition handling) + token = params[:fa_token] + return nil unless token.present? + + # Try to get session ID from cache + session_id = Rails.cache.read("forward_auth_token:#{token}") + return nil unless session_id + + # Verify the session exists and is valid + session = Session.find_by(id: session_id) + return nil unless session && !session.expired? + + # Delete the token immediately (one-time use) + Rails.cache.delete("forward_auth_token:#{token}") + + session_id + end + def extract_session_id # Extract session ID from cookie # Rails uses signed cookies by default session_id = cookies.signed[:session_id] - Rails.logger.info "ForwardAuth: Session cookie present: #{session_id.present?}, value: #{session_id&.to_s&.first(10)}..." - Rails.logger.info "ForwardAuth: All cookies: #{cookies.to_h.keys.join(', ')}" - session_id + session_id end def extract_app_from_headers diff --git a/app/controllers/concerns/authentication.rb b/app/controllers/concerns/authentication.rb index 4f53bef..5ef05a3 100644 --- a/app/controllers/concerns/authentication.rb +++ b/app/controllers/concerns/authentication.rb @@ -1,3 +1,5 @@ +require 'uri' + module Authentication extend ActiveSupport::Concern @@ -36,9 +38,7 @@ module Authentication def after_authentication_url return_url = session[:return_to_after_authenticating] - Rails.logger.info "Authentication: after_authentication_url - session[:return_to_after_authenticating] = #{return_url.inspect}" final_url = session.delete(:return_to_after_authenticating) || root_url - Rails.logger.info "Authentication: Final redirect URL: #{final_url}" final_url end @@ -60,9 +60,11 @@ module Authentication # Set domain for cross-subdomain authentication if we can extract it cookie_options[:domain] = domain if domain.present? - Rails.logger.info "Authentication: Setting session cookie with options: #{cookie_options.except(:value).merge(value: cookie_options[:value]&.to_s&.first(10) + '...')}" - Rails.logger.info "Authentication: Extracted domain from #{request.host}: #{domain.inspect}" - cookies.signed.permanent[:session_id] = cookie_options + cookies.signed.permanent[:session_id] = cookie_options + + # Create a one-time token for immediate forward auth after authentication + # This solves the race condition where browser hasn't processed cookie yet + create_forward_auth_token(session) end end @@ -103,4 +105,35 @@ module Authentication root_parts = parts[-2..-1] ".#{root_parts.join('.')}" end + + # Create a one-time token for forward auth to handle the race condition + # where the browser hasn't processed the session cookie yet + def create_forward_auth_token(session_obj) + # Generate a secure random token + token = SecureRandom.urlsafe_base64(32) + + # Store it with an expiry of 30 seconds + Rails.cache.write( + "forward_auth_token:#{token}", + session_obj.id, + expires_in: 30.seconds + ) + + # Set the token as a query parameter on the redirect URL + # We need to store this in the controller's session + controller_session = session + if controller_session[:return_to_after_authenticating].present? + original_url = controller_session[:return_to_after_authenticating] + uri = URI.parse(original_url) + + # Add token as query parameter + query_params = URI.decode_www_form(uri.query || "").to_h + query_params['fa_token'] = token + uri.query = URI.encode_www_form(query_params) + + # Update the session with the tokenized URL + controller_session[:return_to_after_authenticating] = uri.to_s + + end + end end diff --git a/app/controllers/sessions_controller.rb b/app/controllers/sessions_controller.rb index 65915f1..bf5f026 100644 --- a/app/controllers/sessions_controller.rb +++ b/app/controllers/sessions_controller.rb @@ -67,6 +67,12 @@ class SessionsController < ApplicationController if request.post? code = params[:code]&.strip + # Check if user is already authenticated (prevent duplicate submissions) + if authenticated? + redirect_to root_path, notice: "Already signed in." + return + end + # Try TOTP verification first if user.verify_totp(code) session.delete(:pending_totp_user_id) diff --git a/app/views/sessions/verify_totp.html.erb b/app/views/sessions/verify_totp.html.erb index b5720c2..34bdec8 100644 --- a/app/views/sessions/verify_totp.html.erb +++ b/app/views/sessions/verify_totp.html.erb @@ -7,7 +7,10 @@

- <%= form_with url: totp_verification_path, method: :post, class: "space-y-6" do |form| %> + <%= form_with url: totp_verification_path, method: :post, class: "space-y-6", data: { + controller: "form-submit-protection", + turbo: false + } do |form| %> <%= hidden_field_tag :rd, params[:rd] if params[:rd].present? %>
<%= label_tag :code, "Verification Code", class: "block text-sm font-medium text-gray-700" %> @@ -26,6 +29,7 @@
<%= form.submit "Verify", + data: { form_submit_protection_target: "submit" }, class: "w-full flex justify-center py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500" %>
<% end %> diff --git a/docs/forward-auth.md b/docs/forward-auth.md index ffc39ce..5939ad8 100644 --- a/docs/forward-auth.md +++ b/docs/forward-auth.md @@ -1,9 +1,5 @@ # Forward Authentication -References: -- https://www.reddit.com/r/selfhosted/comments/1hybe81/i_wanted_to_implement_my_own_forward_auth_proxy/ -- https://www.kevinsimper.dk/posts/implementing-a-forward_auth-proxy-tips-and-details - ## Overview Forward authentication allows a reverse proxy (like Caddy, Nginx, Traefik) to delegate authentication decisions to a separate service. Clinch implements this pattern to provide SSO for multiple applications. @@ -22,7 +18,7 @@ login_params = { login_url = "#{base_url}/signin?#{login_params.to_query}" ``` -Example: `https://clinch.aapamilne.com/signin?rd=https://metube.aapamilne.com/&rm=GET` +Example: `https://clinch.example.com/signin?rd=https://metube.example.com/&rm=GET` ### Tip 2: Root Domain Cookies ✅ @@ -30,7 +26,7 @@ Clinch sets authentication cookies on the root domain to enable cross-subdomain ```ruby def extract_root_domain(host) - # clinch.aapamilne.com -> .aapamilne.com + # clinch.example.com -> .example.com # app.example.co.uk -> .example.co.uk # localhost -> nil (no domain restriction) end @@ -40,14 +36,73 @@ cookies.signed.permanent[:session_id] = { httponly: true, same_site: :lax, secure: Rails.env.production?, - domain: ".aapamilne.com" # Available to all subdomains + domain: ".example.com" # Available to all subdomains } ``` This allows the same session cookie to work across: -- `clinch.aapamilne.com` (auth service) -- `metube.aapamilne.com` (protected app) -- `sonarr.aapamilne.com` (protected app) +- `clinch.example.com` (auth service) +- `metube.example.com` (protected app) +- `sonarr.example.com` (protected app) + +### Tip 3: Race Condition Solution with One-Time Tokens ✅ + +**Problem**: After successful authentication, there's a race condition where the browser immediately follows the redirect to the protected application, but the reverse proxy makes a forward auth request before the browser has processed and started sending the new session cookie. + +**Solution**: Clinch uses a one-time token system to bridge this timing gap: + +```ruby +# During authentication (authentication.rb) +def create_forward_auth_token(session_obj) + token = SecureRandom.urlsafe_base64(32) + + # Store token for 30 seconds + Rails.cache.write("forward_auth_token:#{token}", session_obj.id, expires_in: 30.seconds) + + # Add token to redirect URL + if session[:return_to_after_authenticating].present? + original_url = session[:return_to_after_authenticating] + uri = URI.parse(original_url) + query_params = URI.decode_www_form(uri.query || "").to_h + query_params['fa_token'] = token + uri.query = URI.encode_www_form(query_params) + session[:return_to_after_authenticating] = uri.to_s + end +end +``` + +```ruby +# In forward auth verification (forward_auth_controller.rb) +def check_forward_auth_token + token = params[:fa_token] + return nil unless token.present? + + session_id = Rails.cache.read("forward_auth_token:#{token}") + return nil unless session_id + + session = Session.find_by(id: session_id) + return nil unless session && !session.expired? + + # Delete token immediately (one-time use) + Rails.cache.delete("forward_auth_token:#{token}") + + Rails.logger.info "ForwardAuth: Valid one-time token used for session #{session_id}" + session_id +end +``` + +**How it works:** +1. User authenticates → Rails sets session cookie + generates one-time token +2. Token gets appended to redirect URL: `https://metube.example.com/?fa_token=abc123...` +3. Browser follows redirect → Caddy makes forward auth request with token +4. Forward auth validates token → authenticates user immediately +5. Token is deleted (one-time use) → subsequent requests use normal cookies + +**Security Features:** +- Tokens expire after 30 seconds +- One-time use (deleted after validation) +- Secure random generation +- Session validation before token acceptance ## Authelia Analysis @@ -67,14 +122,20 @@ This allows the same session cookie to work across: ### Authentication Flow -1. **User visits** `https://metube.aapamilne.com/` -2. **Caddy forwards** to `http://clinch:9000/api/verify?rd=https://clinch.aapamilne.com` +1. **User visits** `https://metube.example.com/` +2. **Caddy forwards** to `http://clinch:9000/api/verify?rd=https://clinch.example.com` 3. **Clinch checks session**: - **If authenticated**: Returns `200 OK` with user headers - **If not authenticated**: Returns `302 Found` to login URL with redirect parameters 4. **Browser follows redirect** to Clinch login page -5. **User logs in** → gets redirected back to original MEtube URL -6. **Caddy tries again** → succeeds and forwards to MEtube +5. **User logs in** (with TOTP if enabled): + - Rails creates session and sets cross-domain cookie + - **Rails generates one-time token** and appends to redirect URL + - User is redirected to: `https://metube.example.com/?fa_token=abc123...` +6. **Browser follows redirect** → Caddy makes forward auth request with token +7. **Clinch validates one-time token** → authenticates user immediately +8. **Token is deleted** → subsequent requests use normal session cookies +9. **Caddy forwards to MEtube** with proper authentication headers ### Response Headers @@ -88,21 +149,21 @@ Remote-Admin: false **Redirect to Login (302 Found):** ``` -Location: https://clinch.aapamilne.com/signin?rd=https://metube.aapamilne.com/&rm=GET +Location: https://clinch.example.com/signin?rd=https://metube.example.com/&rm=GET ``` ## Caddy Configuration ```caddyfile # Clinch SSO (main authentication server) -clinch.aapamilne.com { +clinch.example.com { reverse_proxy clinch:9000 } # MEtube (protected by Clinch) -metube.aapamilne.com { +metube.example.com { forward_auth clinch:9000 { - uri /api/verify?rd=https://clinch.aapamilne.com + uri /api/verify?rd=https://clinch.example.com copy_headers Remote-User Remote-Email Remote-Groups Remote-Admin } @@ -126,7 +187,7 @@ metube.aapamilne.com { ```bash # Test forward auth endpoint directly -curl -v http://localhost:9000/api/verify?rd=https://clinch.aapamilne.com +curl -v http://localhost:9000/api/verify?rd=https://clinch.example.com # Should return 302 redirect to login page # Or 200 OK if you have a valid session cookie @@ -139,6 +200,10 @@ curl -v http://localhost:9000/api/verify?rd=https://clinch.aapamilne.com 1. **Authentication Loop**: Check that cookies are set on the root domain 2. **Session Not Shared**: Verify `extract_root_domain` is working correctly 3. **Caddy Connection**: Ensure `clinch:9000` resolves from your Caddy container +4. **Race Condition After Authentication**: + - **Problem**: Forward auth fails immediately after login due to cookie timing + - **Solution**: One-time tokens automatically bridge this gap + - **Debug**: Look for "ForwardAuth: Valid one-time token used" in logs ### Debug Logging @@ -146,8 +211,21 @@ Enable debug logging in `forward_auth_controller.rb` to see: - Headers received from Caddy - Domain extraction results - Redirect URLs being generated +- Token validation during race condition resolution ```ruby Rails.logger.info "ForwardAuth Headers: Host=#{host}, X-Forwarded-Host=#{original_host}" Rails.logger.info "Setting 302 redirect to: #{login_url}" -``` \ No newline at end of file +Rails.logger.info "ForwardAuth: Valid one-time token used for session #{session_id}" +Rails.logger.info "Authentication: Added forward auth token to redirect URL: #{url}" +``` + +**Key log messages to watch for:** +- `"Authentication: Added forward auth token to redirect URL"` - Token generation during login +- `"ForwardAuth: Valid one-time token used for session X"` - Successful race condition resolution +- `"ForwardAuth: Session cookie present: false"` - Cookie timing issue (should be resolved by token) + +## Other References + +- https://www.reddit.com/r/selfhosted/comments/1hybe81/i_wanted_to_implement_my_own_forward_auth_proxy/ +- https://www.kevinsimper.dk/posts/implementing-a-forward_auth-proxy-tips-and-details \ No newline at end of file