Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bkuhlmann/auther

A multi-account, form-based, database-less, application-wide, Rails authenticator.
https://github.com/bkuhlmann/auther

authentication authorization engine rails ruby

Last synced: about 2 months ago
JSON representation

A multi-account, form-based, database-less, application-wide, Rails authenticator.

Awesome Lists containing this project

README 

        
: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



* Supports form-based authentication compatible with password managers like link:https://bitwarden.com[Bitwarden].

* Uses pure CSS for styling.

* Uses encrypted account credentials to keep sensitive information secure.

* Supports multiple accounts with optional path exclude lists.

* Supports customizable routes, models, presenters, views, controllers, and loggers.

* Provides a generator for easy install and setup within an existing project.

* Provides auto-redirection to requested path for verified credentials.



== 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:



[source,bash]

----

# 💡 Skip this line if you already have the public certificate installed.

gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)

gem install auther --trust-policy HighSecurity

----



To install _without_ security, run:



[source,bash]

----

gem install auther

----



You can also add the gem directly to your project:



[source,bash]

----

bundle add auther

----



Once the gem is installed, you only need to require it:



[source,ruby]

----

require "auther"

----



Run the credentials generator to generate credentials for your application:



[source,bash]

----

rails generate auther:credentials

----



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:



[source,bash]

----

rails generate auther:install

----



💡 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:



[source,ruby]

----

Rails.application.config.auther = {

  accounts: [

    {

      name: "admin",

      encrypted_login: ENV["AUTHER_ADMIN_LOGIN"],

      encrypted_password: ENV["AUTHER_ADMIN_PASSWORD"],

      paths: ["/admin"]

    }

  ],

  secret: ENV["AUTHER_SECRET"]

}

----



To encrypt/decrypt account credentials, launch a rails console and run the following:



[source,ruby]

----

# The secret as defined in `Rails.application.config.auther` and/or produced by the credentials generator.

secret = SecureRandom.hex 16 # "426a7f46548a1a4518676a8e246517d8"



# The cipher for encrypting/decrypting values.

cipher = Auther::Cipher.new secret



# Use the following to encrypt an unencrypted value.

cipher.encrypt "[email protected]"



# Use the following to decrypt an encrypted value.

cipher.decrypt "hWToltdpl+uZJBPELKNC7Ij++jPkTuo=--nEdbOYL9fIRh14hY--fU+VSCd4+DDOhOmG1gzRfQ=="

----



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. Authorized

    redirection works in the order defined:

*** The excluded path (if requested prior to authorization but now authorized).

*** The authorized URL (if defined and the excluded path wasn't requested).

*** The root path (if none of the above).

** `deauthorized_url` - Optional. The URL to redirect to upon successful deauthorization (i.e.

    logout). Deauthorized redirections works as follows (in the order defined):

*** The deauthorized URL (if defined).

*** The auth URL.

* `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):



[source,ruby]

----

Rails.application.routes.draw do

  mount Auther::Engine => "/auther"

  get "/login", to: "auther/session#new", as: "login"

  delete "/logout", to: "auther/session#destroy", as: "logout"

end

----



=== 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:



[source,ruby]

----

# Example Path:  app/controllers/session_controller.rb

class SessionController < Auther::BaseController

  layout "example"

end

----



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:



[source,ruby]

----

# This is the default logger silences all logging attempts.

Logger.new nil



# Can be used to log to the environment log.

ActiveSupport::Logger.new "log/#{Rails.env}.log"



# Can be used to log to standard output.

Logger.new STDOUT

----



When logging is enabled, you'll be able to see the following information in the server logs to help

debug custom Auther settings:



* Requested path and excluded path detection.

* Finding (or not finding) of account.

* Account authentication pass/fail.

* Account and path authorization pass/fail.



=== Troubleshooting



* If upgrading Rails, changing the cookie/session settings, generating a new secret base key, etc.

  this might cause Auther authentication to fail. Make sure to clear your browser cookies in this

  situation or use Google Chrome (incognito mode) to verify.

* If the authentication view/form looks broken (style wise) this could be due to custom

  `ActionView::Base.field_error_proc` settings defined by your app (usually via an initializer).

  Auther uses this configuration `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

  you have customized this to something else, you might want to read the usage documentation

  (mentioned above) to rebuild the authentication view/form for your specific business needs.



== Development



To contribute, run:



[source,bash]

----

git clone https://github.com/bkuhlmann/auther

cd auther

bin/setup

----



You can also use the IRB console for direct access to all objects:



[source,bash]

----

bin/console

----



== Tests



To test, run:



[source,bash]

----

bin/rake

----



== 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/projects/auther/versions[Versions]



== link:https://alchemists.io/community[Community]



== Credits



* Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].

* Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].