Credible

Credible | Demo Repo | Helvellyn

Credible was extracted from thombruce/helvellyn and is still a work in progress. The goal is to provide JWT and API token based authentication using Warden for Rails API applications.

Installation

Add this line to your application's Gemfile:

gem 'credible'

And then execute:

$ bundle

Mount Credible's authentication routes in your config/routes.rb file:

Rails.application.routes.draw do
  mount Credible::Engine => "/auth"
end

And in your Application Controller, inherit from Credible::ControllerConcern:

class ApplicationController < ActionController::Base
  include Credible::ControllerConcern
end

Credible is a work in progress and requires a complicated setup for now. It was extracted from thombruce/helvellyn. You'll need to add models and configure them manually. In future, I'll had helpers to handle this for you.

Add Models

To get Credible working, your app will need at least a User model and a Session model.

User model

rails g model User email:string:uniq password_digest:string confirmation_token:token confirmed_at:datetime

class User < ApplicationRecord
  include Credible::User
end

Session model

rails g model Session user:references token:token

class Session < ApplicationRecord
  include Credible::Session
end

 Calling the API

To sign up and create a new user, send params in the form { user: { email: 'email@example.com', password: 'Pa$$word123!' } } to auth/signup as a POST request. On success, this will return { access_token: '...', refresh_token: '...' } that can be used to persist the user's session.

To sign in a user, send params in the form { session: { login: 'email@example.com', password: 'Pa$$word123!' } } to auth/login as a POST request. On success, this will return { access_token: '...', refresh_token: '...' } that can be used to persist the user's session.

To sign out a user, send an empty request to auth/signout as a DELETE request. On success, this will return no content. It will destroy the session in the database and invalidate any existing tokens. Note: If you are using the access token to authenticate the user on a separate server, it will still remain valid until its expiry.

To refresh an access token, send params in the form { refresh_token: '...' } to auth/refresh as a POST request. On success, this will return { access_token: '...', refresh_token: '...' } that can be used to continue the user's session. Note: This will also invalidate the refresh token used to renew the tokens, and provide a new refresh token for next use.

Be careful

Credible is still a work in progress and these routes will be subject to change. I'm thinking about keeping them around as sort of a "classic" mode, but I feel like more resource-oriented routes are also desirable. For example, I want to add a /tokens endpoint in place of the existing /refresh enpoint, because refresh what? It's just more semantically correct.

Mailers

To user Credible's in-built mailers, you must set a hostname for your application. A suitable setting for this in config/environments/development.rb might be:

config.action_mailer.default_url_options = { host: 'localhost', port: 3000 }

Your app will also be expected to accept and properly route requests for [root URL]/confirm/[confirmation token]?email=[email]. The confirmation_token and email params should be sent with an AJAX request to the Credible auth route.

For example, if you have Credible mounted as mount Credible::Engine => "/auth", you would make a get request to /auth/confirm/[confirmation token]?email=[email].

This is a little complicated and not very user friendly. A future version will provide an engine_name to assist with Rails' URL helpers, as well as an in-built UI for handling these requests on your behalf.

Contributing

Credible is not yet accepting contributions. Watch this space.

License

The gem is available as open source under the terms of the MIT License.