Blogs from the Ranch

< Back to Our Blog

Simple Subdomain Authentication In Ruby on Rails



Using a subdomain as an account key is a great way to personalize a web application. Rails has a nifty plugin written just for this, but the implementation information is a bit scattered. Here’s a step-by-step guide for implementing, testing, and simulating this powerful feature.

1. Take a look at the Account Location Plugin

Coming in at a concise 30 lines of code, it’s an easy read.

2. Customize the plugin for your needs

The plugin assumes we’re working with an Account model and that an instance variable named @account is the Account associated with the current subdomain. In my case, I wasn’t working with an Account class and I also didn’t want to assign the associated object to an instance variable of the same name (For example, in some cases @account could be assigned to a different account than the one associated with the subdomain).

I’m working with a Heartbeat Dashboard. Here’s my modified code. Instead of installing the plugin, I created a DashboardLocation module:

  module DashboardLocation

    def self.included(controller)
      controller.helper_method(:dashboard_domain, :dashboard_subdomain,
                               :dashboard_host, :dashboard_url,
                               :current_dashboard, :current_subscription)


    def default_dashboard_subdomain
      current_dashboard.subdomain if current_dashboard

    def dashboard_url(dashboard_subdomain = default_dashboard_subdomain,
                      use_ssl = request.ssl?)
      (use_ssl ? "https://" : "http://") + dashboard_host(dashboard_subdomain)

    def dashboard_host(dashboard_subdomain = default_dashboard_subdomain)
      dashboard_host = ""
      dashboard_host << dashboard_subdomain + "."
      dashboard_host << dashboard_domain

    def dashboard_domain
      dashboard_domain = ""
      dashboard_domain << request.subdomains[1..-1].join(".") + "." if request.subdomains.size > 1
      dashboard_domain << request.domain + request.port_string

    def dashboard_subdomain

    def current_dashboard
                     :conditions => ["subdomain = ? and subdomain IS NOT NULL",dashboard_subdomain])

    def ensure_current_dashboard
      return true if current_dashboard
      flash[:warning] = "Please select a dashboard to login."
      redirect_to(:controller => '/home') and return false

3. Install the plugin (or your own module)

If you don’t need to make any modifications, install the plugin straight-up:

  ruby script/plugin install http://dev.rubyonrails.org/svn/rails/plugins/account_location/

If you need a customized module like me, put it in your lib folder (i.e. lib/dashboard_locaton.rb) and require it in your environment.rb file (require ‘dashboard_location’).

4. Add some Test Helpers

I added the methods below to TestHelper to make it easier to test our subdomain functionality. Remember I’m using current_dashboard instead of @account to represent the subdomain record.

  class Test::Unit::TestCase
    # Puts a dashboard into the subdomain
    def dashboard_setup(dashboard = dashboards(:derek_dashboard) )
      @request.host = "#{dashboard.subdomain}.local.host"
      assert_equal dashboard, current_dashboard

    def clear_dashboard
      @request.host = "local.host"
      assert_nil current_dashboard,
        "There is a current dashboard when there shouldn't be: #{current_dashboard}"

    def current_dashboard
      Dashboard.find(:first, :conditions => ["subdomain = ? and subdomain IS NOT NULL",dashboard_subdomain])

    def dashboard_subdomain
  1. Add some Functional Tests
  # failure - invalid subdomain
  @request.host = "invalid.local.host"
  get :index
  assert_redirected_to :controller => 'home'
  assert_not_nil flash[:warning]

  # success
  get :index
  assert_response :success
  assert_template "dashboard/index"

6. Implement the functionality in our controllers

  class ApplicationController < ActionController::Base
    include DashboardLocation
    # ...

7. Verify the tests pass

8. Simulate the environment on your development machine.

Alter your “hosts” file to re-route domain lookups to your local machine (

On Mac OSX and Linux:

  $ sudo vi /etc/hosts

On Windows:


Add an entry for your application domain heartbeathq.com

Add entries for any subdomain you want to test: highgroove.heartbeathq.com rubyonrails.heartbeathq.com

Refresh and clear your cache to make sure lookups are re-routed:

On Mac OSX:

Issue the command in the terminal:

  $ sudo lookupd -flushcache

On Linux:

Linux is pretty good about reading your /etc/hosts file, but to be on the safe side, restart ncsd if it’s running:

  $ sudo /etc/init.d/ncsd restart

On Windows:

Issue the command at the command prompt:

  C:>ipconfig /flushdns

You’ll now be able to access your application through a pretty URL like: http://highgroove.heartbeat.com.

9. Don’t forget…

  • If you’re like me, you may be dealing with 2 records – a record authenticated via the subdomain and a user authenticated and placed in the session. Don’t forget to ensure that the user in the session has access to the subdomain record.

  • Remove the entries we added to /etc/hosts before your site launches.

  • Setup your real DNS server with a CNAME or other wildcard entry and your webserver of choice with the same wildcard mapping for your application.

That’s it! It’s another “why I love Rails” moment – subdomain-as-account-key functionality in 30 lines of code tested and ready for production.

Heartbeat, our Ruby on Rails control panel built during RailsDay 2006, is getting ready to emerge with some very powerful new features. Videos to come late this week.



Not Happy with Your Current App, or Digital Product?

Submit your event

Let's Discuss Your Project

Let's Discuss Your Project