The Authegy gem is a library that combines several top-grade ruby libraries to provide an opinionated authentication and role-based authorization solution for your rails apps.
The following libraries are used as the base of Authegy:
These libraries are used following a particular set of rules:
- Only a single
deviseallows for multiple "authenticatable" models, we're going use single class, to which we can assign different roles instead.
- The "profile" user data - such as names, email, phone, etc. - is extracted
into a separate
Personmodel. We actually can create
Personrecords without an associated user, enabling us to manage a "contact list".
- Roles added to a given person can be assigned either unlimited, or scoped to a given "resource" object.
- The only way of giving access to an app's RESTAPI (where available) is through an OAuth2 flow (i.e. access token, etc) - that's where Doorkeeper comes into play. Given that our most common use case for RESTAPIs is to be consumed by non-confidential apps (Single-page apps, mobile apps, etc), we're avoiding other solutions such as Devise JWT, Devise Token Auth, etc.
- All OAuth2 (doorkeeper) apps will have an owner, and admin roles may be given to other people to manage the apps.
- Restrictions coming from the OAuth2 access token permissions will be added to those already in effect from roles for the token's resource owner.
Add this line to your application's Gemfile:
gem 'authegy', '~> 0.0.2'
Next, you'll need to run the generator:
$ rails generate authegy:install
The install generator will run the install routines for the required libraries ( devise, etc), and will also generate the required models, database migration and routes to start working with the authegy model.
There are several methods available to the
User models, and are
very similar to the methods found at other RBAC libraries:
# Create a person: example_person = Person.create first_name: 'Example', last_name: 'Person', email: 'firstname.lastname@example.org' # Assign a role to this person - The role will be created if it doesn't exist: example_person.assign_role :administrator # Assign a user to this person - he/she will now have the ability to sign-in: example_user = example_person.create_user! password: '123456' # You can assign roles scoped to a particular resource: example_person.assign_role :moderator, Discussion.last # You can test if the person has a role: example_person.has_role? :moderator, Discussion.last # All the role management methods are available to the `User` model via method # delegation: example_user.assign_role :moderator, Discussion.first example_user.has_role? :moderator, Discussion.first
The Authegy model, in detail
- We extracted the
Userfields not fundamental to the process of authentication into the model
Person. This allows us to also cover cases in which we are asked to manage a "contact list", with people that either can sign-in or not. Notice the
Personmodel - we provide the code required for Devise to look in the
- The way we assign roles to a person is using the
RoleAssignmentmodel. This model also allows us to optionally specify a
resourceto which the assigned role will be limited (or scoped). Notice how the
RoleAssignmentis separated from the actual
Rolemodel, achieving a higher level of database normalization.
After checking out the repo, run
bin/setup to install dependencies. Then, run
rake spec to run the tests. You can also run
bin/console for an interactive
prompt that will allow you to experiment.
To install this gem onto your local machine, run
bundle exec rake install. To
release a new version, update the version number in
version.rb, and then run
bundle exec rake release, which will create a git tag for the version, push
git commits and tags, and push the
.gem file to
Bug reports and pull requests are welcome on GitHub at https://github.com/vovimayhem/authegy-gem. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the Authegy project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the Code of Conduct.