rodauth-rails 0.3.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b60f1b274889c1809196e62e8f3ba3516bf631593e6263162b3f4af11521d3a3
-  data.tar.gz: e55af46d9f5886dfc70d1f3112597bf508ba9536e8d0fc9cec141f33d045c94b
+  metadata.gz: 00d7ab9dd749cbae17cddc2788005d8570d8d46f89f427ad624c7e61fe177665
+  data.tar.gz: d62aed32823b0be9c74d7281de80650b8faf600c01db22ad941a35f30bfeb002
 SHA512:
-  metadata.gz: 26c72c879909f9497a9d05802776ef8aa42d73dd8a4ba72695ea88289aebf29b2224bbf9011ab7929b394e708c25379410cb9d62f4d54c9c300002e3405cdc5a
-  data.tar.gz: 8370be5f4885300ded77d1e0bfea95ab99c0b0889fe464fbea062da7d71dd1a66deb4777a08dc235f841eb241170b1a08eb9badce756325e2291b5e87883068a
+  metadata.gz: 7ab0afe5e95fab1af706b64ef5c494252fac49481d49dad1c2ef3510c17ca96050c58bf0832a36af761673137f2fd63d7d49a692656bcf06748840de96f60875
+  data.tar.gz: 729bf3b5887647c23f4b11d821d3829c4b4d290c546d2f19ba6b393dd47bf0b357d128577e877ac3e0a4352972b79325d4217d62935d4a683e78ff8e910d13a2

data/CHANGELOG.md

@@ -1,3 +1,45 @@
+## 0.6.0 (2020-11-22)
+
+* Add `Rodauth::Rails.rodauth` method for retrieving Rodauth instance outside of request context (@janko)
+
+* Add default Action Dispatch response headers in Rodauth responses (@janko)
+
+* Run controller rescue handlers around Rodauth actions (@janko)
+
+* Run controller action callbacks around Rodauth actions (@janko)
+
+## 0.5.0 (2020-11-16)
+
+* Support more Active Record adapters in `rodauth:install` generator (@janko)
+
+* Add `rodauth:migration` generator for creating tables of specified features (@janko)
+
+* Use UUIDs for primary keys if so configured in Rails generators (@janko)
+
+* Add `rodauth:routes` rake task for printing routes handled by Rodauth middleware (@janko)
+
+## 0.4.2 (2020-11-08)
+
+* Drop support for Ruby 2.2 (@janko)
+
+* Bump `sequel-activerecord_connection` dependency to 1.1+ (@janko)
+
+* Set default bcrypt hash cost to `1` in tests (@janko)
+
+* Call `AR::Base.connection_db_config` on Rails 6.1+ in `rodauth:install` generator (@janko)
+
+## 0.4.1 (2020-11-02)
+
+* Don't generate `RodauthController` in API-only mode (@janko)
+
+* Pass `test: false` to Sequel in the `sequel.rb` initializer (@janko)
+
+## 0.4.0 (2020-11-02)
+
+* Support Rails API-only mode (@janko)
+
+* Make `rodauth:install` create `rodauth_app.rb` in `app/lib/` directory (@janko)
+
 ## 0.3.1 (2020-10-25)
 
 * Depend on sequel-activerecord_connection 1.0+ (@janko)

data/README.md

@@ -4,16 +4,27 @@ Provides Rails integration for the [Rodauth] authentication framework.
 
 ## Resources
 
+Useful links:
+
 * [Rodauth documentation](http://rodauth.jeremyevans.net/documentation.html)
-* [rodauth-rails wiki](https://github.com/janko/rodauth-rails/wiki)
 * [Rails demo](https://github.com/janko/rodauth-demo-rails)
 
+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/)
+
 ## Installation
 
 Add the gem to your Gemfile:
 
 ```rb
-gem "rodauth-rails", "~> 0.3"
+gem "rodauth-rails", "~> 0.6"
+
+# gem "jwt",      require: false # for JWT feature
+# gem "rotp",     require: false # for OTP feature
+# gem "rqrcode",  require: false # for OTP feature
+# gem "webauthn", require: false # for WebAuthn feature
 ```
 
 Then run `bundle install`.
@@ -29,7 +40,7 @@ The generator will create the following files:
 * Rodauth migration at `db/migrate/*_create_rodauth.rb`
 * Rodauth initializer at `config/initializers/rodauth.rb`
 * Sequel initializer at `config/initializers/sequel.rb` for ActiveRecord integration
-* Rodauth app at `lib/rodauth_app.rb`
+* Rodauth app at `app/lib/rodauth_app.rb`
 * Rodauth controller at `app/controllers/rodauth_controller.rb`
 * Account model at `app/models/account.rb`
 
@@ -49,7 +60,6 @@ class CreateRodauth < ActiveRecord::Migration
     create_table :account_verification_keys do |t| ... end
     create_table :account_login_change_keys do |t| ... end
     create_table :account_remember_keys do |t| ... end
-    # ...
   end
 end
 ```
@@ -83,17 +93,17 @@ ActiveRecord connection.
 require "sequel/core"
 
 # initialize Sequel and have it reuse Active Record's database connection
-DB = Sequel.postgres(extensions: :activerecord_connection)
+DB = Sequel.connect("postgresql://", extensions: :activerecord_connection)
 ```
 
 ### Rodauth app
 
-Your Rodauth app is created in the `lib/` directory, which comes with a default
-set of authentication features enabled, as well as extensive examples on ways
-you can configure authentication behaviour.
+Your Rodauth app is created in the `app/lib/` directory, and comes with a
+default set of authentication features enabled, as well as extensive examples
+on ways you can configure authentication behaviour.
 
 ```rb
-# lib/rodauth_app.rb
+# app/lib/rodauth_app.rb
 class RodauthApp < Rodauth::Rails::App
   configure do
     # authentication configuration
@@ -105,23 +115,11 @@ class RodauthApp < Rodauth::Rails::App
 end
 ```
 
-Note that Rails doesn't autoload files in the `lib/` directory by default, so
-make sure to add `lib/` to your `config.autoload_paths`:
-
-```rb
-# config/application.rb
-module YourApp
-  class Application < Rails::Application
-    # ...
-    config.autoload_paths += %W[#{config.root}/lib]
-  end
-end
-```
-
 ### Controller
 
-Your Rodauth app will by default use `RodauthController` for view rendering
-and CSRF protection.
+Your Rodauth app will by default use `RodauthController` for view rendering,
+CSRF protection, and running controller callbacks and rescue handlers around
+Rodauth actions.
 
 ```rb
 # app/controllers/rodauth_controller.rb
@@ -129,7 +127,7 @@ class RodauthController < ApplicationController
 end
 ```
 
-### Account Model
+### Account model
 
 Rodauth stores user accounts in the `accounts` table, so the generator will
 also create an `Account` model for custom use.
@@ -140,10 +138,34 @@ class Account < ApplicationRecord
 end
 ```
 
-## Getting started
+## Usage
+
+### Routes
+
+We can see the list of routes our Rodauth middleware handles:
+
+```sh
+$ rails rodauth:routes
+```
+```
+Routes handled by RodauthApp:
+
+  /login                   rodauth.login_path
+  /create-account          rodauth.create_account_path
+  /verify-account-resend   rodauth.verify_account_resend_path
+  /verify-account          rodauth.verify_account_path
+  /change-password         rodauth.change_password_path
+  /change-login            rodauth.change_login_path
+  /logout                  rodauth.logout_path
+  /remember                rodauth.remember_path
+  /reset-password-request  rodauth.reset_password_request_path
+  /reset-password          rodauth.reset_password_path
+  /verify-login-change     rodauth.verify_login_change_path
+  /close-account           rodauth.close_account_path
+```
 
-Let's start by adding some basic authentication navigation links to our home
-page:
+Using this information, we could add some basic authentication links to our
+navigation header:
 
 ```erb
 <ul>
@@ -156,43 +178,48 @@ page:
 </ul>
 ```
 
-These links are fully functional, feel free to visit them and interact with the
+These routes are fully functional, feel free to visit them and interact with the
 pages. The templates that ship with Rodauth aim to provide a complete
 authentication experience, and the forms use [Bootstrap] markup.
 
-Let's also load the account record for authenticated requests and expose it via
-`#current_account`:
+### Current account
+
+To be able to fetch currently authenticated account, let's define a
+`#current_account` method that fetches the account id from session and
+retrieves the corresponding account record:
 
 ```rb
 # app/controllers/application_controller.rb
 class ApplicationController < ActionController::Base
-  before_action :load_account, if: -> { rodauth.authenticated? }
+  before_action :current_account, if: -> { rodauth.authenticated? }
 
   private
 
-  def load_account
-    @current_account = Account.find(rodauth.session_value)
+  def current_account
+    @current_account ||= Account.find(rodauth.session_value)
   rescue ActiveRecord::RecordNotFound
     rodauth.logout
     rodauth.login_required
   end
-
-  attr_reader   :current_account
   helper_method :current_account
 end
 ```
+
+This allows us to access the current account in controllers and views:
+
 ```erb
 <p>Authenticated as: <%= current_account.email %></p>
 ```
 
 ### Requiring authentication
 
-Next, we'll likely want to require authentication for certain sections/pages of
-our app. We can do this in our Rodauth app's routing block, which helps keep
-the authentication logic encapsulated:
+We'll likely want to require authentication for certain parts of our app,
+redirecting the user to the login page if they're not logged in. We can do this
+in our Rodauth app's routing block, which helps keep the authentication logic
+encapsulated:
 
 ```rb
-# lib/rodauth_app.rb
+# app/lib/rodauth_app.rb
 class RodauthApp < Rodauth::Rails::App
   # ...
   route do |r|
@@ -247,9 +274,9 @@ end
 
 ### Views
 
-The templates built into Rodauth are useful when getting started, but at some
-point we'll probably want more control over the markup. For that we can run the
-following command:
+The templates built into Rodauth are useful when getting started, but soon
+you'll want to start editing the markup. You can run the following command to
+copy Rodauth templates into your Rails app:
 
 ```sh
 $ rails generate rodauth:views
@@ -273,7 +300,7 @@ $ rails generate rodauth:views --all
 ```
 
 You can also tell the generator to create views into another directory (in this
-case don't forget to rename the Rodauth controller accordingly).
+case make sure to rename the Rodauth controller accordingly):
 
 ```sh
 # generates views into app/views/authentication
@@ -308,11 +335,11 @@ end
 
 ### Mailer
 
-Rodauth may send emails as part of the authentication flow. Most email settings
-can be customized:
+Depending on the features you've enabled, Rodauth may send emails as part of
+the authentication flow. Most email settings can be customized:
 
 ```rb
-# lib/rodauth_app.rb
+# app/lib/rodauth_app.rb
 class RodauthApp < Rodauth::Rails::App
   # ...
   configure do
@@ -353,11 +380,11 @@ end
 ```
 
 You can then uncomment the lines in your Rodauth configuration to have it call
-your mailer. If you've enabled additional authentication features, make sure to
-override their `send_*_email` methods as well.
+your mailer. If you've enabled additional authentication features that send
+emails, make sure to override their `send_*_email` methods as well.
 
 ```rb
-# lib/rodauth_app.rb
+# app/lib/rodauth_app.rb
 class RodauthApp < Rodauth::Rails::App
   # ...
   configure do
@@ -393,6 +420,76 @@ class RodauthApp < Rodauth::Rails::App
 end
 ```
 
+### Migrations
+
+The install generator will create a migration for tables used by the Rodauth
+features enabled by default. For any additional features, you can use the
+migration generator to create the corresponding tables:
+
+```sh
+$ rails generate rodauth:migration otp sms_codes recovery_codes
+```
+```rb
+# db/migration/*_create_rodauth_otp_sms_codes_recovery_codes.rb
+class CreateRodauthOtpSmsCodesRecoveryCodes < ActiveRecord::Migration
+  def change
+    create_table :account_otp_keys do |t| ... end
+    create_table :account_sms_codes do |t| ... end
+    create_table :account_recovery_codes do |t| ... end
+  end
+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.
+
+### Rodauth instance
+
+In some cases you might need to use Rodauth more programmatically, and perform
+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.login_url #=> "https://example.com/login"
+rodauth.account_from_login("user@example.com") # loads user by email
+rodauth.password_match?("secret") #=> true
+rodauth.setup_account_verification
+rodauth.close_account
+```
+
+This Rodauth instance will be initialized with basic Rack env that allows is it
+to generate URLs, using `config.action_mailer.default_url_options` options.
+
 ## How it works
 
 ### Middleware
@@ -437,11 +534,12 @@ end
 The `Rodauth::Rails::App` class is a [Roda] subclass that provides Rails
 integration for Rodauth:
 
-* uses Rails' flash instead of Roda's
-* uses Rails' CSRF protection instead of Roda's
+* uses Action Dispatch flash instead of Roda's
+* uses Action Dispatch CSRF protection instead of Roda's
 * sets [HMAC] secret to Rails' secret key base
-* uses ActionController for rendering templates
-* uses ActionMailer for sending emails
+* uses Action Controller for rendering templates
+* runs Action Controller callbacks & rescue handlers around Rodauth actions
+* uses Action Mailer for sending emails
 
 The `configure { ... }` method wraps configuring the Rodauth plugin, forwarding
 any additional [plugin options].
@@ -498,20 +596,6 @@ Rodauth::Rails.configure do |config|
 end
 ```
 
-## Working with JWT
-
-To use Rodauth's [JWT feature], you'll need to load Roda's JSON support:
-
-```rb
-# lib/rodauth_app.rb
-class RodauthApp < Rodauth::Rails::App
-  configure(json: true) do
-    enable :jwt
-    # your configuration
-  end
-end
-```
-
 ## Testing
 
 If you're writing system tests, it's generally better to go through the actual
@@ -579,6 +663,22 @@ disables the use of database functions, though you can always turn it back on.
 use_database_authentication_functions? true
 ```
 
+To create the database functions, pass the Sequel database object into the
+Rodauth method for creating database functions:
+
+```rb
+# db/migrate/*_create_rodauth_database_functions.rb
+class CreateRodauthDatabaseFunctions < ActiveRecord::Migration
+  def up
+    Rodauth.create_database_authentication_functions(DB)
+  end
+
+  def down
+    Rodauth.drop_database_authentication_functions(DB)
+  end
+end
+```
+
 ### Account statuses
 
 The recommended [Rodauth migration] stores possible account status values in a
@@ -631,9 +731,9 @@ 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
-[rendering views outside of controllers]: https://blog.bigbinary.com/2016/01/08/rendering-views-outside-of-controllers-in-rails-5.html
 [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/
 [HMAC]: http://rodauth.jeremyevans.net/rdoc/files/README_rdoc.html#label-HMAC