KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

proof

★ 221 Open GitHub ↗

Secure Authentication for Single Page Applications

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# proof [![build status](https://travis-ci.org/undercase/proof.svg?branch=master)](https://travis-ci.org/undercase/proof) [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/undercase/proof?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
Authentication for Modern Web Apps

Proof is JWT Authentication with Rails Made Easy. It is designed for web applications which must authenticate users with Rails APIs. It is:

* Based on [JWT](http://jwt.io/), a secure, open authentication standard.
* Easy to Use and Modular. It works out of the box with Devise, and can easily be customized to work with any database setup.
* Designed for Single-Page Applications and API-Driven experiences.

## How it Works
When your web application send a POST request to the `login` action with an identifier (email, username, etc.) and password, proof authenticates the user and creates a JWT token. This token is encrypted and signed using a secret key generated by your rails application, so a hacker who gets a hold of it can't modify it. The token identifies the user it will authenticate for and an expiration time. Your web application stores the token and sends it as an HTTP header with every request. Proof will take care of authenticating the token, verifying it is not expired, and retrieving the current User on every request, so you just need to add a `before_action` call for the actions you want to restrict to authenticated users.
## Installation
In your Gemfile:

gem 'proof-rails', require: "proof"
## Usage
To quickly start using proof with Devise, use the generator:

rails generate proof:devise User

Where `User` is the class name of your User model.

For other authentication solutions or custom Devise setups, you must first use proof_actions in the controller you would like the login route to be on:

class AuthenticationController < ActionController::Base
      proof_actions
    end
`proof_actions` will create a `login` action on the controller it is called in. This login action will accept the parameters `identifier` and `password`. Proof will use these parameters to authenticate the corresponding user and create a JWT token. If the parameters correspond to a nonexistant or invalid user, proof will return an error message with the status `401 Unauthorized`.

#### Using `proof_actions`

`proof_actions` accepts a number of options, allowing you to configure it for any authentication setup:

proof_actions authenticatable: :User, identifier: :email, password: :password, authenticate: :authenticate

`authenticatable:` specifies the name of the model which represents your users.

`identifier:` specifies the name of the field which uniquely identifies each user, and which the user uses to log in. For devise, this is the `email` field.

`password:` specifies the name of the param which holds the password used to authenticate a user. This is almost always `password`, but sometimes the param goes by a different name.

`authenticate:` specifies the name of the method on the User model which accepts a password to authenticate the user. This is the name of an instance method on the User model which accepts the `password` param, and returns either true or false to indicate authentication.

#### Handle Bad Tokens

By default proof will handle invalid token by rendering json like so:

{ error: "Invalid Credentials." }

To customize this you have to options you can pass to `proof_actions`.

`error_json:` which allows you to fully overide the default json. Used like so:

proof_actions authenticatable: :User, authenticate: :valid_password?, error_json: { errors: { general: [ "Not Authorized" ] } } do |user, token|
      Api::V1::SessionSerializer.new(user).attributes
    end

`raise_error:` which instead of rendering json will trigger an exception that can be handled like so:

rescue_from Proof::NotAuthorizedError, with: :user_not_authorized

This will likely need to be in the ApplicationController.

The usage looks like:

Used like so:

proof_actions authenticatable: :User, authenticate: :valid_password?, raise_error: true do |user, token|
      Api::V1::SessionSerializer.new(user).attributes
    end

#### Modify Token

Proof also allows for a optional block that returns a hash to modify the json return

proof_actions authenticatable: :User do |user, token|
      {
        user_id: user.id,
        email: user.email,
        auth_token: token
      }
    end

#### How to handle the token

When your application sends a `POST` request to the `login` action, it will return JSON with the key `auth_token` if it finds a valid user. Your application must then save this token and send it with every request under the `Authorization` HTTP header, in the Bearer format: `Bearer [token]`.

#### Routeing

You must route the `login` action yourself. For example, if you had a controller named `AuthenticationController`, you could create a `/login` route like so:

post '/login', to: 'authentication#login'

In order to restrict an action to authenticated users, simply use a `before_action` call for the actions you'd like to restrict:

before_action :require_proof, only: [:index, :show]

`require_proof` accepts the option `authenticatable`, representing the name of the User class. This is `User` by default. If you'd like to change it, you must call `before_action` like so:

before_action only: [:index, :show] do
      require_proof authenticatable: :User
    end
Where `:User` is the name of the model class representing your users.

### After Authorization

Proof gives you access to the following helper methods in the views and the controllers:

`current_user` Returns the current authenticated user in the controller and the views. For example:

before_action :require_proof, only: :index
    def index
      @posts = current_user.posts
    end

### Token

If you need to access the token yourself you can use `Proof::Token`.

For example if you want to send a token in a Serializer you can create the token like so.

Proof::Token.from_data({ user_id: object.id }, false, secret, 'HS256', expiration_date)

The parameters look like this:

- data
  - expire_token = true
  - secret_key = Rails.application.secrets.secret_key_base
  - algorithm = 'HS256'
  - expiration_date = 24.hours.from_now.to_i

To be used correctly `data` always needs a valid `user_id`.

## Contribute
Proof is fully-tested using MiniTest. Make sure to write tests for new functionality you add in, and run `rake test` before pushing your changes.

To help out, either contribute to this repository, or write adapters for popular client-side libraries, such as Ember, Angular, and React.

proof

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README