authegy 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c939c8d171cedd6e8e7f41d1fb692321365a1f72996420b74a5e2250c81438be
-  data.tar.gz: c02ed8a0ae4e9b88ee8de0131ea8cacb60f2724e5aacdc0f1af296ee8c48d3ed
+  metadata.gz: 2a7fdcc608fb168061d6b17fa23335ee534a0d0fa9b65cd542daf21a7c36b515
+  data.tar.gz: ed2ba96fd8a897153ab2c34879d00c231db2ca3b09dda6eb826505e24217d5ec
 SHA512:
-  metadata.gz: 164ed0276e9bd154d3ffd05f3ea8630b3c82522bb083a87d5d27942015aa4c2aedd18c38afdb291183c9ef3801fffc775ab132387dd548c27050545efa4550d4
-  data.tar.gz: 283427d912da0cda5e0cf9437ff74e8f9ed63806083fee9e9db6fadd1c3f255367339f558d18550b08b4505057d7071e1d29a5ee2d911832033715af1141313e
+  metadata.gz: 585350d7081f58a6122480eaff47e98f05ed233e3633e887d4b9c640c90bb917c913293e0d71301bb0575031abe1bb80441342beeab2f7fad7b5c8c295e8678e
+  data.tar.gz: c1e6c3bf0287abda69a78330755786a236f5ed06a70172d4212052713dacf4e0f0f810c7eb918796a307a46ea7d513b901db3fa3563fd7fa830503ad4971d23b

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Authegy Changelog
 
+## Version 0.0.3
+
+- Fixed User Signup
+- Use router method 'authegy_routes' instead of 'devise_for'
+
+## Version 0.0.2
+
+- Minor correction over the User model template
+
 ## Version 0.0.1
 
 - Initial Implementation

data/README.md

@@ -1,43 +1,94 @@
 # Authegy
 
-The Authegy gem is a library that combines several useful ruby libraries to
-provide an opinionated authentication and role-based authorization models for
+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.
 
-## Installation
+The following libraries are used as the base of Authegy:
+- Devise
+- Doorkeeper
+
+These libraries are used following a particular set of rules:
+
+- Only a single `User` class: whereas `devise` allows 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 `Person` model. We actually can create `Person` records
+  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.
+
+## Getting started
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'authegy'
+gem 'authegy', '~> 0.0.2'
 ```
 
-And then execute:
+Then run `bundle install`.
 
-    $ bundle
+Next, you'll need to run the generator:
 
-Or install it yourself as:
+    $ rails generate authegy:install
 
-    $ gem install authegy
+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.
 
-## Usage
+### Model methods
 
-### Basic Use Case: The User & Role models
+There are several methods available to the `Person` and `User` models, and are
+very similar to the methods found at other RBAC libraries:
 
-- Use only a single "User" class, with several roles associated to it - instead
-  of having multiple "user" classes, which tend to have duplicated code &
-  functionality between them.
-- Roles can also be optionally associated to different "Resource" models, so we
-  can limit the authorization to certain objects. Examples:
-  - "User 2" is an "Administrator" of "Website 2" (so he/she can change the
-    Website 2's URL)
-  - "User 3" is a "Procurement Manager" of "Company 4" (so he/she can place
-    orders on behalf of the Company 4)
+```ruby
 
-![Base Use Case](docs/use-cases/base-use-case.svg)
+# Create a person:
+example_person = Person.create first_name: 'Example', last_name: 'Person', email: 'first@example.com'
+
+# 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
+
+![Base Use Case](docs/use-cases/base-use-case.svg)
 
+- We extracted the `User` fields 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 `email` field is also moved to the `Person` model -
+  we provide the code required for Devise to look in the `people` table.
+- The way we assign roles to a person is using the `RoleAssignment` model. This
+  model also allows us to optionally specify a `resource` to which the assigned
+  role will be limited (or scoped). Notice how the `RoleAssignment` is separated
+  from the actual `Role` model, achieving a higher level of database
+  normalization.
 
 ## Development
 
@@ -54,7 +105,7 @@ git commits and tags, and push the `.gem` file to
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at
-https://github.com/vovimayhem/authegy. This project is intended to be a safe,
+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](http://contributor-covenant.org) code of conduct.
 
@@ -65,6 +116,6 @@ The gem is available as open source under the terms of the
 
 ## Code of Conduct
 
-Everyone interacting in the A2 project’s codebases, issue trackers, chat rooms
-and mailing lists is expected to follow the
-[Code of Conduct](https://github.com/vovimayhem/authegy/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Authegy project’s codebases, issue trackers, chat
+rooms and mailing lists is expected to follow the
+[Code of Conduct](https://github.com/vovimayhem/authegy-gem/blob/master/CODE_OF_CONDUCT.md).

data/lib/authegy/engine.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+require 'authegy/rails/routes'
+
 module Authegy
   class Engine < ::Rails::Engine
     isolate_namespace Authegy

data/lib/authegy/models/user.rb

@@ -15,8 +15,17 @@ module Authegy
     devise :database_authenticatable_with_person_email,
            :validatable_with_person_email
 
-    belongs_to :person, inverse_of: :user, foreign_key: :id
-    delegate :email, :email=, :name, to: :person, allow_nil: true
+    belongs_to :person,
+               class_name: '::Person',
+               inverse_of: :user,
+               foreign_key: :id
+
+    delegate :email, :name, to: :person, allow_nil: true
+
+    def email=(value)
+      return person.email = value if person.present?
+      build_person(email: value).email
+    end
 
     delegate :assigned_roles, :assign_role, :has_role?, :has_any_role?,
              :remove_role, :role_assignments, to: :person

data/lib/authegy/rails/routes.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+module ActionDispatch
+  module Routing
+    class Mapper
+      def authegy_routes(options = {})
+        # Remove the keys that would interfere with the authegy way:
+        options.extract! :class_name, # We'll only use 'User'
+                         :path,       # All devise paths available from root
+                         :singular    # No 'resource name' required
+
+        default_path_names = { sign_in: 'sign-in', sign_out: 'sign-out' }
+        options.reverse_merge! path: '/', path_names: default_path_names
+
+        devise_for :users, options
+      end
+    end
+  end
+end

data/lib/authegy/version.rb

@@ -1,3 +1,3 @@
 module Authegy
-  VERSION = '0.0.2'.freeze
+  VERSION = '0.0.3'.freeze
 end

data/lib/generators/authegy/install_generator.rb

@@ -19,11 +19,7 @@ class InstallGenerator < Rails::Generators::Base
     generate 'authegy:models People'
   end
 
-  def add_devise_routes
-    route <<~STRING
-      devise_for :users,
-                 path: '/',
-                 path_names: { sign_in: 'sign-in', sign_out: 'sign-out' }
-    STRING
+  def add_autegy_routes
+    route 'authegy_routes'
   end
 end

data/lib/generators/authegy/templates/models_migration.erb

@@ -10,8 +10,8 @@ class CreateAuthegyModelTables < ActiveRecord::Migration<%= migration_version %>
 
   def create_people_table
     create_table :people do |t|
-      t.string :first_name, null: false
-      t.string :last_name, null: false
+      t.string :first_name
+      t.string :last_name
       t.string :email, index: { unique: true }
 
       # Feel free to add additional fields, such as 'nickname', etc:

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: authegy
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Roberto Quintanilla
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-03-02 00:00:00.000000000 Z
+date: 2019-03-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -140,6 +140,7 @@ files:
 - lib/authegy/models/role.rb
 - lib/authegy/models/role_assignment.rb
 - lib/authegy/models/user.rb
+- lib/authegy/rails/routes.rb
 - lib/authegy/version.rb
 - lib/devise/models/database_authenticatable_with_person_email.rb
 - lib/devise/models/validatable_with_person_email.rb