Build a Secure API with Rails 8 - Part-4: SSL, CSRF & Serialization

Hey folks 👋

Welcome back. In Part 3 we built all five auth endpoints, added Rack-Attack rate limiting, hardened the HTTP headers with secure_headers, and set up Lograge for structured logs. The API is functional and most of the security checklist is green.

But we left three vectors partially open, and we made a design debt: hand-rolling response hashes in every controller. Today we close all of that.

Here is what we are doing in Part 4:

• Explicit CSRF tokens for every state-changing endpoint
• Session fixation protection with reset_session on login and refresh
• force_ssl in production, the last piece of MITM defense
• Production error handler so unhandled exceptions never leak stack traces
• Alba serializers to replace the hand-rolled response hashes across controllers

If your Part 3 project is open, let's continue.

A quick word on what CSRF actually means for a cookie-based API

In Part 3 we used SameSite=Lax cookies and pinned CORS origins. Together those already stop most CSRF attacks. So why add explicit CSRF tokens on top?

SameSite=Lax tells the browser: "don't send this cookie on cross-site requests unless it's a top-level GET." That blocks the classic CSRF attack where a malicious site submits a form to your API. But SameSite is a browser-level protection, and its behavior has edge cases across older browsers, redirect chains, and certain same-site subdomain scenarios.

Explicit CSRF tokens add a second layer that doesn't depend on the browser getting SameSite right. The server issues a token, the client must echo it back, and an attacker who can only influence what cookies the browser sends can never produce the right header value.

There's also a subtler attack called login CSRF. An attacker forges a login request that authenticates the victim as the attacker's own account. The victim thinks they're using the site normally but their actions (uploading documents, saving payment details) land in the attacker's account. The only way to prevent that is to protect the login endpoint itself, which we do here.

Step 1. Include CSRF protection in ApplicationController

Rails 8 API mode excludes ActionController::RequestForgeryProtection by default. We have to bring it back in.

Edit app/controllers/application_controller.rb:

# frozen_string_literal: true

class ApplicationController < ActionController::API
  include ActionController::Cookies
  include ActionController::RequestForgeryProtection
  include Pundit::Authorization

  protect_from_forgery with: :exception

  before_action :doorkeeper_authorize!, unless: :skip_authorization?

  private

  def current_user
    return @current_user if defined?(@current_user)
    @current_user = User.find_by(id: doorkeeper_token.resource_owner_id) if doorkeeper_token
  end

  def skip_authorization?
    false
  end

  def append_info_to_payload(payload)
    super
    payload[:host]    = request.host
    payload[:user_id] = current_user&.id if doorkeeper_token
  end
end

Three things changed:

1. include ActionController::RequestForgeryProtection brings the CSRF machinery in.
2. protect_from_forgery with: :exception makes any request with a missing or invalid CSRF token raise ActionController::InvalidAuthenticityToken. We will rescue that shortly.
3. append_info_to_payload is the hook Lograge calls to let you attach custom fields. We add host and user_id so every log line carries them. I left this out of Part 3 by accident.

protect_from_forgery only fires on non-GET requests (POST, PUT, PATCH, DELETE). GET requests don't need CSRF tokens and never will.

Step 2. Handle the CSRF error in BaseController

We need to rescue ActionController::InvalidAuthenticityToken and return a JSON response. While we're here, we also add a rescue_from StandardError for production: no unhandled exception should ever reach the client as a stack trace.

Edit app/controllers/api/v1/base_controller.rb:

# frozen_string_literal: true

module Api
  module V1
    class BaseController < ApplicationController
      # StandardError must be first (lowest priority) so specific handlers below take precedence
      rescue_from StandardError,                              with: :internal_server_error
      rescue_from ActiveRecord::RecordNotFound,               with: :not_found
      rescue_from ActiveRecord::RecordInvalid,                with: :unprocessable_entity
      rescue_from Pundit::NotAuthorizedError,                 with: :forbidden
      rescue_from ActionController::InvalidAuthenticityToken, with: :invalid_csrf_token

      private

      def not_found
        render json: { error: "Not found" }, status: :not_found
      end

      def unprocessable_entity(exception)
        render json: { errors: exception.record.errors.full_messages },
               status: :unprocessable_entity
      end

      def forbidden
        render json: { error: "Access denied" }, status: :forbidden
      end

      def invalid_csrf_token
        render json: { error: "Invalid CSRF token" }, status: :forbidden
      end

      def internal_server_error(exception)
        raise exception unless Rails.env.production?

        Rails.logger.error("#{exception.class}: #{exception.message}")
        render json: { error: "Internal server error" }, status: :internal_server_error
      end
    end
  end
end

The ordering of rescue_from matters. Rails searches handlers from the last declared to the first (last in wins). By declaring rescue_from StandardError first and the specific errors after, each specific handler has higher priority. An ActiveRecord::RecordNotFound matches the not_found handler before it ever reaches internal_server_error.

The internal_server_error handler re-raises the exception in non-production environments. This means your development server still shows the full error (useful for debugging), but production callers only ever see "Internal server error".

🛡️ Mitigation in action: Verbose Error Messages (Part 1, vector 11)

This closes the last gap from Part 3. Stack traces, internal paths, database errors. None of it reaches the client in production. It all goes to the logger, which is where it belongs.

Step 3. Add the CSRF token endpoint

The client needs a way to get a CSRF token before making its first state-changing request. A dedicated GET endpoint is the cleanest approach.

Create app/controllers/api/v1/csrf_controller.rb:

# frozen_string_literal: true

module Api
  module V1
    class CsrfController < BaseController
      skip_before_action :doorkeeper_authorize!

      # GET /api/v1/csrf_token
      def show
        render json: { csrf_token: form_authenticity_token }
      end

      private

      def skip_authorization?
        true
      end
    end
  end
end

form_authenticity_token generates a masked token tied to the current session. The session itself is stored in the _secure_api_session cookie (configured in Part 2). Every call generates a fresh masked version of the same underlying session token. All those masked versions are valid, the server unmasks them before comparing.

Wire it up in config/routes.rb:

Rails.application.routes.draw do
  use_doorkeeper do
    skip_controllers :authorizations, :applications,
                     :authorized_applications, :tokens
  end

  namespace :api do
    namespace :v1 do
      # CSRF token for SPA clients
      get "csrf_token", to: "csrf#show"

      # Authentication endpoints
      post   "auth/register", to: "registrations#create"
      post   "auth/login",    to: "sessions#create"
      delete "auth/logout",   to: "sessions#destroy"
      post   "auth/refresh",  to: "sessions#refresh"

      # Protected resources
      get "me", to: "users#me"
    end
  end

  get "up" => "rails/health#show", as: :rails_health_check
end

Step 4. Update SessionsController: session fixation + CSRF token in response

Two changes here: reset_session on login and refresh, and returning the CSRF token so the client doesn't need to make a second round-trip after authenticating.

Edit app/controllers/api/v1/sessions_controller.rb:

# frozen_string_literal: true

module Api
  module V1
    class SessionsController < BaseController
      skip_before_action :doorkeeper_authorize!, only: %i[create refresh]

      # POST /api/v1/auth/login
      def create
        user = User.find_for_database_authentication(email: params[:email])

        if user&.valid_password?(params[:password])
          tokens = generate_tokens(user)
          set_auth_cookies(tokens)
          reset_session
          render json: {
            user: UserSerializer.new(user).as_json,
            expires_at: tokens[:expires_at],
            csrf_token: form_authenticity_token
          }
        else
          render json: { error: "Invalid credentials" }, status: :unauthorized
        end
      end

      # DELETE /api/v1/auth/logout
      def destroy
        revoke_tokens
        clear_auth_cookies
        render json: { message: "Logged out successfully" }
      end

      # POST /api/v1/auth/refresh
      def refresh
        refresh_token = cookies.encrypted[:refresh_token]
        return render json: { error: "No refresh token" }, status: :unauthorized if refresh_token.blank?

        existing = Doorkeeper::AccessToken.by_refresh_token(refresh_token)

        if existing.nil? || existing.revoked? || refresh_expired?(existing)
          clear_auth_cookies
          return render json: { error: "Expired session" }, status: :unauthorized
        end

        user = User.find_by(id: existing.resource_owner_id)
        existing.revoke

        tokens = generate_tokens(user)
        set_auth_cookies(tokens)
        reset_session
        render json: {
          user: UserSerializer.new(user).as_json,
          expires_at: tokens[:expires_at],
          csrf_token: form_authenticity_token
        }
      end

      private

      def skip_authorization?
        action_name.in?(%w[create refresh])
      end

      def generate_tokens(user)
        token = Doorkeeper::AccessToken.create!(
          resource_owner_id: user.id,
          expires_in: Doorkeeper.configuration.access_token_expires_in,
          scopes: "read write",
          use_refresh_token: true
        )
        {
          access_token: token.token,
          refresh_token: token.refresh_token,
          expires_at: token.expires_in.seconds.from_now.iso8601
        }
      end

      def set_auth_cookies(tokens)
        cookie_opts = { httponly: true, secure: Rails.env.production?, same_site: :lax }

        cookies.encrypted[:access_token] = cookie_opts.merge(
          value: tokens[:access_token],
          expires: 15.minutes.from_now
        )
        cookies.encrypted[:refresh_token] = cookie_opts.merge(
          value: tokens[:refresh_token],
          expires: 7.days.from_now
        )
      end

      def clear_auth_cookies
        cookies.delete(:access_token)
        cookies.delete(:refresh_token)
      end

      def revoke_tokens
        token = Doorkeeper::AccessToken.by_refresh_token(cookies.encrypted[:refresh_token])
        token&.revoke
      end

      def refresh_expired?(token)
        token.created_at + 7.days < Time.current
      end
    end
  end
end

Why reset_session? Before this change, if an attacker somehow knew or influenced the user's session ID before login (a session fixation attack), they could reuse that session ID after the victim authenticated and hijack the session. reset_session wipes the old session and generates a new ID on every login and refresh, so there is no pre-login session to fixate on.

Why return csrf_token in the login response? The client already made a round-trip to log in. We return the CSRF token right there in the response body, so it doesn't need to call GET /csrf_token separately after logging in. The client stores the token in JS memory (not in localStorage, not in a cookie) and sends it as the X-CSRF-Token header on every subsequent state-changing request.

🛡️ Mitigation in action: CSRF (Part 1, vector 3)

Combined with SameSite=Lax and pinned CORS origins from Part 2 and 3, this closes the CSRF vector completely. We now have three layers: the browser won't send cookies cross-site (SameSite), the server rejects unknown origins (CORS), and a random site can never produce a valid CSRF token (explicit tokens).

Step 5. Add serializers with Alba

Add the gem:

# Serialization
gem "alba"

Then:

bundle install

Create app/serializers/user_serializer.rb:

# frozen_string_literal: true

class UserSerializer
  include Alba::Resource

  attributes :id, :email

  attribute :created_at do |user|
    user.created_at.iso8601
  end
end

That's the whole serializer. attributes declares fields by name; attribute with a block lets you transform a value before it goes out. The created_at block converts the ActiveRecord timestamp to an ISO 8601 string so the client always gets a consistent format regardless of Rails serialization settings.

Update app/controllers/api/v1/users_controller.rb:

# frozen_string_literal: true

module Api
  module V1
    class UsersController < BaseController
      # GET /api/v1/me
      def me
        render json: { user: UserSerializer.new(current_user).as_json }, status: :ok
      end
    end
  end
end

The as_json call (instead of serialize) returns a Ruby hash that Rails can embed inside the larger response hash. If you called serialize here it would return a JSON string, and Rails would end up double-encoding it.

🛡️ Mitigation in action: Excessive Data Exposure (Part 1, vector 8)

With serializers in place, the contract is explicit and enforced in one place. Adding a new column to the users table even a sensitive one will never accidentally appear in API responses. The serializer is the whitelist. Nothing goes out unless it's listed there.

Step 6. Enable force_ssl in production

Uncomment one line in config/environments/production.rb:

# Force all access to the app over SSL, use Strict-Transport-Security, and use secure cookies.
config.force_ssl = true

force_ssl does three things at the Rails level:

1. Redirects any HTTP request to HTTPS before it reaches your controllers.
2. Sets the Secure flag on all cookies (so they are never sent over plain HTTP).
3. Adds an HSTS header (Strict-Transport-Security) that instructs browsers to remember the HTTPS-only policy for a configurable duration.

We already set HSTS manually in the secure_headers initializer in Part 3. force_ssl being enabled means Rails adds its own HSTS on top. The two don't conflict, the browser just sees the header and caches the policy. But force_ssl is the one that actually enforces the redirect, which secure_headers alone doesn't do.

🛡️ Mitigation in action: MITM (Part 1, vector 9)

The chain is now complete: force_ssl redirects HTTP → HTTPS, secure_headers sets HSTS so browsers remember not to try HTTP again, and Secure cookies ensure auth tokens are never sent in the clear. A network-level attacker has nothing to intercept.

Step 7. Test the updated flow with curl

The CSRF requirement changes the curl commands from Part 3. Here's the updated flow.

Start the server:

bin/rails server

Step 1 — get a CSRF token:

CSRF=$(curl -s -c cookies.txt http://localhost:3000/api/v1/csrf_token | ruby -e "require 'json'; puts JSON.parse(STDIN.read)['csrf_token']")
echo $CSRF

We save the session cookie with -c cookies.txt. The CSRF token is stored in shell variable $CSRF.

Step 2 — register:

curl -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
  -b cookies.txt -c cookies.txt \
  -d '{"user": {"email": "me@example.com", "password": "s3cr3tP@ss", "password_confirmation": "s3cr3tP@ss"}}'

Step 3 - login and capture the new CSRF token:

LOGIN=$(curl -s -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
  -b cookies.txt -c cookies.txt \
  -d '{"email": "me@example.com", "password": "s3cr3tP@ss"}')

echo $LOGIN
CSRF=$(echo $LOGIN | ruby -e "require 'json'; puts JSON.parse(STDIN.read)['csrf_token']")

After login, reset_session invalidated the old session and generated a new one. The response body carries the new CSRF token, which we capture into $CSRF again.

Step 4 — call the protected endpoint:

curl http://localhost:3000/api/v1/me -b cookies.txt

This is a GET so no CSRF token needed.

Step 5 — refresh:

REFRESH=$(curl -s -X POST http://localhost:3000/api/v1/auth/refresh \
  -H "X-CSRF-Token: $CSRF" \
  -b cookies.txt -c cookies.txt)

echo $REFRESH
CSRF=$(echo $REFRESH | ruby -e "require 'json'; puts JSON.parse(STDIN.read)['csrf_token']")

Refresh also calls reset_session, so again we capture the new token from the response.

Step 6 — logout:

curl -X DELETE http://localhost:3000/api/v1/auth/logout \
  -H "X-CSRF-Token: $CSRF" \
  -b cookies.txt

What happens without the CSRF header?

Try sending a POST without X-CSRF-Token and you'll get:

{ "error": "Invalid CSRF token" }

with a 403 Forbidden. Not a stack trace. Not a Rails error page. Just the response we defined in invalid_csrf_token.

Where we are now

The security checklist is nearly complete. CSRF is fully mitigated, SSL is enforced in production, no unhandled exception ever leaks to a client, and serializers mean accidental data exposure through new model fields is no longer possible.

Progress tracker: security vectors from Part 1

Legend: 🟢 Covered, 🟡 Partial, 🔴 Pending

One vector remains: IDOR. It only becomes a real problem once we have resources that belong to users, which is exactly what we build next.

Coming up in Part 5

We add the first real resource, Post, and wire up Pundit policies so users can only access their own records. We also introduce Sqids so database IDs never appear in URLs directly. After that the API is ready for more complex authorization scenarios.

Follow along if you want to get notified when the next part is published. And if anything broke or didn't make sense, drop a comment.