Milia is a multi-tenanting gem for hosted Rails 4.0.x applications which use the devise gem for user authentication and registrations. Milia comes with tailoring for common use cases needing multi-tenanting with user authentication.
- should be transparent to the main application code
- should be symbiotic with user authentication
- should raise exceptions upon attempted illegal access
- should force tenanting (not allow sloppy access to all tenant records)
- should allow application flexibility upon new tenant sign-up, usage of eula information, etc
- should be as non-invasive (as possible) to Rails code
- row-based tenanting is used
- default_scope is used to enforce tenanting
The author used schema-based tenanting in the past but found it deficient for the following reasons: most DBMS are optimized to handle enormous number of rows but not an enormous number of schema (tables). Schema-based tenancy took a performance hit, was seriously time-consuming to backup and restore, was invasive into the Rails code structure (monkey patching), was complex to implement, and couldn't use Rails migration tools as-is.
A tenant == an organization; users == members of the organization.
Only organizations sign up for new tenants, not members (users).
The very first user of an organization, let's call him the Organizer,
is the one responsible for initiating the organizational signup.
The Organizer becomes the first member (user) of the organization (tenant).
Thereafter, other members only obtain entry to the organization (tenant)
by invitation. New tenants are not created for every new user.
milia v1.0.0 is the release version for Rails 4.0.x and is now available for usage.
The last previous release version for Rails 3.2.x can be found in the git branch 'v0.3', but it is essentially obsolete. Go with v1.0.x
- Rails 4.0.x adapted (changes to terms, strong_parameters, default_scope, etc)
- Devise 3.2.x adapted
- All the changes which version 0.3.x advised to be inserted in applications_controller.rb are now automatically loaded into ActionController by milia.
- that includes authenticate_tenant!
- so if you've been using an older version of milia, you'll need to remove that stuff from applications_controller!
- generators for easy install of basic rails/milia/devise
- callback after successful authenticate_tenant!
- debug & info logging and trace for troubleshooting
- improved invite_member support
- revised README instructions
There were numerous requests for me to provide a complete sample web application which uses milia and devise. I have done this. This README will have a brief section on creating and installing the sample application.
This sample app is now running on heroku and you may test it out here: http://sample-milia.herokuapp.com Instructions for deploying to heroku can be found in doc/sample.sh STEP 6 within the milia gem.
Further details about this process can be found via the sources listed below:
- see doc/sample.sh for easy generator usage for setting up and creating a working app. Although all the same information is here in this README, it's perhaps clearer, and presented better, as a step-by-step instruction manual. This README must perforce be more as a reference manual.
- the sample app uses web-theme-app to provide some pleasantly formatted views for your testing pleasure.
- see doc/manual_sample.sh for complete step-by-step instructions for manually setting up and creating a working app.
- if you want to know exactly everything the generators are doing, see the manual_sample.sh
- instructions are very detailed and loaded with comments (600 lines!).
- Stage one: with simple devise and no milia,
- Stage two: installing milia for complete tenanting,
- Stage three: adding in invite_member capability
- the entire sample is also fully available on github, if you wish to check your work. diff can be your friend. this sample on github, however, will always be for the latest release or latest beta (whichever is most recent).
- find it at: https://github.com/dsaronin/sample-milia-app
-
doc/sample.sh -- this document will ALWAYS be the most recent (for example in the edge branch: "newdev")
-
doc/manual_sample.sh -- non-generator-based instructions for manually editing files. (this may no longer be the most recent since further work will focus on the generators)
-
doc/gemfile_addition.txt -- the additions to Gemfile needed for setting up the sample-milia-app
-
github.com/milia/wiki/sample-milia-app-tutorial this should be the same as the manual_sample.sh doc for the current stable release (or last beta version); but markdown formatted https://github.com/dsaronin/milia/wiki/sample-milia-app-tutorial
-
milia README (this document):
- this will be the knowledgable programmer's digest of the essentials
- and thus it won't cover some of the intricacies of actually implementing milia: either the tutorial or sample.sh will do that
- if you're a first time milia implementer, please use both the README and either of the two above documents for assistance: it will save you time.
It is doable, but you'll need to first understand how milia basically is installed. I'd still recommend bringing up the sample-milia-app, getting it working, and then figuring out how to either graft it onto your app. Or (recommended), grafting your app onto it. I prefer to work that way because it's based off of a pure Rails 4.0 and devise 3.2 install.
- Rails 4.0.x
- Devise 3.2.x
-
changes in beta-7: model & controller testing is almost complete; minor bug fixed; mixed-in controller methods are now public, not private.
-
changes in beta-6: user_params added to Tenant.create_new_tenant; ability to add additional whitelist parameters during config
-
changes in beta-5: logging, callback, bug fixes
-
changes in beta-4: corrections to README for Gemfile requirements generator tests for requirements
-
changes in beta-3: improved generators getting a new app started
-
changes in beta-2: invite_member capability
If I'm actively developing, this can be in a state of flux. Use at your own risk.
Milia doesn't have any requirements re roles for users. But you will probably need something in your app to support different roles levels. Devise recommends cancan, but I have not used it and do not know how it might affect milia. In my app, I used to use ACL9 before it encountered version issues with Rails. Rather than debugging it, I spun off my own simplified version which I use now with great success. The gem I wrote is open sourced. It is called kibali and is available at github: https://github.com/dsaronin/kibali. Kibali is a simple replacement for ACL9, a role-based authentication gem. I prefer the non-obstrusive nature of kibali and the clear-cut way it deliniates roles for actions at the start of each controller. This simplicity was also in ACL9. Kibali is primarily oriented for functioning as a before_action role authentication scheme for Rails controllers.
- necessary models: user, tenant
- necessary migrations: user, tenant, tenants_users (join table)
You must understand which of your apps models will be tenanted ( acts_as_tenant ) and which will be universal ( acts_as_universal). Universal data NEVER has critical user/company information in the table. It is usually only for system-wide constants. For example, if you've put too much user information in the users table, you'll need to seperate it out. by definition, the devise user table MUST be universal and should only contain email, encrypted password, and devise-required data. ALL OTHER USER DATA (name, phone, address, etc) should be broken out into a tenanted table (say called member_data) which belongs_to :user, and in the User model, has_one :member_data. Ditto for organization (account or company) information.
Most of your tables (except for pure join tables, users, and tenants) SHOULD BE tenanted. You should rarely have universal tables, even for things you consider to be system settings. At some time in the future, your accounts (organizations) will want to tailor/customize this data. So might as well start off correctly by making the table tenanted. It costs you nothing to do so now at the beginning. It does mean that you will need to seed these tables whenever a new tenant (organizational account) is created.
Finally:
- tenants = organizational accounts and are created via sign up, a one-time event. this also creates the first MEMBER of that account in your app who is usually the organizing admin. This person can then issue invitations (below) to bring other members into the account on the app.
- members = members WITHIN a tenant and are created by invitation only; they do NOT sign up. An invitation is sent to them, they click on an activate or confirm link, and then they become a member of a tenanted group.
- The invitation process involves creating both a new user (within the current_tenant) and its corresponding member_data records.
- ALL models (whether tenanted or universal) are expected to have a field in the table labelled: tenant_id.
- YOUR CODE SHOULD NEVER EVER TRY TO CHANGE OR SET THE tenant_id OF A RECORD. milia will not allow it, milia will check for deviance; milia will raise exceptions if it's wrong; and milia will override it to maintain integrity.
- Tenanted records will have tenant_id set to the appropriate tenant automagically by milia.
- Universal records will have tenant_id always set to nil, automagically by milia; and references to any universal table will ALWAYS expect this field to be nil.
- Pure join tables (has_and_belongs_to_many HABTM associations) get neither designation (tenant nor universal). The way that rails accesses these ensures that it will validate the tenant of joined member. A pure HABTM join table is created with generation such as follows:
rails g migration CreateModel1sModel2sJoinTable model1s model2s
This README describes two different ways to install:
- use of a milia generator to install itself and automate those tweaks for most use cases (recommended method)
- a bare minimum manual setup which requires many minor tweaks; those tweaks will be described in a later section.
Later sections of the README will enumerate:
- how to create a simple working sample rails/devise/milia application
- all the expected tweaks which the generator performed automatically
- advice on advanced usage of milia (from rake tasks, console)
- specifics about the milia API
Multi-tenanting, much like user authentication, exists within the large scheme of an application. I recommend first creating and installing the following complete, but simple, reference Rails application so that you can validate a working setup on your system, and have a reference point for making changes to your own application.
I put these in .bashrc for an Ubuntu system.
export PORT=3000
export RACK_ENV=development
export SMTP_ENTRY=<my smtp password>
# OPTIONAL: recaptcha keys
export RECAPTCHA_PUBLIC_KEY=6LeYAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKpT
export RECAPTCHA_PRIVATE_KEY=6LeBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBgQBv
This example shows getting starting a new rails project in an rvm environment and using git (github) as the SCM, and expecting to use heroku (eventually) as the PaaS (Platform as a Service) provider. Note: foreman is available when you set up the heroku toolbelt (see doc/sample.sh for more details).
This example will set everything up for milia AND devise (you won't need to do devise). It assumes you won't use airbrake, you will use recaptcha for new account sign-ups, and you will use invite_member capability. Skeleton user, tenant, and member models will be created. Before you run db:migrate, you can add any additional fields to the tenant and member models. User model really is primarily only used by devise, and so you shouldn't add anything to this model as it's a universal model. Member is a tenanted model and so this is where all the information for a member should be kept.
$ cd projectspace # if not there already
$ rails new sample-milia-app --skip-bundle
$ echo "sample-milia-app" > sample-milia-app/.ruby-gemset
$ echo "2.0.0" > sample-milia-app/.ruby-version
$ echo "web: bundle exec thin start -R config.ru -p \$PORT -e \$RACK_ENV" > sample-milia-app/Procfile
$ rvm gemset create sample-milia-appChange .gitignore to match your development environment. I just copy my standard .gitignore from another project but you can copy mine from sample-milia-app on github.
$ cd sample-milia-app
$ cp ../<an existing project>/.gitignore .
$ git init
$ git add --all .
$ git commit -am 'initial commit'
$ git remote add origin [email protected]:<git-user>/sample-milia-app.git
$ git push -u origin master
This sample web application depends on my updates to the web-app-theme, as
well as several other gems for the application, which need to be added
to the Gemfile, before running the installer.
You can directly import these into your Gemfile
by getting them from doc/gemfile_addition.txt.
After adding this addition to the Gemfile, please make sure the correct
milia branch is being designated (it sometimes points to edge branch).
$ vim Gemfile
G
:r <path to milia gem>/doc/gemfile_addition.txt
ZZ
$ bundle install
WARNING: don't go commando and try to change everything at once! Don't be a perfectionist and try to bring up a fully written app at once!
Just follow the instructions for creating the sample, exactly, step-by-step. Get the basics working. Then change, adapt, and spice to taste. Please?! Because I'm more inclined to help you solve problems if you've started out by getting the sample working exactly as described! If you've tried to go off into the jungle on your own, you are, well, on your own. And as they say, "get out the way you got in!"
Running the generator below will completely install milia, devise, and a sample app. You will not need to run the "milia:install" given above. You'll need to do the following:
$ rails g milia:install --org_email='<your smtp email for dev work>'
$ rails g web_app_theme:milia
NOTE: The above generator has an option to specify an email address to be used for sending emails for confirmation and account activation.
The generator set up basic information for being able to send the confirmation & activation emails. But, you might need to complete entering in your email and smtp information in the following places:
- config/environments/development.rb
- config/environments/production.rb
$ rake db:create
$ rake db:migrate
$ foreman start
open your browser to http://localhost:3000
And that's all you have to do!
This is the mininum necessary for using milia with a Rails application. If you're new to Rails (or Devise and Milia), then I'd recommend you skip this section and instead follow the instructions (previous section above) for Creating and Installing a Rails/Milia/Devise Sample Application.
In any case, do NOT do both installations.
If you'll be using the recaptcha option, then milia will generate expecting the following environment variables (put them in .bashrc, with the correct keys):
export RECAPTCHA_PUBLIC_KEY=6LeYAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKpT
export RECAPTCHA_PRIVATE_KEY=6LeBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBgQBv
Add to your Gemfile:
gem 'devise', '~>3.2'
gem 'milia', '~>1.0'If you'll be working with any beta or leading edge version, specify as follows:
gem 'milia', :git => 'git://github.com/dsaronin/milia.git', :branch => 'v1.0.0-beta-7'
Then,
$ bundle install
$ rails g milia:install --org_email='<your smtp email for dev work>'
Note: The milia generator has an option to specify an email address to be used for sending emails for confirmation and account activation. Also note that the milia generator runs two devise generators.
Make any changes required to the generated migrations, then:
$ rake db:create
$ rake db:migrate
This information is for reference only. The two generators automatically perform these changes when installing the sample application. Do NOT repeat these steps if you followed the automatic installation of the sample application.
The above generator did everthing that's required. This section will explain why the generator did what it did. You won't need to do any of these steps unless you decide to customize or adapt.
Rails 4 now handles this with a gem:
gem 'activerecord-session_store', github: 'rails/activerecord-session_store'
$ rails g active_record:session_migration
- See https://github.com/plataformatec/devise for how to set up devise.
- The current version of milia requires that devise use a User model.
$ rails g devise:install
$ rails g devise user
Add the following in config/routes.rb to the existing devise_for :users :
as :user do # *MUST* come *BEFORE* devise's definitions (below)
match '/user/confirmation' => 'milia/confirmations#update', :via => :put, :as => :update_user_confirmation
end
devise_for :users, :controllers => {
:registrations => "milia/registrations",
:confirmations => "milia/confirmations",
:sessions => "milia/sessions",
:passwords => "milia/passwords",
}
Add the appropriate line below to config/environments/_ files development.rb, production.rb, test.rb_ (respectively below, editing hosts as appropriate for your app). Make sure you've also correctly set up the ActionMailer::Base.smtp_settings. If you're unclear as to how to do that, refer to the sample-milia-app.
config.action_mailer.default_url_options = { :host => 'localhost:3000' }
config.action_mailer.default_url_options = { :host => 'secure.simple-milia-app.com', :protocol => 'https' }
config.action_mailer.default_url_options = { :host => "www.example.com" }
EDIT: db/migrate/xxxxxxx_devise_create_users.rb and uncomment the confirmable section, it will then look as follows:
## Confirmable
t.string :confirmation_token
t.datetime :confirmed_at
t.datetime :confirmation_sent_at
t.string :unconfirmed_email # Only if using reconfirmable
and uncomment the confirmation_token index line to look as follows
add_index :users, :confirmation_token, :unique => true
and add above the t.timestamps line:
# milia member_invitable
t.boolean :skip_confirm_change_password, :default => false
t.references :tenant
edit config/initializers/devise.rb and change mailer_sender to be your from: email address
config.mailer_sender = "[email protected]"
OPTIONAL (not required for milia): in the same initializer file, locate and uncomment the following lines:
config.pepper = '46f2....'
config.confirmation_keys = [ :email ]
config.email_regexp = /\A[^@]+@[^@]+\z/
ALL models require a tenanting field, whether they are to be universal or to be tenanted. So make sure the following is added to each migration:
db/migrate/xxxxxxx_create_modelXYZ.rb
t.references :tenant
Tenanted models will also require indexes for the tenant field.
add_index :<tablename>, :tenant_id
BUT: Do not add any belongs_to :tenant statements into any of your models. milia will do that for all. I do recommend, however, that you add into your app/models/tenant.rb file, one line per tenanted model such as the following (replacing with your model's name):
has_many :<model>s, :dependency => destroy
The reason for this is that if you wish to have a master destroy tenant action, it will also remove all related tenanted tables and records.
Generate the tenant migration
$ rails g model tenant tenant:references name:string:index
Generate the tenants_users join table migration
$ rails g migration CreateTenantsUsersJoinTable tenants users
EDIT: db/migrate/20131119092046_create_tenants_users_join_table.rb then uncomment the first index line as follows:
t.index [:tenant_id, :user_id]
app/controllers/application_controller.rb add the following line IMMEDIATELY AFTER line 4 protect_from_forgery
before_action :authenticate_tenant! # authenticate user and sets up tenant
rescue_from ::Milia::Control::MaxTenantExceeded, :with => :max_tenants
rescue_from ::Milia::Control::InvalidTenantAccess, :with => :invalid_tenant
# milia defines a default max_tenants, invalid_tenant exception handling
# but you can override if you wish to handle directly
Add the following acts_as_... to designate which model will be used as the key into tenants_users to find the tenant for a given user. Only designate one model in this manner.
app/models/user.rb
class User < ActiveRecord::Base
acts_as_universal_and_determines_account
end # class UserAdd the following acts_as_... to designate which model will be used as the tenant model. It is this id field which designates the tenant for an entire group of users which exist within a single tenanted domain. Only designate one model in this manner.
app/models/tenant.rb
class Tenant < ActiveRecord::Base
acts_as_universal_and_determines_tenant
end # class Tenantwhich the generator might have generated ( both acts_as_tenant and acts_as_universal will specify these ).
Add the following acts_as_universal to ALL models which are to be universal.
acts_as_universalAdd the following acts_as_tenant to ALL models which are to be tenanted. Example for a ficticous Post model:
app/models/post.rb
class Post < ActiveRecord::Base
acts_as_tenant
end # class Post Milia::Control::InvalidTenantAccess
Milia::Control::MaxTenantExceededIn some applications, you will want to set up commonly used variables used throughout your application, after a user and a tenant have been established. This is optional and if the callback is missing, nothing will happen.
app/controllers/application_controller.rb
def callback_authenticate_tenant
# set_environment or whatever else you need for each valid session
end Tenant.create_new_tenant(tenant_params, coupon_params) # see sample code belowwhere the sign-up params are passed, the new tenant must be validated, created, and then returned. Any other kinds of prepatory processing are permitted here, but should be minimal, and should not involve any tenanted models. At this point in the new account sign-up chain, no tenant has been set up yet (but will be immediately after the new tenant has been created).
app/models/tenant.rb
def self.create_new_tenant(tenant_params, user_params, coupon_params)
tenant = Tenant.new(:name => tenant_params[:name])
if new_signups_not_permitted?(coupon_params)
raise ::Milia::Control::MaxTenantExceeded, "Sorry, new accounts not permitted at this time"
else
tenant.save # create the tenant
end
return tenant
end
# ------------------------------------------------------------------------
# new_signups_not_permitted? -- returns true if no further signups allowed
# args: params from user input; might contain a special 'coupon' code
# used to determine whether or not to allow another signup
# ------------------------------------------------------------------------
def self.new_signups_not_permitted?(params)
return false
end Tenant.tenant_signup(user,tenant,other) # see sample code belowThe purpose here is to do any tenant initialization AFTER devise has validated and created a user. Objects for the user and tenant are passed. It is recommended that only minimal processing be done here ... for example, queueing a background task to do the actual work in setting things up for a new tenant.
app/models/tenant.rb
# ------------------------------------------------------------------------
# tenant_signup -- setup a new tenant in the system
# CALLBACK from devise RegistrationsController (milia override)
# AFTER user creation and current_tenant established
# args:
# user -- new user obj
# tenant -- new tenant obj
# other -- any other parameter string from initial request
# ------------------------------------------------------------------------
def self.tenant_signup(user, tenant, other = nil)
# StartupJob.queue_startup( tenant, user, other )
# any special seeding required for a new organizational tenant
Member.create_org_admin(user) # sample if using Member as tenanted member information model
endThis example shows how to display a signup form together with recaptcha. It also shows usage of an optional coupon field for whatever reason you might need. If you're not familiar with haml, leading spaces are significant and are used to indicate logical blocks. Otherwise, it's kinda like erb without all the syntactical cruff. Leading "." indicate div class; "#" indicates a div ID. The example here is taken from sample-milia-app.
app/views/devise/registrations/new.html.haml
%h1 Simple Milia App
.block#block-signup
%h2 New Organizational Sign up
.content
%span.description
%i
If you're a member of an existing group in our system,
click the activate link in the invitation email from your organization's admin.
You should not sign up for a new organizational account.
%br
.flash
- flash.each do |type, message|
%div{ :class => "message #{type}" }
%p= message
- flash.clear # clear contents so we won't see it again
= form_for(resource, :as => resource_name, :url => registration_path(resource_name), :html => { :class => "form" }) do |f|
.group
= f.label :email, :class => "label"
= f.text_field :email, :class => "text_field"
%span.description Ex. [email protected]
.group
= f.label :password, :class => "label"
= f.password_field :password, :class => "text_field"
%span.description must be at least 6 characters
.group
= f.label :password_confirmation, "Re-enter Password", :class => "label"
= f.password_field :password_confirmation, :class => "text_field"
%span.description to confirm your password
.group
= fields_for( :tenant ) do |w|
= w.label( :name, 'Organization', :class => "label" )
= w.text_field( :name, :class => "text_field")
%span.description unique name for your group or organization for the new account
- if ::Milia.use_coupon
.group
= label_tag( 'coupon', 'Coupon code', :class => "label" )
= text_field_tag( "coupon[coupon]", @coupon.to_s, :size => 8, :class => "text_field" )
%span.description optional promotional code, if any
- if ::Milia.use_recaptcha
= recaptcha_tags( :display => { :theme => 'clean', :tabindex => 0 } )
.group.navform.wat-cf
%button.button{ :type => "submit" }
= image_tag "web-app-theme/icons/tick.png"
Sign up
= render :partial => "devise/shared/links"
Your application might allow a user to belong to multiple tenants. You will need to provide some type of mechanism to allow the user to choose which account (thus tenant) they wish to access. Once chosen, in your controller, you will need to put:
app/controllers/any_controller.rb
set_current_tenant( new_tenant_id )Subordinate join tables will not get the Rails default scope. Theoretically, the default scope on the master table alone should be sufficient in restricting answers to the current_tenant alone .. HOWEVER, it doesn't feel right.
If the master table for the join is a universal table, however, you really MUST use the following workaround, otherwise the database will access data in other tenanted areas even if no records are returned. This is a potential security breach. Further details can be found in various discussions about the behavior of databases such as POSTGRES.
The milia workaround is to add an additional .where( where_restrict_tenants(klass1, klass2,...)) for each of the subordinate models in the join.
Comment.joins(stuff).where( where_restrict_tenants(Post, Author) ).allAny controller actions, such as the root_path page, will need to skip the tenant & user authorizations. For example in app/controllers/home_controller.rb place the following near the top of the controller:
skip_before_action :authenticate_tenant!, :only => [ :index ]My app has certain actions which require a token for authentication, instead of a user sign-in. These use cases include an icalendar feed for a particular user's assignments or a generic icalendar feed for all of an organization's events. The tokens are NOT a general replacement for user sign-in for all actions, but merely to enable a simple restful API for certain specific actions. This section will explain how to incorporate token authentication together with milia/devise. Please note that the application assigns to each user an authentication token for this use, as well as creates a generic "guest" for the organization itself for accessing the organization-wide action.
The general scheme is to have a prepend_before_action authenticate_by_token! specified only for those actions allowed. This action determines the "user" required to proceed with the action, signs in that user via devise, then falls through to the normal before_action authenticate_tenant! action which establishes the current_tenant.
Below are some examples of this (typically the token is passed as the id parameter):
app/controllers/application_controller
# ------------------------------------------------------------------------------
# NOTE: be sure to use prepend_before_action authenticate_by_token!
# so that this will occur BEFORE authenticate_tenant!
# ------------------------------------------------------------------------------
# Notice we are passing store false, so the user is not
# actually stored in the session and a token is needed for every request.
# ------------------------------------------------------------------------------
def authenticate_by_token!
# special case for designated actions only
if ( controller_name == "feeder" &&
( user = User.find_user_by_user_feed( params ) )
) ||
( controller_name == "questions" && ['signup_form', 'finish_signup'].include?(action_name) &&
( user = User.find_user_by_user_feed( params ) )
)
# create a special session after authorizing a user
reset_session
sign_in(user, store: false) # devise's way to signin the user
# now continue with tenant authorization & set up
true # ok to continue processing
else
act_path = controller_name.to_s + '/' + action_name.to_s
logger.info("SECURITY - access denied #{Time.now.to_s(:db)} - auth: #{params[:userfeed] }\tuid:#{(user.nil? ? 'n/f' : user.id.to_s)}\tRequest: " + act_path)
render( :nothing => true, :status => :forbidden) # redirect_back # go back to where you were
nil # abort further processing
end
endapp/controllers/feeder_controller
prepend_before_action :authenticate_by_token! # special authtentication by html tokenapp/models/user.rb
# ------------------------------------------------------------------------
# find_user_by_user_feed -- returns a user based on auth code from params
# ------------------------------------------------------------------------
def self.find_user_by_user_feed( params )
# can get auth by either :userfeed or :id
key = ( params[:userfeed].blank? ? params[:id] : params[:userfeed] )
return nil if key.blank? # neither key present; invalid
return User.where( :authentication_token => key ).first # find by the key; nil if invalid
end
def make_authentication_token
self.authentication_token = generate_unique_authentication_token
end
def generate_unique_authentication_token
loop do
token = AuthKey.make_token # this can be anything to generate a random large token
break token unless User.where(authentication_token: token).first
end
endNote that even when running the console, ($ rails console) it will be run in multi-tenanting mode. You will need to establish a current_user and setup the current_tenant, otherwise most Model DB accesses will fail.
For the author's own application, I have set up a small ruby file which I load when I start the console. This does the following:
def change_tenant(my_id,my_tenant_id)
@me = User.find( my_id )
@w = Tenant.find( my_tenant_id )
Tenant.set_current_tenant @w
end
change_tenant(1,1) # or whatever is an appropriate starting user, tenantDuring the Tenant.create_new_tenant part of the sign-up process, three sets of whitelisted parameters are passed to the method: The parameters for tenant, user, and coupon. But some applications might require more or other parameters than the ones expected by milia. Sometimes the application might need to add some parameters of its own, such a EULA version number, additions to an activation message, or a unique name for the tenant itself.
Milia has a mechanism to add additional parameters to be whitelisted. In config/initializers/milia.rb you can add a list of symbols for the additional parameters to each of a config setting for any of the three (tenant, user, or coupon). The example below shows how.
# whitelist user params list
# allows an app to expand the permitted attribute list
# specify each attribute as a symbol
# example: [:name]
config.whitelist_user_params = [:eula_id, :message]
# whitelist tenant params list
# allows an app to expand the permitted attribute list
# specify each attribute as a symbol
# example: [:name]
config.whitelist_tenant_params = [:company, :cname]
# whitelist coupon params list
# allows an app to expand the permitted attribute list
# specify each attribute as a symbol
# example: [:coupon]
config.whitelist_coupon_params = [:vendor]To keep this discussion simple, we'll give the example of using class Member < Activerecord::Base which will be a tenanted table for keeping information regarding all the members in a given organization. The name "Member" is not a requirement of milia. But this is how you would set up an invite_member capability. It is in this event, that you will require the line in the Tenant post-processing hook tenant_signup
Member.create_org_admin(user)which also creates the Member record for the initial admin on the account.
$ rails g resource member tenant:references user:references first_name:string last_name:string favorite_color:string
ADD to app/models/tenant.rb
has_many :members, dependent: :destroyADD to app/models/user.rb
has_one :member, :dependent => :destroyEDIT app/models/member.rb REMOVE belongs_to :tenant ADD
acts_as_tenant
DEFAULT_ADMIN = {
first_name: "Admin",
last_name: "Please edit me"
}
def self.create_new_member(user, params)
# add any other initialization for a new member
return user.create_member( params )
end
def self.create_org_admin(user)
new_member = create_new_member(user, DEFAULT_ADMIN)
unless new_member.errors.empty?
raise ArgumentError, new_member.errors.full_messages.uniq.join(", ")
end
return new_member
endCREATE a form for inputting new member information for an invite (below is a sample only) app/views/members/new.html.haml
%h1 Simple Milia App
.block#block-signup
%h2 Invite a new member into #{@org_name}
.content.login
.flash
- flash.each do |type, message|
%div{ :class => "message #{type}" }
%p= message
- flash.clear # clear contents so we won't see it again
= form_for(@member, :html => { :class => "form login" }) do |f|
- unless @member.errors.empty? && @user.errors.empty?
#errorExplanation.group
%ul
= @member.errors.full_messages.uniq.inject(''){|str, msg| (str << "<li> #{msg}") }.html_safe
= @user.errors.full_messages.uniq.inject(''){|str, msg| (str << "<li> #{msg}") }.html_safe
= fields_for( :user ) do |w|
.group
= w.label :email, :class => "label "
= w.text_field :email, :class => "text_field"
%span.description Ex. test@example.com; must be unique
.group
= f.label :first_name, :class => "label "
= f.text_field :first_name, :class => "text_field"
.group
= f.label :last_name, :class => "label "
= f.text_field :last_name, :class => "text_field"
.group
= f.label :favorite_color, :class => "label "
= f.text_field :favorite_color, :class => "text_field"
%span.description What is your favorite color?
.group.navform.wat-cf
%button.button{ :type => "submit" }
= image_tag "web-app-theme/icons/key.png"
Create user and inviteYou will need a members-only landing page for after someone successfully signs into your app. Here is what I typically do:
# REPLACE the empty def index ... end with following ADD:
# this will give you improved handling for letting user know
# what is expected. If you want to have a welcome page for
# signed in users, uncomment the redirect_to line, etc.
def index
if user_signed_in?
# was there a previous error msg carry over? make sure it shows in flasher
flash[:notice] = flash[:error] unless flash[:error].blank?
redirect_to( welcome_path() )
else
if flash[:notice].blank?
flash[:notice] = "sign in if your organization has an account"
end
end # if logged in .. else first time
end
def welcome
end set_current_tenant( tenant_id )
# raise InvalidTenantAccess unless tenant_id is one of the current_user valid tenantsset_current_tenant can be used to change the current_tenanted (for example, if a member can belong to multiple tenants and wants to switch between them). See example else in this README. NOTE: you will normally NEVER use this. Milia does this automatically during authorize_tenant! so you never should at the beginning of a session.
Tenant.current_tenant -- returns tenant object for the current tenant; nil if none
Tenant.current_tenant_id -- returns tenant_id for the current tenant; nil if noneIf you need to gain access to tenant object itself (say to get the name of the tenant), then use these accessor methods.
From background jobs (only at the start of the task); tenant can either be a tenant object or an integer tenant_id; anything else will raise exception. set_current_tenant -- is model-level ability to set the current tenant NOTE: USE WITH CAUTION normally this should NEVER be done from the models ... it is only useful and safe WHEN performed at the start of a background job (DelayedJob#perform) or at start of rails console, or a rake task.
Tenant.set_current_tenant( tenant )
raise ArgumentError, "invalid tenant object or id"You must cd into the milia/test directory. Then run test:units, test:functionals seperately. For some reason, rake test won't work and yields errors.
$ cd test
$ rake db:create
$ rake db:migrate
$ rake db:test:prepare
$ rake test:units
$ rake test:functionals- All models, including milia-added methods, are tested.
- Functional testing currently covers all milia-added controller methods.
- TBD: milia overrides of devise registration, confirmation controllers
- Milia designates a default_scope for all models (both universal and tenanted). From Rails 3.2 onwards, the last designated default scope overrides any prior scopes and will invalidate multi-tenanting; so DO NOT USE default_scope
- Milia uses Thread.current[:tenant_id] to hold the current tenant for the existing Action request in the application.
- SQL statements executed outside the context of ActiveRecord pose a potential danger; the current milia implementation does not extend to the DB connection level and so cannot enforce tenanting at this point.
- The tenant_id of a universal model will always be forced to nil.
- The tenant_id of a tenanted model will be set to the current_tenant of the current_user upon creation.
- HABTM (has_and_belongs_to_many) associations don't have models; they shouldn't have id fields (setup as below) nor any field other than the joined references; they don't have a tenant_id field; rails will invoke the default_scope of the appropriate joined table which does have a tenant_id field.
- Check out the three-part blog discussion of Multi-tenanting Ruby on Rails Applications on Heroku at: http://myrailscraft.blogspot.com/2013/05/multi-tenanting-ruby-on-rails.html
- See the Milia tutorial at: http://myrailscraft.blogspot.com/2013/05/multi-tenanting-ruby-on-rails_3982.html
- see code & setup sample in test/railsapp, which is also used to run the tests.
- see milia wiki on github for a CHANGE HISTORY page.
- Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
- Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
- Fork the project
- Start a feature/bugfix branch
- Commit and push until you are happy with your contribution
- Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
- Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
Copyright (c) 2014 Daudi Amani. See LICENSE.txt for further details.