Setup Authentication

setup-authentication

Use this workflow when implementing authentication in Hanami 2.x.

Core principle: Authentication is explicit in every Action. No global magic — each Action declares its auth requirements.

Workflow

Step 1 — Inject Auth Service (inject-dependencies)

• Create an authentication service object
• Register it in the DI container
• Inject it into Actions that need auth
• Handoff condition: Auth service accessible via Deps["authentication"]

Step 2 — Register Provider (register-provider)

• Create config/providers/authentication.rb
• Register the auth service in the start block
• Handoff condition: Auth service registered and injectable

Example — config/providers/authentication.rb:

Hanami.app.register_provider(:authentication) do
  start do
    require "bcrypt"

    register("authentication", MyApp::Authentication::Service.new)
  end
end

Step 3 — Create Actions (create-action)

• Create login Action: validates credentials, sets session/token
• Create logout Action: clears session/token
• Create protected Actions: check auth before processing
• Handoff condition: Login/logout work, protected endpoints require auth

Example — minimal auth service:

# app/authentication/service.rb
module MyApp
  module Authentication
    class Service
      def authenticate(email:, password:, session:)
        user = UserRepository.new.find_by_email(email)
        return false unless user
        return false unless BCrypt::Password.new(user.password_digest) == password

        session[:user_id] = user.id
        true
      end

      def current_user(session)
        return nil unless session[:user_id]

        UserRepository.new.find(session[:user_id])
      end

      def authenticated?(session)
        !current_user(session).nil?
      end
    end
  end
end

Example — login Action:

# app/actions/sessions/create.rb
module MyApp
  module Actions
    module Sessions
      class Create < MyApp::Action
        include Deps["authentication"]

        params do
          required(:email).filled(:string)
          required(:password).filled(:string)
        end

        def handle(request, response)
          halt 422 unless request.params.valid?

          authenticated = authentication.authenticate(
            email: request.params[:email],
            password: request.params[:password],
            session: request.session
          )

          if authenticated
            response.redirect_to "/dashboard"
          else
            response.status = 401
            response.body = { error: "Invalid credentials" }.to_json
          end
        end
      end
    end
  end
end

Example — protected Action:

# app/actions/dashboard/show.rb
module MyApp
  module Actions
    module Dashboard
      class Show < MyApp::Action
        include Deps["authentication"]

        def handle(request, response)
          halt 401 unless authentication.authenticated?(request.session)

          user = authentication.current_user(request.session)
          response.body = { user: user.email }.to_json
        end
      end
    end
  end
end

Step 4 — Handle Errors (handle-errors)

• Return 401 for missing/invalid credentials
• Return 403 for insufficient permissions
• Log auth failures (but not passwords)
• Handoff condition: Correct error responses for auth failures

Verification

After each step, verify the workflow is progressing correctly:

# Verify provider is registered
bundle exec hanami console
> Hanami.app["authentication"]  # Should return auth service instance

# Test login endpoint
curl -X POST http://localhost:2300/sessions \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"secret"}'
# Expect: redirect or 200 with session cookie on success; 401 on failure

# Test protected endpoint without auth
curl http://localhost:2300/dashboard
# Expect: 401 Unauthorized

# Test protected endpoint with session cookie
curl http://localhost:2300/dashboard --cookie "<session-cookie>"
# Expect: 200 with user data

Common Mistakes