A multi-account, form-based, database-less, application-wide, Rails authenticator.
OTHER License
:toc: macro :toclevels: 5 :figure-caption!:
= Auther
Auther provides simple, form-based authentication for apps that need security but don't want to deal with the clunky HTTP Basic Authentication user interface or as heavyweight as link:https://github.com/plataformatec/devise[Devise]. Auther doesn't require a database and is compatible with password managers which makes for a pleasant user experience.
Auther is useful in situations -- like minimal viable products or applications with a small user base -- where you need to a security layer up and running quickly before adding more robust user management.
toc::[]
== Features
== Screenshots
image::https://alchemists.io/images/projects/auther/screenshots/form-without_errors.png[Form Without Errors Screenshot,width=347,height=394,role=focal_point] image::https://alchemists.io/images/projects/auther/screenshots/form-with_errors.png[Form With Errors Screenshot,width=386,height=456,role=focal_point]
== Requirements
. link:https://www.ruby-lang.org[Ruby] . link:https://rubyonrails.org[Ruby on Rails]
== Setup
To install with security, run:
To install without security, run:
You can also add the gem directly to your project:
Once the gem is installed, you only need to require it:
Run the credentials generator to generate credentials for your application:
Example:
image::https://alchemists.io/images/projects/auther/screenshots/credentials_generator.png[Credentials Generator Screenshot,width=768,height=288,role=focal_point]
If using link:https://direnv.net[direnv], copy and paste the generated credentials -- as shown above -- into your .envrc
file (💡 don't forget to add export
before each key). Ensure you've applied these credentials to your environment and then run the install generator to configure and initialize your application:
💡 If you ran the generator before applying your credentials to the environment, you can re-run the generator to fix.
== Usage
Launch your Rails application and visit the following: http://localhost:3000/login
. Enter your
login and password as used for the rails generate auther:credentials
generator and you'll be
logged in.
=== Initializer
The initializer (installed during setup) can be found here: config/initializers/auther.rb
. The
initializer comes installed with the following settings:
To encrypt/decrypt account credentials, launch a rails console and run the following:
Rails.application.config.auther
and/or produced by the credentials generator.secret = SecureRandom.hex 16 # "426a7f46548a1a4518676a8e246517d8"
cipher = Auther::Cipher.new secret
cipher.encrypt "[email protected]"
The initializer can be customized as follows:
title
- Optional. The HTML page title (as rendered within a browser tab). Default:"Authorization"
.label
- Optional. The page label (what would appear above the form). Default: "Authorization"
.secret
- Required. The secret passphrase used to encrypt/decrypt account credentials.accounts
- Required. The array of accounts with different or similar access to the application.name
- Required. The account name that uniquely identifies the account.encrypted_login
- Required. The encrypted account login.encrypted_password
- Required. The encrypted account password.paths
- Required. The array of excluded paths for which only this account has access to.authorized_url
- Optional. The URL to redirect to upon successful authorization. Authorizeddeauthorized_url
- Optional. The URL to redirect to upon successful deauthorization (i.e.url
- Optional. The URL to redirect to when enforcing authentication. Default: "/login"
.logger
- Optional. The logger used to log path/account authorization messages. Default:Logger.new nil
.=== Routes
The routes can be customized as follows (installed, by default, via the install generator):
=== Model
The Auther::Account
is a struct that uses ActiveModel validations to aid in attribute validation.
This model could potentially be replaced with a database-backed object (would require controller
customization)...but you should question if you have outgrown the use of this gem and need a
different solution altogether if it comes to that.
=== Presenter
The Auther::Presenter::Account
is a plain old Ruby object that uses ActiveModel validations to aid
in form validation. This presenter makes it easy to construct form data for input and validation.
=== View
The view can be customized by creating the following file within your Rails application (assumes
that the default Auther::SessionController
implementation is sufficient):
app/views/auther/session/new.html
.
The form uses the @account
instance variable which is an instance of the
Auther::Presenter::Account
presenter (as mentioned above). The form can be stylized by modifying
the styles found in the auther.scss
stylesheet.
=== Controller
The Auther::SessionController
inherits from the Auther::BaseController
. To customize, it is
recommended that you add a controller to your app that inherits from the Auther::BaseController
.
Example:
This allows customization of session controller behavior to serve any special business needs. See
the Auther::BaseController
for additional details or the Auther::SessionController
for default
implementation.
=== Logging
As mentioned in the setup above, the logger can be customized as follows:
Logger.new nil
ActiveSupport::Logger.new "log/#{Rails.env}.log"
When logging is enabled, you'll be able to see the following information in the server logs to help debug custom Auther settings:
=== Troubleshooting
ActionView::Base.field_error_proc
settings defined by your app (usually via an initializer).ActionView::Base.field_error_proc = proc { |html_tag, _| html_tag.html_safe }
so that no additional markup is added to the DOM when errors are raised. If== Development
To contribute, run:
You can also use the IRB console for direct access to all objects:
== Tests
To test, run:
== link:https://alchemists.io/policies/license[License]
== link:https://alchemists.io/policies/security[Security]
== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]
== link:https://alchemists.io/policies/contributions[Contributions]
== link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin]
== link:https://alchemists.io/projects/auther/versions[Versions]
== link:https://alchemists.io/community[Community]
== Credits