# Overview
[](http://badge.fury.io/rb/auther)
[](https://codeclimate.com/github/bkuhlmann/auther)
[](https://gemnasium.com/bkuhlmann/auther)
[](http://travis-ci.org/bkuhlmann/auther)
[](https://coveralls.io/r/bkuhlmann/auther)
Provides simple, form-based authentication for apps that need security but don't want to deal with the clunky UI
of HTTP Basic Authentication or something as heavyweight as [Devise](https://github.com/plataformatec/devise). It
doesn't require a database and is compatible with password managers like [1Password](https://agilebits.com/onepassword)
making for a pleasent user experience.
# Features
* Form-based authentication compatible with password managers like [1Password](https://agilebits.com/onepassword).
[](https://github.com/bkuhlmann/auther)
[](https://github.com/bkuhlmann/auther)
* Encrypted account credentials.
* Multiple account support with account specific blacklisted paths.
* Log filtering for account credentials (login and password).
* Auto-redirection to requested path (once credentials have been verified).
* Customizable view.
* Customizable controller.
# Requirements
0. Any of the following Ruby VMs:
* [MRI 2.x.x](http://www.ruby-lang.org)
* [JRuby 1.x.x](http://jruby.org)
* [Rubinius 2.x.x](http://rubini.us)
0. [Ruby on Rails 4.x.x](http://rubyonrails.org).
# Setup
For a secure install, type the following from the command line (recommended):
gem cert --add <(curl -Ls http://www.redalchemist.com/gem-public.pem)
gem install auther --trust-policy HighSecurity
...or, for an insecure install, type the following (not recommended):
gem install auther
Add the following to your Gemfile:
gem "auther"
Edit your routes.rb as follows:
Rails.application.routes.draw do
mount Auther::Engine => "/auther"
get "/login", to: "auther/session#new"
end
Edit your application.rb as follows:
module Example
class Application < Rails::Application
config.auther_settings = {
title: "Authorization",
label: "Authorization",
accounts: [
name: "admin",
login: "N3JzR213WlBISDZsMjJQNkRXbEVmYVczbVdnMHRYVHRud29lOWRCekp6ST0tLWpFMkROekUvWDBkOHZ4ZngxZHV6clE9PQ==--cd863c39991fa4bb9a35de918aa16da54514e331",
password: "cHhFSStjRm9KbEYwK3ZJVlF2MmpTTWVVZU5acEdlejZsZEhjWFJoQWxKND0tLTE3cmpXZVBQdW5VUW1jK0ZSSDdLUnc9PQ==--f51171174fa77055540420f205e0dd9d499cfeb6",
paths: ["/admin"]
],
secret: "vuKrwD9XWoYuv@s99?tR(9VqryiL,KV{W7wFnejUa4QcVBP+D{2rD4JfuD(mXgA=$tNK4Pfn#NeGs3o3TZ3CqNc^Qb",
auth_url: "/login"
}
end
end
The purpose of each setting is as follows:
* *title* - The HTML page title (as rendered within a browser tab).
* *label* - The page label (what would appear above the form).
* *accounts* - The array of accounts with different or similar access to the application.
* *login* - The encrypted account login. For example, the above decrypts to: *test@test.com*.
* *password* - The encrypted account password. For example, the above decrypts to: *password*.
* *paths* - The array of blacklisted paths for which only this account has access to.
* *secret* - The secret passphrase used to encrypt/decrypt account credentials.
* *auth_url* - The URL to redirect to when enforcing authentication to a blacklisted path.
# Usage
Using the setup examples, from above, launch your Rails application and visit either of the following routes:
http://localhost:3000/login
http://localhost:3000/admin # Will redirect to /login if not authorized.
To encrypt/decrypt account credentials, launch a rails console and type the following:
# Best if more than 150 characters and gibberish to read. Must be the same as defined in auther settings.
cipher = Auther::Cipher.new "vuKrwD9XWoYuv@s99?tR(9VqryiL,KV{W7wFnejUa4QcVBP+D{2rD4JfuD(mXgA=$tNK4Pfn#NeGs3o3TZ3CqNc^Qb"
# Do this to encrypt an unecrypted value.
cipher.encrypt "test@test.com"
# Do this to decrypt an encrypted value.
cipher.decrypt "N3JzR213WlBISDZsMjJQNkRXbEVmYVczbVdnMHRYVHRud29lOWRCekp6ST0tLWpFMkROekUvWDBkOHZ4ZngxZHV6clE9PQ==--cd863c39991fa4bb9a35de918aa16da54514e331"
# Customization
## Model
The [Auther::Account](app/models/auther/account.rb) is a plain old Ruby object that uses ActiveRecord validations
to aid in form/credential validation. This model could potentially be replaced with a database-backed object
(would require controller customization)...but you might want to question if you have outgrown the use of this
gem and need a different solution altogether if it comes to that.
## Views
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 can be stylized by attaching new styles to the .authorization class (see
[auther.scss](app/assets/stylesheets/auther/auther.scss) for details).
## Controller
The [Auther::SessionController](app/controllers/auther/session_controller.rb) inherits from the
[Auther::BaseController](app/controllers/auther/base_controller.rb). To customize, it is recommended that
you add a controller to your app that inherits from the Auther::BaseController. Example:
# Example Path: app/controllers/session_controller.rb
class SessionController < Auther::BaseController
layout "example_site_layout"
end
This allows complete 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.
## Routes
As mentioned in the setup above, the routes can also be customized. Example:
Rails.application.routes.draw do
mount Auther::Engine => "/auther"
get "/login", to: "auther/session#new"
delete "/logout", to: "auther/session#destroy"
end
# Tests
To test, do the following:
0. cd to the gem root.
0. bundle install
0. bundle exec rspec spec
# Resources
* [Simplest Auth](https://github.com/vigetlabs/simplest_auth) - For situations where you need user and email reset
support beyond what this engine can provide.
# Contributions
Read CONTRIBUTING for details.
# Credits
Developed by [Brooke Kuhlmann](http://www.redalchemist.com) at [Red Alchemist](http://www.redalchemist.com).
# License
Copyright (c) 2014 [Red Alchemist](http://www.redalchemist.com).
Read the LICENSE for details.
# History
Read the CHANGELOG for details.
Built with [Gemsmith](https://github.com/bkuhlmann/gemsmith).