rodauth-rails 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8163d64892cbebd867182d15148f3099abb3ed49ae3e07a89a5adea6606623d2
-  data.tar.gz: 3cc7990e0af8e5ffb2ac959f989fb45cf538490412adfc908571823e5dd7b160
+  metadata.gz: 0f1312dbd1bb4dc0d954c77a5ff350b5c9e1ff3fc4dd45b8834cd3e7d0280a22
+  data.tar.gz: 5dda5720126361589a428add9b8256b35aa53644166ca7a8a6d14c5baef53f02
 SHA512:
-  metadata.gz: 99005d6864310fa3a36f8314a13588900a5ac1559af7a77d75cb5aba66b0b829d32c83fe66a3f5a7ced098de32b39396edd666919177836bb84b35a0de3a558b
-  data.tar.gz: 2d66b5ab43d05b26483cb3d69181c506b19a937fa77a2d7d66a38708f6357fae7bd2e605cc0a96affdd8fed822076dccb1603577338e68620c70a816fc45db7a
+  metadata.gz: f70e5a44db25c016fe92169be342d1f489cd0e3307fe6c06dbe822c28c05f55dc696b26721836d315daabbbfb0889d18357cec3bb7aa52932649f5ecb08ceedb
+  data.tar.gz: 6af3cd43f9266729049d984c9da58beff019dd2f0148465d65c8f814602d9a9678308d752ef469f08ab381a1373b919d1e61b62b204751d95ca57d10ed05de2a

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.8.0 (2021-01-03)
+
+* Add `--api` option to `rodauth:install` generator for choosing JSON-only configuration (@janko)
+
+* Don't blow up when a Rodauth request is made using an unsupported HTTP verb (@janko)
+
 ## 0.7.0 (2020-11-27)
 
 * Add `#rails_controller_eval` method for running code in context of a controller instance (@janko)

data/README.md

@@ -12,7 +12,25 @@ Useful links:
 Articles:
 
 * [Rodauth: A Refreshing Authentication Solution for Ruby](https://janko.io/rodauth-a-refreshing-authentication-solution-for-ruby/)
-* [Adding Authentication in Rails 6 with Rodauth](https://janko.io/adding-authentication-in-rails-with-rodauth/)
+* [Adding Authentication in Rails with Rodauth](https://janko.io/adding-authentication-in-rails-with-rodauth/)
+* [Adding Multifactor Authentication in Rails with Rodauth](https://janko.io/adding-multifactor-authentication-in-rails-with-rodauth/)
+
+## Why Rodauth?
+
+There are already several popular authentication solutions for Rails (Devise,
+Sorcery, Clearance, Authlogic), so why would you choose Rodauth? Well, because
+it has many advantages over the mentioned alternatives:
+
+* multifactor authentication ([TOTP][otp], [SMS codes][sms_codes], [recovery codes][recovery_codes], [WebAuthn][webauthn])
+* standardized [JSON API support][jwt] (for every feature)
+* enterprise security features ([password complexity][password_complexity], [disallow password reuse][disallow_password_reuse], [password expiration][password_expiration], [session expiration][session_expiration], [single session][single_session], [account expiration][account_expiration])
+* [email authentication][email_auth] (aka "passwordless")
+* [audit logging][audit_logging] (for any action)
+* ability to protect password hashes even in case of SQL injection ([more details][password protection])
+* additional bruteforce protection for tokens ([more details][bruteforce tokens])
+* uniform configuration DSL (any setting can be static or dynamic)
+* consistent before/after hooks around everything
+* dedicated object encapsulating all authentication logic
 
 ## Upgrading
 
@@ -21,14 +39,14 @@ Articles:
 Starting from version 0.7.0, rodauth-rails now correctly detects Rails
 application's `secret_key_base` when setting default `hmac_secret`, including
 when it's set via credentials or `$SECRET_KEY_BASE` environment variable. This
-means authentication will be more secure by default, and Rodauth features that
-require `hmac_secret` should now work automatically as well.
+means that your authentication will now be more secure by default, and Rodauth
+features that require `hmac_secret` should now work automatically as well.
 
 However, if you've already been using rodauth-rails in production, where the
 `secret_key_base` is set via credentials or environment variable and `hmac_secret`
 was not explicitly set, the fact that your authentication will now start using
 HMACs has backwards compatibility considerations. See the [Rodauth
-documentation](hmac) for instructions on how to safely transition, or just set
+documentation][hmac] for instructions on how to safely transition, or just set
 `hmac_secret nil` in your Rodauth configuration.
 
 ## Installation
@@ -48,10 +66,17 @@ Then run `bundle install`.
 
 Next, run the install generator:
 
-```
+```sh
 $ rails generate rodauth:install
 ```
 
+Or if you want Rodauth endpoints to be exposed via JSON API:
+
+```sh
+$ rails generate rodauth:install --api
+$ bundle add jwt
+```
+
 The generator will create the following files:
 
 * Rodauth migration at `db/migrate/*_create_rodauth.rb`
@@ -185,14 +210,12 @@ Using this information, we could add some basic authentication links to our
 navigation header:
 
 ```erb
-<ul>
-  <% if rodauth.authenticated? %>
-    <li><%= link_to "Sign out", rodauth.logout_path, method: :post %></li>
-  <% else %>
-    <li><%= link_to "Sign in", rodauth.login_path %></li>
-    <li><%= link_to "Sign up", rodauth.create_account_path %></li>
-  <% end %>
-</ul>
+<% if rodauth.logged_in? %>
+  <%= link_to "Sign out", rodauth.logout_path, method: :post %>
+<% else %>
+  <%= link_to "Sign in", rodauth.login_path %>
+  <%= link_to "Sign up", rodauth.create_account_path %>
+<% end %>
 ```
 
 These routes are fully functional, feel free to visit them and interact with the
@@ -208,7 +231,7 @@ retrieves the corresponding account record:
 ```rb
 # app/controllers/application_controller.rb
 class ApplicationController < ActionController::Base
-  before_action :current_account, if: -> { rodauth.authenticated? }
+  before_action :current_account, if: -> { rodauth.logged_in? }
 
   private
 
@@ -382,7 +405,7 @@ $ rails generate rodauth:mailer
 ```
 
 This will create a `RodauthMailer` with the associated mailer views in
-`app/views/rodauth_mailer` directory.
+`app/views/rodauth_mailer` directory:
 
 ```rb
 # app/mailers/rodauth_mailer.rb
@@ -434,9 +457,9 @@ end
 ```
 
 This approach can be used even if you're using a 3rd-party service for
-transactional emails, where emails are sent via API requests instead of
-SMTP. Whatever the `create_*_email` block returns will be passed to
-`send_email`, so you can be creative.
+transactional emails, where emails are sent via HTTP instead of SMTP. Whatever
+the `create_*_email` block returns will be passed to `send_email`, so you can
+be creative.
 
 ### Migrations
 
@@ -458,37 +481,6 @@ class CreateRodauthOtpSmsCodesRecoveryCodes < ActiveRecord::Migration
 end
 ```
 
-### JSON API
-
-JSON API support in Rodauth is provided by the [JWT feature]. First you'll need
-to add the [JWT gem] to your Gemfile:
-
-```rb
-gem "jwt"
-```
-
-The following configuration will enable the Rodauth endpoints to be accessed
-via JSON requests (in addition to HTML requests):
-
-```rb
-# app/lib/rodauth_app.rb
-class RodauthApp < Rodauth::Rails::App
-  configure(json: true) do
-    # ...
-    enable :jwt
-    jwt_secret "...your secret key..."
-    # ...
-  end
-end
-```
-
-If you want the endpoints to be only accessible via JSON requests, or if your
-Rails app is in API-only mode, instead of `json: true` pass `json: :only` to
-the configure method.
-
-Make sure to store the `jwt_secret` in a secure place, such as Rails
-credentials or environment variables.
-
 ### Calling controller methods
 
 When using Rodauth before/after hooks or generally overriding your Rodauth
@@ -585,13 +577,38 @@ integration for Rodauth:
 * runs Action Controller callbacks & rescue handlers around Rodauth actions
 * uses Action Mailer for sending emails
 
-The `configure { ... }` method wraps configuring the Rodauth plugin, forwarding
+The `configure` method wraps configuring the Rodauth plugin, forwarding
 any additional [plugin options].
 
 ```rb
-configure { ... }             # defining default Rodauth configuration
-configure(json: true) { ... } # passing options to the Rodauth plugin
-configure(:secondary) { ... } # defining multiple Rodauth configurations
+class RodauthApp < Rodauth::Rails::App
+  configure { ... }             # defining default Rodauth configuration
+  configure(json: true) { ... } # passing options to the Rodauth plugin
+  configure(:secondary) { ... } # defining multiple Rodauth configurations
+end
+```
+
+The `route` block is provided by Roda, and it's called on each request before
+it reaches the Rails router.
+
+```rb
+class RodauthApp < Rodauth::Rails::App
+  route do |r|
+    # ... called before each request ...
+  end
+end
+```
+
+Since `Rodauth::Rails::App` is just a Roda subclass, you can do anything you
+would with a Roda app, such as loading additional Roda plugins:
+
+```rb
+class RodauthApp < Rodauth::Rails::App
+  plugin :request_headers # easier access to request headers
+  plugin :typecast_params # methods for conversion of request params
+  plugin :default_headers, { "Foo" => "Bar" }
+  # ...
+end
 ```
 
 ### Sequel
@@ -607,6 +624,142 @@ connection (using the [sequel-activerecord_connection] gem).
 This means that, from the usage perspective, Sequel can be considered just
 as an implementation detail of Rodauth.
 
+## JSON API
+
+JSON API support in Rodauth is provided by the [JWT feature][jwt]. You'll need
+to install the [JWT gem], enable JSON support and enable the JWT feature:
+
+```sh
+$ bundle add jwt
+```
+```rb
+# app/lib/rodauth_app.rb
+class RodauthApp < Rodauth::Rails::App
+  configure(json: :only) do
+    # ...
+    enable :jwt
+    # make sure to store the JWT secret below in a safe place
+    jwt_secret "...your secret key..."
+    # ...
+  end
+end
+```
+
+With the above configuration, Rodauth routes will only be accessible via JSON
+requests. If you still want to allow HTML access alongside JSON, change `json:
+:only` to `json: true`.
+
+Emails will automatically work in JSON-only mode, because `Rodauth::Rails::App`
+comes with Roda's `render` plugin loaded. They are customized the same as in
+the non-JSON case.
+
+## OmniAuth
+
+While Rodauth doesn't yet come with [OmniAuth] integration, we can build one
+ourselves using the existing Rodauth API.
+
+In order to allow the user to login via multiple external providers, let's
+create an `account_identities` table that will have a many-to-one relationship
+with the `accounts` table:
+
+```sh
+$ rails generate model AccountIdentity
+```
+```rb
+# db/migrate/*_create_account_identities.rb
+class CreateAccountIdentities < ActiveRecord::Migration
+  def change
+    create_table :account_identities do |t|
+      t.references :account, null: false, foreign_key: { on_delete: :cascade }
+      t.string :provider, null: false
+      t.string :uid, null: false
+      t.jsonb :info, null: false, default: {} # adjust JSON column type for your database
+
+      t.timestamps
+
+      t.index [:provider, :uid], unique: true
+    end
+  end
+end
+```
+```rb
+# app/models/account_identity.rb
+class AcccountIdentity < ApplicationRecord
+  belongs_to :account
+end
+```
+```rb
+# app/models/account.rb
+class Account < ApplicationRecord
+  has_many :identities, class_name: "AccountIdentity"
+end
+```
+
+Let's assume we want to implement Facebook login, and have added the
+corresponding OmniAuth strategy to the middleware stack, together with an
+authorization link on the login form:
+
+```rb
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :facebook, ENV["FACEBOOK_APP_ID"], ENV["FACEBOOK_APP_SECRET"],
+    scope: "email", callback_path: "/auth/facebook/callback"
+end
+```
+```erb
+<%= link_to "Login via Facebook", "/auth/facebook" %>
+```
+
+Let's implement the OmniAuth callback endpoint on our Rodauth controller:
+
+```rb
+# config/routes.rb
+Rails.application.routes.draw do
+  # ...
+  get "/auth/:provider/callback", to: "rodauth#omniauth"
+end
+```
+```rb
+# app/controllres/rodauth_controller.rb
+class RodauthController < ApplicationController
+  def omniauth
+    auth = request.env["omniauth.auth"]
+
+    # attempt to find existing identity directly
+    identity = AccountIdentity.find_by(provider: auth["provider"], uid: auth["uid"])
+
+    if identity
+      # update any external info changes
+      identity.update!(info: auth["info"])
+      # set account from identity
+      account = identity.account
+    end
+
+    # attempt to find an existing account by email
+    account ||= Account.find_by(email: auth["info"]["email"])
+
+    # disallow login if account is not verified
+    if account && account.status != rodauth.account_open_status_value
+      redirect_to rodauth.login_path, alert: rodauth.unverified_account_message
+      return
+    end
+
+    # create new account if it doesn't exist
+    unless account
+      account = Account.create!(email: auth["info"]["email"])
+    end
+
+    # create new identity if it doesn't exist
+    unless identity
+      account.identities.create!(provider: auth["provider"], uid: auth["uid"], info: auth["info"])
+    end
+
+    # login with Rodauth
+    rodauth.account_from_login(account.email)
+    rodauth.login("omniauth")
+  end
+end
+```
+
 ## Configuring
 
 For the list of configuration methods provided by Rodauth, see the [feature
@@ -640,6 +793,37 @@ Rodauth::Rails.configure do |config|
 end
 ```
 
+## Custom extensions
+
+When developing custom extensions for Rodauth inside your Rails project, it's
+better to use plain modules (at least in the beginning), because Rodauth
+feature API doesn't yet support Zeitwerk reloading well.
+
+```rb
+# app/lib/rodauth_argon2.rb
+module RodauthArgon2
+  def password_hash(password)
+    Argon2::Password.create(password, t_cost: password_hash_cost, m_cost: password_hash_cost)
+  end
+
+  def password_hash_match?(hash, password)
+    Argon2::Password.verify_password(password, hash)
+  end
+end
+```
+```rb
+# app/lib/rodauth_app.rb
+class RodauthApp < Rodauth::Rails::App
+  configure do
+    # ...
+    auth_class_eval do
+      include RodauthArgon2
+    end
+    # ...
+  end
+end
+```
+
 ## Testing
 
 If you're writing system tests, it's generally better to go through the actual
@@ -712,6 +896,8 @@ Rodauth method for creating database functions:
 
 ```rb
 # db/migrate/*_create_rodauth_database_functions.rb
+require "rodauth/migrations"
+
 class CreateRodauthDatabaseFunctions < ActiveRecord::Migration
   def up
     Rodauth.create_database_authentication_functions(DB)
@@ -776,7 +962,6 @@ conduct](https://github.com/janko/rodauth-rails/blob/master/CODE_OF_CONDUCT.md).
 [Rodauth]: https://github.com/jeremyevans/rodauth
 [Sequel]: https://github.com/jeremyevans/sequel
 [feature documentation]: http://rodauth.jeremyevans.net/documentation.html
-[JWT feature]: http://rodauth.jeremyevans.net/rdoc/files/doc/jwt_rdoc.html
 [JWT gem]: https://github.com/jwt/ruby-jwt
 [Bootstrap]: https://getbootstrap.com/
 [Roda]: http://roda.jeremyevans.net/
@@ -786,3 +971,19 @@ conduct](https://github.com/janko/rodauth-rails/blob/master/CODE_OF_CONDUCT.md).
 [sequel-activerecord_connection]: https://github.com/janko/sequel-activerecord_connection
 [plugin options]: http://rodauth.jeremyevans.net/rdoc/files/README_rdoc.html#label-Plugin+Options
 [hmac]: http://rodauth.jeremyevans.net/rdoc/files/README_rdoc.html#label-HMAC
+[OmniAuth]: https://github.com/omniauth/omniauth
+[otp]: http://rodauth.jeremyevans.net/rdoc/files/doc/otp_rdoc.html
+[sms_codes]: http://rodauth.jeremyevans.net/rdoc/files/doc/sms_codes_rdoc.html
+[recovery_codes]: http://rodauth.jeremyevans.net/rdoc/files/doc/recovery_codes_rdoc.html
+[webauthn]: http://rodauth.jeremyevans.net/rdoc/files/doc/webauthn_rdoc.html
+[jwt]: http://rodauth.jeremyevans.net/rdoc/files/doc/jwt_rdoc.html
+[email_auth]: http://rodauth.jeremyevans.net/rdoc/files/doc/email_auth_rdoc.html
+[audit_logging]: http://rodauth.jeremyevans.net/rdoc/files/doc/audit_logging_rdoc.html
+[password protection]: https://github.com/jeremyevans/rodauth#label-Password+Hash+Access+Via+Database+Functions
+[bruteforce tokens]: https://github.com/jeremyevans/rodauth#label-Tokens
+[password_complexity]: http://rodauth.jeremyevans.net/rdoc/files/doc/password_complexity_rdoc.html
+[disallow_password_reuse]: http://rodauth.jeremyevans.net/rdoc/files/doc/disallow_password_reuse_rdoc.html
+[password_expiration]: http://rodauth.jeremyevans.net/rdoc/files/doc/password_expiration_rdoc.html
+[session_expiration]: http://rodauth.jeremyevans.net/rdoc/files/doc/session_expiration_rdoc.html
+[single_session]: http://rodauth.jeremyevans.net/rdoc/files/doc/single_session_rdoc.html
+[account_expiration]: http://rodauth.jeremyevans.net/rdoc/files/doc/account_expiration_rdoc.html

data/lib/generators/rodauth/install_generator.rb

@@ -13,6 +13,15 @@ module Rodauth
         source_root "#{__dir__}/templates"
         namespace "rodauth:install"
 
+        # The :api option is a Rails-recognized option that always
+        # defaults to false, so we make it use our provided default
+        # value instead.
+        def self.default_value_for_option(name, options)
+          name == :api ? options[:default] : super
+        end
+
+        class_option :api, type: :boolean, desc: "Generate JSON-only configuration"
+
         def create_rodauth_migration
           return unless defined?(ActiveRecord::Base)
 
@@ -75,9 +84,11 @@ module Rodauth
         end
 
         def api_only?
-          return unless ::Rails.gem_version >= Gem::Version.new("5.0")
-
-          ::Rails.application.config.api_only
+          if options.key?(:api)
+            options[:api]
+          elsif ::Rails.gem_version >= Gem::Version.new("5.0")
+            ::Rails.application.config.api_only
+          end
         end
 
         def migration_features

data/lib/rodauth/rails/app.rb

@@ -1,4 +1,6 @@
 require "roda"
+require "rodauth"
+require "rodauth/rails/feature"
 
 module Rodauth
   module Rails

data/lib/rodauth/rails/feature.rb

@@ -68,9 +68,11 @@ module Rodauth
 
       if rails_controller_instance.performed?
         rails_controller_response
-      else
+      elsif result
         result[1].merge!(rails_controller_instance.response.headers)
         throw :halt, result
+      else
+        result
       end
     end
 

data/lib/rodauth/rails/version.rb

@@ -1,5 +1,5 @@
 module Rodauth
   module Rails
-    VERSION = "0.7.0"
+    VERSION = "0.8.0"
   end
 end

data/rodauth-rails.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "railties", ">= 4.2", "< 7"
-  spec.add_dependency "rodauth", "~> 2.6"
+  spec.add_dependency "rodauth", "~> 2.7"
   spec.add_dependency "sequel-activerecord_connection", "~> 1.1"
   spec.add_dependency "tilt"
   spec.add_dependency "bcrypt"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rodauth-rails
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Janko Marohnić
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-11-27 00:00:00.000000000 Z
+date: 2021-01-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -36,14 +36,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.6'
+        version: '2.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.6'
+        version: '2.7'
 - !ruby/object:Gem::Dependency
   name: sequel-activerecord_connection
   requirement: !ruby/object:Gem::Requirement
@@ -187,7 +187,6 @@ files:
 - lib/generators/rodauth/templates/db/migrate/create_rodauth.rb
 - lib/generators/rodauth/views_generator.rb
 - lib/rodauth-rails.rb
-- lib/rodauth/features/rails.rb
 - lib/rodauth/rails.rb
 - lib/rodauth/rails/app.rb
 - lib/rodauth/rails/app/flash.rb

data/lib/rodauth/features/rails.rb

@@ -1 +0,0 @@
-require "rodauth/rails/feature"