Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/twilio/authy-devise

Authy Devise plugin to add Two-Factor Authentication
https://github.com/twilio/authy-devise

Last synced: about 2 months ago
JSON representation

Authy Devise plugin to add Two-Factor Authentication

Host: GitHub
URL: https://github.com/twilio/authy-devise
Owner: twilio
License: mit
Archived: true
Created: 2013-04-08T23:03:18.000Z (over 11 years ago)
Default Branch: master
Last Pushed: 2022-05-30T02:32:52.000Z (over 2 years ago)
Last Synced: 2024-07-19T13:45:54.025Z (2 months ago)
Language: Ruby
Size: 546 KB
Stars: 201
Watchers: 26
Forks: 84
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt

Awesome Lists containing this project

README

🚨🚨🚨

**This library is no longer actively maintained.** The Authy API has been replaced with the [Twilio Verify API](https://www.twilio.com/docs/verify). Twilio will support the Authy API through November 1, 2022 for SMS/Voice. After this date, we’ll start to deprecate the service for SMS/Voice. Any requests sent to the API after May 1, 2023, will automatically receive an error. Push and TOTP will continue to be supported through July 2023.

[Learn more about migrating from Authy to Verify.](https://www.twilio.com/blog/migrate-authy-to-verify)

Please visit the Twilio Docs for:
* [Verify + Ruby (Rails) quickstart](https://www.twilio.com/docs/verify/quickstarts/ruby-rails)
* [Twilio Ruby helper library](https://www.twilio.com/docs/libraries/ruby)
* [Verify API reference](https://www.twilio.com/docs/verify/api)
* **Coming soon**: Look out for a new Devise plugin to use Twilio Verify with Devise

Please direct any questions to [Twilio Support](https://support.twilio.com/hc/en-us). Thank you!

🚨🚨🚨

---

# Authy Devise [![Build Status](https://github.com/twilio/authy-devise/workflows/build/badge.svg)](https://github.com/twilio/authy-devise/actions)

This is a [Devise](https://github.com/plataformatec/devise) extension to add [Two-Factor Authentication with Authy](https://www.twilio.com/docs/authy) to your Rails application.

* [Pre-requisites](#pre-requisites)
* [Demo](#demo)
* [Getting started](#getting-started)
* [Configuring Models](#configuring-models)
* [With the generator](#with-the-generator)
* [Manually](#manually)
* [Final steps](#final-steps)
* [Custom Views](#custom-views)
* [Request a phone call](#request-a-phone-call)
* [Custom Redirect Paths (eg. using modules)](#custom-redirect-paths-eg-using-modules)
* [I18n](#i18n)
* [Session variables](#session-variables)
* [OneTouch support](#onetouch-support)
* [Generic authenticator token support](#generic-authenticator-token-support)
* [Rails 5 CSRF protection](#rails-5-csrf-protection)
* [Running Tests](#running-tests)
* [Notice: Twilio Authy API’s Sandbox feature will stop working on Sep 30, 2021](#notice-twilio-authy-apis-sandbox-feature-will-stop-working-on-sep-30-2021)
* [Copyright](#copyright)

## Pre-requisites

To use the Authy API you will need a Twilio Account, [sign up for a free Twilio account here](https://www.twilio.com/try-twilio).

Create an [Authy Application in the Twilio console](https://www.twilio.com/console/authy/applications) and take note of the API key.

## Demo

See [this repo for a full demo of using `authy-devise`](https://github.com/twilio/authy-devise-demo).

## Getting started

First get your Authy API key from [the Twilio console](https://www.twilio.com/console/authy/applications). We recommend you store your API key as an environment variable.

```bash
$ export AUTHY_API_KEY=YOUR_AUTHY_API_KEY
```

Next add the gem to your Gemfile:

```ruby
gem 'devise'
gem 'devise-authy'
```

And then run `bundle install`

Add `Devise Authy` to your App:

rails g devise_authy:install

--haml: Generate the views in Haml
--sass: Generate the stylesheets in Sass

### Configuring Models

You can add devise_authy to your user model in two ways.

#### With the generator

Run the following command:

```bash
rails g devise_authy [MODEL_NAME]
```

To support account locking (recommended), you must add `:authy_lockable` to the `devise :authy_authenticatable, ...` configuration in your model as this is not yet supported by the generator.

#### Manually

Add `:authy_authenticatable` and `:authy_lockable` to the `devise` options in your Devise user model:

```ruby
devise :authy_authenticatable, :authy_lockable, :database_authenticatable, :lockable
```

(Note, `:authy_lockable` is optional but recommended. It should be used with Devise's own `:lockable` module).

Also add a new migration. For example, if you are adding to the `User` model, use this migration:

```ruby
class DeviseAuthyAddToUsers < ActiveRecord::Migration[6.0]
def self.up
change_table :users do |t|
t.string :authy_id
t.datetime :last_sign_in_with_authy
t.boolean :authy_enabled, :default => false
end

add_index :users, :authy_id
end

def self.down
change_table :users do |t|
t.remove :authy_id, :last_sign_in_with_authy, :authy_enabled
end
end
end
```

#### Final steps

For either method above, run the migrations:

```bash
rake db:migrate
```

**[Optional]** Update the default routes to point to something like:

```ruby
devise_for :users, :path_names => {
:verify_authy => "/verify-token",
:enable_authy => "/enable-two-factor",
:verify_authy_installation => "/verify-installation",
:authy_onetouch_status => "/onetouch-status"
}
```

Now whenever a user wants to enable two-factor authentication they can go to:

http://your-app/users/enable-two-factor

And when the user logs in they will be redirected to:

http://your-app/users/verify-token

## Custom Views

If you want to customise your views, you can modify the files that are located at:

app/views/devise/devise_authy/enable_authy.html.erb
app/views/devise/devise_authy/verify_authy.html.erb
app/views/devise/devise_authy/verify_authy_installation.html.erb

### Request a phone call

The default views come with a button to force a request for an SMS message. You can also add a button that will request a phone call instead. Simply add the helper method to your view:

<%= authy_request_phone_call_link %>

## Custom Redirect Paths (eg. using modules)

If you want to customise the redirects you can override them within your own controller like this:

```ruby
class MyCustomModule::DeviseAuthyController < Devise::DeviseAuthyController

protected
def after_authy_enabled_path_for(resource)
my_own_path
end

def after_authy_verified_path_for(resource)
my_own_path
end

def after_authy_disabled_path_for(resource)
my_own_path
end

def invalid_resource_path
my_own_path
end
end
```

And tell the router to use this controller

```ruby
devise_for :users, controllers: {devise_authy: 'my_custom_module/devise_authy'}
```

## I18n

The install generator also copies a `Devise Authy` i18n file which you can find at:

config/locales/devise.authy.en.yml

## Session variables

If you want to know if the user is signed in using Two-Factor authentication,
you can use the following session variable:

```ruby
session["#{resource_name}_authy_token_checked"]

# Eg.
session["user_authy_token_checked"]
```

## OneTouch support

To enable [Authy push authentication](https://www.twilio.com/authy/features/push), you need to modify the Devise config file `config/initializers/devise.rb` and add configuration:

```
config.authy_enable_onetouch = true
```

## Generic authenticator token support

Authy supports other authenticator apps by providing a QR code that your users can scan.

> **To use this feature, you need to enable it in your [Twilio Console](https://www.twilio.com/console/authy/applications)**

Once you have enabled generic authenticator tokens, you can enable this in devise-authy by modifying the Devise config file `config/initializers/devise.rb` and adding the configuration:

```
config.authy_enable_qr_code = true
```

This will display a QR code on the verification screen (you still need to take a user's phone number and country code). If you have implemented your own views, the QR code URL is available on the verification page as `@authy_qr_code`.

## Rails 5 CSRF protection

In Rails 5 `protect_from_forgery` is no longer prepended to the `before_action` chain. If you call `authenticate_user` before `protect_from_forgery` your request will result in a "Can't verify CSRF token authenticity" error.

To remedy this, add `prepend: true` to your `protect_from_forgery` call, like in this example from the [Authy Devise demo app](https://github.com/twilio/authy-devise-demo):

```ruby
class ApplicationController < ActionController::Base
protect_from_forgery with: :exception, prepend: true
end
```

## Running Tests

Run the following command:

```bash
$ bundle exec rspec
```

## Notice: Twilio Authy API’s Sandbox feature will stop working on Sep 30, 2021
Twilio is discontinuing the Authy API’s Sandbox, a feature that allows customers to run continuous integration tests against a mock Authy API for free. The Sandbox is no longer being maintained, so we will be taking the final deprecation step of shutting it down on September 30, 2021. The rest of the Authy API product will continue working as-is.

This repo previously used the sandbox API as part of the test suite, but that has been since removed.

You will only be affected if you are using the sandbox API in your own application or test suite.

For more information please read this article on [how we are discontinuing the Twilio Authy sandbox API](https://support.authy.com/hc/en-us/articles/1260803396889-Notice-Twilio-Authy-API-s-Sandbox-feature-will-stop-working-on-Sep-30-2021).