rodauth-rails 0.8.2 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40b75a97a14021dafe773b2585d66d6ceef7498dddcef146498721bf39e57426
-  data.tar.gz: 270bac846036bfd32945e71116e6816db4d51ec752ec6ff354be8f38dd206da9
+  metadata.gz: 60fda35b195285a7c9cc14e07153d80faa9e939cf2944fbb04e1360baf30e306
+  data.tar.gz: 1f89bcfff28e6d08287fa67a9fe9228a2d61f15a8a9cdecb9fcf138137d72c47
 SHA512:
-  metadata.gz: 46e413275b4aca41959f36fb21d5fa3fd55eb6c73f87c6eda42a6eb8e36c5886913ad01e6e80394923f38236810aad4d608064f1f51661367798e8da70a9fd11
-  data.tar.gz: 22779086e32ced89a113d33e6b123c64f7f6094e1e41d0b99a741d38c3bbfc3ed64a0894d5b656754717cd11b50c83cd541039c5a8d094ffa3e37e1ed7f592ff
+  metadata.gz: 8e4ed3afbe7a114ba36f19541d1c8c8ee62de07526400230b1386f027b05876cd78ad88bdb40cae9767e74f83d1532d4939d97d03657662933f81d7086df34d9
+  data.tar.gz: cae1fc15a86f1b2e2423a8e54f36b844f610ba23ff74fd9ced132200e9816260028682c0efea1dcf19cf8a722a7ae49882c8d31c670e268e229117b4f6fb84f2

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 0.9.0 (2021-02-07)
+
+* Load Roda's JSON support by default, so that enabling `json`/`jwt` feature is all that's needed (@janko)
+
+* Bump Rodauth dependency to 2.9+ (@janko)
+
+* Add `--json` option for `rodauth:install` generator for configuring `json` feature (@janko)
+
+* Add `--jwt` option for `rodauth:install` generator for configuring `jwt` feature (@janko)
+
+* Remove the `--api` option from `rodauth:install` generator (@janko)
+
 ## 0.8.2 (2021-01-10)
 
 * Reset Rails session on `#clear_session`, protecting from potential session fixation attacks (@janko)

data/README.md

@@ -2,6 +2,35 @@
 
 Provides Rails integration for the [Rodauth] authentication framework.
 
+## Table of contents
+
+* [Resources](#resources)
+* [Why Rodauth?](#why-rodauth)
+* [Upgrading](#upgrading)
+* [Installation](#installation)
+* [Usage](#usage)
+  - [Routes](#routes)
+  - [Current account](#current-account)
+  - [Requiring authentication](#requiring-authentication)
+  - [Views](#views)
+  - [Mailer](#mailer)
+  - [Migrations](#migrations)
+  - [Multiple configurations](#multiple-configurations)
+  - [Calling controller methods](#calling-controller-methods)
+  - [Rodauth instance](#rodauth-instance)
+* [How it works](#how-it-works)
+  - [Middleware](#middleware)
+  - [App](#app)
+  - [Sequel](#sequel)
+* [JSON API](#json-api)
+* [OmniAuth](#omniauth)
+* [Configuring](#configuring)
+* [Custom extensions](#custom-extensions)
+* [Testing](#testing)
+* [Rodauth defaults](#rodauth-defaults)
+  - [Database functions](#database-functions)
+  - [Account statuses](#account-statuses)
+
 ## Resources
 
 Useful links:
@@ -18,11 +47,11 @@ Articles:
 ## 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:
+Sorcery, Clearance, Authlogic), so why would you choose Rodauth? Here are some
+of the advantages that stand out for me:
 
 * multifactor authentication ([TOTP][otp], [SMS codes][sms_codes], [recovery codes][recovery_codes], [WebAuthn][webauthn])
-* standardized [JSON API support][jwt] (for every feature)
+* standardized [JSON API support][json] for every feature (including [JWT][jwt])
 * 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)
@@ -54,7 +83,7 @@ documentation][hmac] for instructions on how to safely transition, or just set
 Add the gem to your Gemfile:
 
 ```rb
-gem "rodauth-rails", "~> 0.6"
+gem "rodauth-rails", "~> 0.9"
 
 # gem "jwt",      require: false # for JWT feature
 # gem "rotp",     require: false # for OTP feature
@@ -73,7 +102,9 @@ $ rails generate rodauth:install
 Or if you want Rodauth endpoints to be exposed via JSON API:
 
 ```sh
-$ rails generate rodauth:install --api
+$ rails generate rodauth:install --json # regular authentication using the Rails session
+# or
+$ rails generate rodauth:install --jwt # token authentication via the "Authorization" header
 $ bundle add jwt
 ```
 
@@ -481,6 +512,42 @@ class CreateRodauthOtpSmsCodesRecoveryCodes < ActiveRecord::Migration
 end
 ```
 
+### Multiple configurations
+
+If you need to handle multiple types of accounts that require different
+authentication logic, you can create different configurations for them:
+
+```rb
+# app/lib/rodauth_app.rb
+class RodauthApp < Rodauth::Rails::App
+  # primary configuration
+  configure do
+    # ...
+  end
+
+  # alternative configuration
+  configure(:admin) do
+    # ... enable features ...
+    prefix "/admin"
+    session_key_prefix "admin_"
+    remember_cookie_key "_admin_remember" # if using remember feature
+    # ...
+  end
+
+  route do |r|
+    r.rodauth
+    r.on("admin") { r.rodauth(:admin) }
+    # ...
+  end
+end
+```
+
+Then in your application you can reference the secondary Rodauth instance:
+
+```rb
+rodauth(:admin).login_path #=> "/admin/login"
+```
+
 ### Calling controller methods
 
 When using Rodauth before/after hooks or generally overriding your Rodauth
@@ -514,7 +581,7 @@ Rodauth operations outside of the request context. rodauth-rails gives you the
 ability to retrieve the Rodauth instance:
 
 ```rb
-rodauth = Rodauth::Rails.rodauth # or Rodauth::Rails.rodauth(:secondary)
+rodauth = Rodauth::Rails.rodauth # or Rodauth::Rails.rodauth(:admin)
 
 rodauth.login_url #=> "https://example.com/login"
 rodauth.account_from_login("user@example.com") # loads user by email
@@ -545,8 +612,8 @@ The Rodauth app stores the `Rodauth::Auth` instance in the Rack env hash, which
 is then available in your Rails app:
 
 ```rb
-request.env["rodauth"]           #=> #<Rodauth::Auth>
-request.env["rodauth.secondary"] #=> #<Rodauth::Auth> (if using multiple configurations)
+request.env["rodauth"]       #=> #<Rodauth::Auth>
+request.env["rodauth.admin"] #=> #<Rodauth::Auth> (if using multiple configurations)
 ```
 
 For convenience, this object can be accessed via the `#rodauth` method in views
@@ -555,14 +622,14 @@ and controllers:
 ```rb
 class MyController < ApplicationController
   def my_action
-    rodauth             #=> #<Rodauth::Auth>
-    rodauth(:secondary) #=> #<Rodauth::Auth> (if using multiple configurations)
+    rodauth         #=> #<Rodauth::Auth>
+    rodauth(:admin) #=> #<Rodauth::Auth> (if using multiple configurations)
   end
 end
 ```
 ```erb
-<% rodauth             #=> #<Rodauth::Auth> %>
-<% rodauth(:secondary) #=> #<Rodauth::Auth> (if using multiple configurations) %>
+<% rodauth         #=> #<Rodauth::Auth> %>
+<% rodauth(:admin) #=> #<Rodauth::Auth> (if using multiple configurations) %>
 ```
 
 ### App
@@ -584,7 +651,7 @@ any additional [plugin options].
 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
+  configure(:admin) { ... }     # defining multiple Rodauth configurations
 end
 ```
 
@@ -619,15 +686,32 @@ function calls).
 
 If ActiveRecord is used in the application, the `rodauth:install` generator
 will have automatically configured Sequel to reuse ActiveRecord's database
-connection (using the [sequel-activerecord_connection] gem).
+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:
+To make Rodauth endpoints accessible via JSON API, enable the [`json`][json]
+feature:
+
+```rb
+# app/lib/rodauth_app.rb
+class RodauthApp < Rodauth::Rails::App
+  configure do
+    # ...
+    enable :json
+    only_json? true # accept only JSON requests
+    # ...
+  end
+end
+```
+
+This will store account session data into the Rails session. If you rather want
+stateless token-based authentication via the `Authorization` header, enable the
+[`jwt`][jwt] feature (which builds on top of the `json` feature) and add the
+[JWT gem] to the Gemfile:
 
 ```sh
 $ bundle add jwt
@@ -635,24 +719,16 @@ $ bundle add jwt
 ```rb
 # app/lib/rodauth_app.rb
 class RodauthApp < Rodauth::Rails::App
-  configure(json: :only) do
+  configure do
     # ...
     enable :jwt
-    # make sure to store the JWT secret below in a safe place
-    jwt_secret "...your secret key..."
+    jwt_secret "<YOUR_SECRET_KEY>" # store the JWT secret in a safe place
+    only_json? true # accept only JSON requests
     # ...
   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
@@ -976,6 +1052,7 @@ conduct](https://github.com/janko/rodauth-rails/blob/master/CODE_OF_CONDUCT.md).
 [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
+[json]: http://rodauth.jeremyevans.net/rdoc/files/doc/json_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

data/lib/generators/rodauth/install_generator.rb

@@ -13,14 +13,8 @@ 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"
+        class_option :json, type: :boolean, desc: "Configure JSON support"
+        class_option :jwt, type: :boolean, desc: "Configure JWT support"
 
         def create_rodauth_migration
           return unless defined?(ActiveRecord::Base)
@@ -83,17 +77,17 @@ module Rodauth
           end
         end
 
-        def api_only?
-          if options.key?(:api)
-            options[:api]
-          elsif ::Rails.gem_version >= Gem::Version.new("5.0")
-            ::Rails.application.config.api_only
-          end
+        def json?
+          options[:json]
+        end
+
+        def jwt?
+          options[:jwt] || Rodauth::Rails.api_only?
         end
 
         def migration_features
           features = [:base, :reset_password, :verify_account, :verify_login_change]
-          features << :remember unless api_only?
+          features << :remember unless jwt?
           features
         end
       end

data/lib/generators/rodauth/templates/app/lib/rodauth_app.rb

@@ -1,11 +1,11 @@
 class RodauthApp < Rodauth::Rails::App
-  configure<%= " json: :only" if api_only? %> do
+  configure do
     # List of authentication features that are loaded.
     enable :create_account, :verify_account, :verify_account_grace_period,
-      :login, :logout, <%= api_only? ? ":jwt" : ":remember" %>,
+      :login, :logout<%= ", :remember" unless jwt? %>,
       :reset_password, :change_password, :change_password_notify,
       :change_login, :verify_login_change,
-      :close_account
+      :close_account<%= ", :json" if json? %><%= ", :jwt" if jwt? %>
 
     # See the Rodauth documentation for the list of available config options:
     # http://rodauth.jeremyevans.net/documentation.html
@@ -14,6 +14,16 @@ class RodauthApp < Rodauth::Rails::App
     # The secret key used for hashing public-facing tokens for various features.
     # Defaults to Rails `secret_key_base`, but you can use your own secret key.
     # hmac_secret "<%= SecureRandom.hex(64) %>"
+<% if jwt? -%>
+
+    # Set JWT secret, which is used to cryptographically protect the token.
+    jwt_secret "<%= SecureRandom.hex(64) %>"
+<% end -%>
+<% if json? || jwt? -%>
+
+    # Accept only JSON requests.
+    only_json? true
+<% end -%>
 
     # Specify the controller used for view rendering and CSRF verification.
     rails_controller { RodauthController }
@@ -42,18 +52,6 @@ class RodauthApp < Rodauth::Rails::App
 
     # Redirect to the app from login and registration pages if already logged in.
     # already_logged_in { redirect login_redirect }
-<% if api_only? -%>
-
-    # ==> JWT
-    # Set JWT secret, which is used to cryptographically protect the token.
-    jwt_secret "<%= SecureRandom.hex(64) %>"
-
-    # Don't require login confirmation param.
-    require_login_confirmation? false
-
-    # Don't require password confirmation param.
-    require_password_confirmation? false
-<% end -%>
 
     # ==> Emails
     # Uncomment the lines below once you've imported mailer views.
@@ -80,14 +78,14 @@ class RodauthApp < Rodauth::Rails::App
     #   db.after_commit { email.deliver_later }
     # end
 
-    # In the meantime you can tweak settings for emails created by Rodauth
+    # In the meantime, you can tweak settings for emails created by Rodauth.
     # email_subject_prefix "[MyApp] "
     # email_from "noreply@myapp.com"
     # send_email(&:deliver_later)
     # reset_password_email_body { "Click here to reset your password: #{reset_password_email_link}" }
 
     # ==> Flash
-<% unless api_only? -%>
+<% unless json? || jwt? -%>
     # Match flash keys with ones already used in the Rails app.
     # flash_notice_key :success # default is :notice
     # flash_error_key :error # default is :alert
@@ -107,7 +105,7 @@ class RodauthApp < Rodauth::Rails::App
 
     # Change minimum number of password characters required when creating an account.
     # password_minimum_length 8
-<% unless api_only? -%>
+<% unless jwt? -%>
 
     # ==> Remember Feature
     # Remember all logged in users.
@@ -128,13 +126,14 @@ class RodauthApp < Rodauth::Rails::App
 
     # Perform additional actions after the account is created.
     # after_create_account do
-    #   Profile.create!(account_id: account[:id], name: param("name"))
+    #   Profile.create!(account_id: account_id, name: param("name"))
     # end
 
     # Do additional cleanup after the account is closed.
     # after_close_account do
-    #   Profile.find_by!(account_id: account[:id]).destroy
+    #   Profile.find_by!(account_id: account_id).destroy
     # end
+<% unless json? || jwt? -%>
 
     # ==> Redirects
     # Redirect to home page after logout.
@@ -145,6 +144,7 @@ class RodauthApp < Rodauth::Rails::App
 
     # Redirect to login page after password reset.
     reset_password_redirect { login_path }
+<% end -%>
 
     # ==> Deadlines
     # Change default deadlines for some actions.
@@ -156,14 +156,13 @@ class RodauthApp < Rodauth::Rails::App
 
   # ==> Multiple configurations
   # configure(:admin) do
-  #   enable :http_basic_auth
-  #
+  #   enable :http_basic_auth # enable different set of features
   #   prefix "/admin"
-  #   session_key :admin_id
+  #   session_key_prefix "admin_"
   # end
 
   route do |r|
-<% unless api_only? -%>
+<% unless jwt? -%>
     rodauth.load_memory # autologin remembered users
 
 <% end -%>

data/lib/rodauth/rails.rb

@@ -42,6 +42,16 @@ module Rodauth
         end
       end
 
+      if ::Rails.gem_version >= Gem::Version.new("5.0")
+        def api_only?
+          ::Rails.application.config.api_only
+        end
+      else
+        def api_only?
+          false
+        end
+      end
+
       def configure
         yield self
       end

data/lib/rodauth/rails/app.rb

@@ -12,22 +12,16 @@ module Rodauth
       plugin :hooks
       plugin :render, layout: false
 
-      def self.configure(name = nil, **options, &block)
-        unless options[:json] == :only
-          require "rodauth/rails/app/flash"
-          plugin Flash
-        end
+      if defined?(ActionDispatch::Flash) # not in API-only mode
+        require "rodauth/rails/app/flash"
+        plugin Flash
+      end
 
-        plugin :rodauth, name: name, csrf: false, flash: false, **options do
+      def self.configure(name = nil, **options, &block)
+        plugin :rodauth, name: name, csrf: false, flash: false, json: true, **options do
           # load the Rails integration
           enable :rails
 
-          if options[:json] == :only && ActionPack.version >= Gem::Version.new("5.0")
-            rails_controller { ActionController::API }
-          else
-            rails_controller { ActionController::Base }
-          end
-
           # database functions are more complex to set up, so disable them by default
           use_database_authentication_functions? false
 

data/lib/rodauth/rails/app/flash.rb

@@ -30,10 +30,12 @@ module Rodauth
             rails_request.flash
           end
 
-          def commit_flash
-            if ActionPack.version >= Gem::Version.new("5.0")
+          if ActionPack.version >= Gem::Version.new("5.0")
+            def commit_flash
               rails_request.commit_flash
-            else
+            end
+          else
+            def commit_flash
               # ActionPack 4.2 automatically commits flash
             end
           end

data/lib/rodauth/rails/feature.rb

@@ -192,6 +192,14 @@ module Rodauth
       defined?(ActionController::API) && rails_controller <= ActionController::API
     end
 
+    def rails_controller
+      if only_json? && Rodauth::Rails.api_only?
+        ActionController::API
+      else
+        ActionController::Base
+      end
+    end
+
     # ActionMailer subclass for correct email delivering.
     class Mailer < ActionMailer::Base
       def create_email(**options)

data/lib/rodauth/rails/version.rb

@@ -1,5 +1,5 @@
 module Rodauth
   module Rails
-    VERSION = "0.8.2"
+    VERSION = "0.9.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.8"
+  spec.add_dependency "rodauth", "~> 2.9"
   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.8.2
+  version: 0.9.0
 platform: ruby
 authors:
 - Janko Marohnić
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-01-10 00:00:00.000000000 Z
+date: 2021-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -36,14 +36,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.8'
+        version: '2.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.8'
+        version: '2.9'
 - !ruby/object:Gem::Dependency
   name: sequel-activerecord_connection
   requirement: !ruby/object:Gem::Requirement
@@ -216,7 +216,7 @@ homepage: https://github.com/janko/rodauth-rails
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -231,8 +231,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
-signing_key: 
+rubygems_version: 3.2.3
+signing_key:
 specification_version: 4
 summary: Provides Rails integration for Rodauth.
 test_files: []