It adds support to Devise for sending invitations by email (it requires to be authenticated) and accept the invitation setting the password.
The latest version of DeviseInvitable works with Devise >= 4.6.
If you want to use devise_invitable with earlier Devise releases (4.0 <= x < 4.6), use version 1.7.5.
Install DeviseInvitable gem:
gem install devise_invitableAdd DeviseInvitable to your Gemfile:
gem 'devise_invitable', '~> 2.0.0'Run the following generator to add DeviseInvitable’s configuration option in
the Devise configuration file (config/initializers/devise.rb):
rails generate devise_invitable:installWhen you are done, you are ready to add DeviseInvitable to any of your Devise models using the following generator:
rails generate devise_invitable MODELReplace MODEL by the class name you want to add DeviseInvitable, like User,
Admin, etc. This will add the :invitable flag to your model's Devise
modules. The generator will also create a migration file (if your ORM supports
them).
Follow the walkthrough for Devise and after it's done, follow this walkthrough.
Add :invitable to the devise call in your model (we’re assuming here you
already have a User model with some Devise modules):
class User < ActiveRecord::Base
devise :database_authenticatable, :confirmable, :invitable
endAdd t.invitable to your Devise model migration:
create_table :users do
...
## Invitable
t.string :invitation_token
t.datetime :invitation_created_at
t.datetime :invitation_sent_at
t.datetime :invitation_accepted_at
t.integer :invitation_limit
t.integer :invited_by_id
t.string :invited_by_type
...
end
add_index :users, :invitation_token, unique: trueor for a model that already exists, define a migration to add DeviseInvitable to your model:
def change
add_column :users, :invitation_token, :string
add_column :users, :invitation_created_at, :datetime
add_column :users, :invitation_sent_at, :datetime
add_column :users, :invitation_accepted_at, :datetime
add_column :users, :invitation_limit, :integer
add_column :users, :invited_by_id, :integer
add_column :users, :invited_by_type, :string
add_index :users, :invitation_token, unique: true
endIf you previously used devise_invitable with a :limit on
:invitation_token, remove it:
def up
change_column :users, :invitation_token, :string, limit: nil
end
def down
change_column :users, :invitation_token, :string, limit: 60
endIf you are using Mongoid, define the following fields and indexes within your invitable model:
field :invitation_token, type: String
field :invitation_created_at, type: Time
field :invitation_sent_at, type: Time
field :invitation_accepted_at, type: Time
field :invitation_limit, type: Integer
index( { invitation_token: 1 }, { background: true} )
index( { invitation_by_id: 1 }, { background: true} )You do not need to define a belongs_to relationship, as DeviseInvitable does
this on your behalf:
belongs_to :invited_by, polymorphic: trueRemember to create indexes within the MongoDB database after deploying your changes.
rake db:mongoid:create_indexesDeviseInvitable adds some new configuration options:
invite_for: The period the generated invitation token is valid. After this period, the invited resource won't be able to accept the invitation. Wheninvite_foris0(the default), the invitation won't expire.
You can set this configuration option in the Devise initializer as follow:
# ==> Configuration for :invitable
# The period the generated invitation token is valid.
# After this period, the invited resource won't be able to accept the invitation.
# When invite_for is 0 (the default), the invitation won't expire.
# config.invite_for = 2.weeksor directly as parameters to the devise method:
devise :database_authenticatable, :confirmable, :invitable, invite_for: 2.weeks-
invitation_limit: The number of invitations users can send. The default value ofnilmeans users can send as many invites as they want, there is no limit for any user,invitation_limitcolumn is not used. A setting of0means they can't send invitations. A settingn > 0means they can sendninvitations. You can changeinvitation_limitcolumn for some users so they can send more or less invitations, even with globalinvitation_limit = 0. -
invite_key: The key to be used to check existing users when sending an invitation. You can use multiple keys. This value must be a hash with the invite key as hash keys, and values that respond to the===operator (including procs and regexes). The default value is looking for users by email and validating withDevise.email_regexp. -
validate_on_invite: force a record to be valid before being actually invited. -
resend_invitation: resend invitation if user with invited status is invited again. Enabled by default. -
invited_by_class_name: the class name of the inviting model. If this isnil, polymorphic association is used. -
invited_by_foreign_key: the foreign key to the inviting model (only used ifinvited_by_class_nameis set, otherwise:invited_by_id) -
invited_by_counter_cache: the column name used for counter_cache column. If this isnil(default value), theinvited_byassociation is declared withoutcounter_cache. -
allow_insecure_sign_in_after_accept: automatically sign in the user after they set a password. Enabled by default. -
require_password_on_accepting: require password when user accepts the invitation. Enabled by default. Disable if you don't want to ask or enforce to set password while accepting, because is set when user is invited or it will be set later.
For more details, see config/initializers/devise.rb (after you invoked the
devise_invitable:install generator described above).
All the views are packaged inside the gem. If you'd like to customize the views, invoke the following generator and it will copy all the views to your application:
rails generate devise_invitable:viewsYou can also use the generator to generate scoped views:
rails generate devise_invitable:views usersThen turn scoped views on in config/initializers/devise.rb:
config.scoped_views = truePlease refer to Devise's README for more information about views.
To change the controller's behavior, create a controller that inherits from
Devise::InvitationsController. The available methods are: new, create,
edit, and update. Refer to the original controllers source
before editing any of these actions. Your
controller might now look something like this:
class Users::InvitationsController < Devise::InvitationsController
def update
if some_condition
redirect_to root_path
else
super
end
end
endNow just tell Devise that you want to use your controller, the controller
above is 'users/invitations', so our routes.rb would have this line:
devise_for :users, controllers: { invitations: 'users/invitations' }be sure that you generate the views and put them into the controller that you generated, so for this example it would be:
rails generate devise_invitable:views usersTo change behaviour of inviting or accepting users, you can simply override two methods:
class Users::InvitationsController < Devise::InvitationsController
private
# This is called when creating invitation.
# It should return an instance of resource class.
def invite_resource
# skip sending emails on invite
super { |user| user.skip_invitation = true }
end
# This is called when accepting invitation.
# It should return an instance of resource class.
def accept_resource
resource = resource_class.accept_invitation!(update_resource_params)
# Report accepting invitation to analytics
Analytics.report('invite.accept', resource.id)
resource
end
endWhen you customize your own views, you may end up adding new attributes to forms. Rails 4 moved the parameter sanitization from the model to the controller, causing DeviseInvitable to handle this concern at the controller as well. Read about it in Devise README
There are just two actions in DeviseInvitable that allows any set of parameters to be passed down to the model, therefore requiring sanitization. Their names and the permited parameters by default are:
invite(Devise::InvitationsController#create) - Permits only the authentication keys (likeemail)accept_invitation(Devise::InvitationsController#update) - Permitsinvitation_tokenpluspasswordandpassword_confirmation.
Here is an example of the steps needed to add a first_name, last_name and role to invited Users.
Caution: Adding roles requires additional security measures, such as preventing a standard user from inviting an administrator. Implement appropriate access controls to ensure system security.
Note: These modifications can be applied directly in the InvitationsController if not needed for other Devise actions.
before_action :configure_permitted_parameters, if: :devise_controller?
protected
# Permit the new params here.
def configure_permitted_parameters
devise_parameter_sanitizer.permit(:invite, keys: [:first_name, :last_name, :role])
endclass User < ApplicationRecord
has_many :models
enum role: {Role 1 Name: 0, Role 2 Name: 1, Role 3 Name: 2, etc...}
end<h2><%= t "devise.invitations.new.header" %></h2>
<%= form_for(resource, as: resource_name, url: invitation_path(resource_name), html: { method: :post }) do |f| %>
<%= render "devise/shared/error_messages", resource: resource %>
<% resource.class.invite_key_fields.each do |field| -%>
<div class="field">
<%= f.label field %><br />
<%= f.text_field field %>
</div>
<% end %>
<div class="field">
<%= f.label :first_name %>
<%= f.text_field :first_name %>
</div>
<div class="field">
<%= f.label :last_name %>
<%= f.text_field :last_name %>
</div>
<div class="field">
<%= f.label :role %>
<%= f.select :role, options_for_select(User.roles.map { |key, value| [key.humanize, key] }), {prompt: "Select Role"} %>
</div>
<div class="actions">
<%= f.submit t("devise.invitations.new.submit_button") %>
</div>
<% end %>To send an invitation to a user, use the invite! class method. Note: This
will create a user, and send an email for the invite. :email must be
present in the parameters hash. You can also include other attributes in the
hash. The record will not be validated.
User.invite!(email: '[email protected]', name: 'John Doe')
# => an invitation email will be sent to [email protected]If you want to create the invitation but not send it, you can set
skip_invitation to true.
user = User.invite!(email: '[email protected]', name: 'John Doe') do |u|
u.skip_invitation = true
end
# => the record will be created, but the invitation email will not be sentWhen generating the accept_user_invitation_url yourself, you must use the
raw_invitation_token. This value is temporarily available when you invite a
user and will be decrypted when received.
accept_user_invitation_url(invitation_token: user.raw_invitation_token)When skip_invitation is used, you must also then set the
invitation_sent_at field when the user is sent their token. Failure to do so
will yield "Invalid invitation token" error when the user attempts to accept
the invite. You can set the column, or call deliver_invitation to send the
invitation and set the column:
user.deliver_invitationYou can add :skip_invitation to attributes hash if skip_invitation is
added to attr_accessible.
User.invite!(email: '[email protected]', name: 'John Doe', skip_invitation: true)
# => the record will be created, but the invitation email will not be sentskip_invitation skips sending the email, but sets invitation_token, so
invited_to_sign_up? on the resulting user returns true.
To check if a particular user is created by invitation, irrespective to state
of invitation one can use created_by_invite?
Warning
When using skip_invitation you must send the email with the user object
instance that generated the tokens, as user.raw_invitation_token is
available only to the instance and is not persisted in the database.
You can also set invited_by when using the invite! class method:
User.invite!({ email: '[email protected]' }, current_user) # current_user will be set as invited_byYou can send an invitation to an existing user if your workflow creates them separately:
user = User.find(42)
user.invite!(current_user) # current user is optional to set the invited_by attributeTo find by invitation token use the find_by_invitation_token class method.
user = User.find_by_invitation_token(params[:invitation_token], true)To accept an invitation with a token use the accept_invitation! class
method. :invitation_token must be present in the parameters hash. You can
also include other attributes in the hash.
User.accept_invitation!(invitation_token: params[:invitation_token], password: 'ad97nwj3o2', name: 'John Doe')A callback event is fired before and after an invitation is created (User#invite!) or accepted (User#accept_invitation!). For example, in your resource model you can add:
# Note: callbacks should be placed after devise: :invitable is specified.
before_invitation_created :email_admins
after_invitation_accepted :email_invited_by
def email_admins
# ...
end
def email_invited_by
# ...
endThe callbacks support all options and arguments available to the standard callbacks provided by ActiveRecord.
A pair of scopes to find those users that have accepted, and those that have not accepted, invitations are defined:
User.invitation_accepted # => returns all Users for whom the invitation_accepted_at attribute is not nil
User.invitation_not_accepted # => returns all Users for whom the invitation_accepted_at attribute is nil
User.created_by_invite # => returns all Users who are created by invitations, irrespective to invitation statusSince the invitations controller takes care of all the creation/acceptation of
an invitation, in most cases you wouldn't call the invite! and
accept_invitation! methods directly. Instead, in your views, put a link to
new_user_invitation_path or new_invitation_path(:user) or even
/users/invitation/new to prepare and send an invitation (to a user in this
example).
After an invitation is created and sent, the inviter will be redirected to
after_invite_path_for(inviter, invitee), which is the same path as
signed_in_root_path by default.
After an invitation is accepted, the invitee will be redirected to
after_accept_path_for(resource), which is the same path as
signed_in_root_path by default. If you want to override the path, override
invitations controller and define after_accept_path_for method. This is
useful in the common case that a user is invited to a specific location in
your application. More on Devise's
README, "Controller filters and
helpers" section.
The invitation email includes a link to accept the invitation that looks like
this: /users/invitation/accept?invitation_token=abcd123. When clicked, the
invited must set a password in order to accept its invitation. Note that if
the invitation_token is not present or not valid, the invited is redirected
to invalid_token_path_for(resource_name), which by default is
after_sign_out_path_for(resource_name).
The controller sets the invited_by_id attribute for the new user to the
current user. This will let you easily keep track of who invited whom.
InvitationsController uses authenticate_inviter! filter to restrict who can
send invitations. You can override this method in your
ApplicationController.
Default behavior requires authentication of the same resource as the invited
one. For example, if your model User is invitable, it will allow all
authenticated users to send invitations to other users.
You would have a User model which is configured as invitable and an Admin
model which is not. If you want to allow only admins to send invitations,
simply overwrite the authenticate_inviter! method as follow:
class ApplicationController < ActionController::Base
protected
def authenticate_inviter!
authenticate_admin!(force: true)
end
endAnd include DeviseInvitable::Inviter module into Admin model:
class Admin < ActiveRecord::Base
devise :database_authenticatable, :validatable
include DeviseInvitable::Inviter
endIf you want to get all records invited by a resource, you should define
has_many association in the model allowed to send invitations.
For the default behavior, define it like this:
has_many :invitations, class_name: self.to_s, as: :invited_byFor the previous example, where admins send invitations to users, define it like this:
has_many :invitations, class_name: 'User', as: :invited_byDeviseInvitable uses flash messages with I18n with the flash keys
:send_instructions, :invitation_token_invalid and :updated. To customize
your app, you can modify the generated locale file:
en:
devise:
invitations:
send_instructions: 'An invitation email has been sent to %{email}.'
invitation_token_invalid: 'The invitation token provided is not valid!'
updated: 'Your password was set successfully. You are now signed in.'
updated_not_active: 'Your password was set successfully.'You can also create distinct messages based on the resource you've configured using the singular name given in routes:
en:
devise:
invitations:
user:
send_instructions: 'A new user invitation has been sent to %{email}.'
invitation_token_invalid: 'Your invitation token is not valid!'
updated: 'Welcome on board! You are now signed in.'
updated_not_active: 'Welcome on board! Sign in to continue.'The DeviseInvitable mailer uses the same pattern as Devise to create mail subject messages:
en:
devise:
mailer:
invitation_instructions:
subject: 'You got an invitation!'
user_subject: 'You got a user invitation!'Take a look at the generated locale file to check all available messages.
Check out wiki for translations.
If you are using sub schema in you application, you need to make sure that you
are prioritizing your sub schema scheme over Warden in Rack. For instance, if
you are using the Apartment gem go inside your config/application.rb file,
add the following lines:
module YourSite
class Application < Rails::Application
...
Rails.application.config.middleware.insert_before Warden::Manager, Apartment::Elevators::Subdomain
end
endDeviseInvitable supports ActiveRecord and Mongoid, like Devise.
It's possible to find additional information about DeviseInvitable on the Wiki:
https://github.com/scambra/devise_invitable/wiki
To run tests:
bundle install
bundle exec rake testCheck them all at:
https://github.com/scambra/devise_invitable/contributors
Special thanks to rymai for the Rails 3 support, his fork was a great help.
- Fork the project.
- Make your feature addition or bug fix.
- Add tests for it. This is important so I don't break it in a future version unintentionally.
- Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
- Send me a pull request. Bonus points for topic branches.
Copyright (c) 2019 Sergio Cambra. See LICENSE for details.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent