userbin 1.6.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9c4187739931daad2ab4737e663b9d048ab3728d
-  data.tar.gz: 0e22aae813008c87dce6625c8735ca819358cb1f
+  metadata.gz: 8a4569c81702c9644066b6bdaa74246a068632ba
+  data.tar.gz: 17a9fd3f2c51969565ca485adf025601e74b4029
 SHA512:
-  metadata.gz: 3938f98100098d8b5b8f0048addfbbc89fc8204e4e68c83c57f8546565e63dfb84bf67cd2bd3f9cfa039d14d0adf5b809c66bcc7e5609025a441bd8172f9dccc
-  data.tar.gz: 046433d4a20b1a5c18fe719d4ada56b4d46dce15a0bcbc8610f22c6292e46f656141b4e1cab99876f7f9257b5b1405289beace703a3e0cf66a16ae43dea661cf
+  metadata.gz: 79a9d2ac54fd2dafed09ca930e769f48b01d8b1b8896cde859f7ea98c2fa599b77529018409dac5ab41b902da43882878d43df8160079d324c4ffe78206b3b5b
+  data.tar.gz: b7024885c8ee6fca6566550b763ca2f81f7684fbda42bce710c90bf1e27378ade15597ab93a0b4db6b2384a3be06811f0b7e0bd166b1a526b2af0f4f08623d7e

data/README.md

@@ -5,286 +5,47 @@
 [![Dependency Status](https://gemnasium.com/userbin/userbin-ruby.png)](https://gemnasium.com/userbin/userbin-ruby)
 [![Coverage Status](https://coveralls.io/repos/userbin/userbin-ruby/badge.png)](https://coveralls.io/r/userbin/userbin-ruby)
 
-**[Userbin](https://userbin.com) adds an additional security layer to your application by providing account takeover protection and two-factor authentication in a white-label package**
-
-Your users **do not** need to be signed up or registered for Userbin before using the service and there's no need for them to download any proprietary apps. Also, Userbin requires **no modification of your current database schema** as it uses your local user IDs.
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Getting Started](#getting-started)
-- [Active Sessions](#active-sessions)
-- [Security Events](#security-events)
-- [Two-factor Authentication](#two-factor-authentication)
-  - [Pairing with Google Authenticator](#pairing-with-google-authenticator)
-  - [Pairing with Phone Number (SMS)](#pairing-with-phone-number-sms)
-  - [Pairing with YubiKey](#pairing-with-yubikey)
-  - [Enabling and Disabling](#enabling-and-disabling)
-  - [Authenticating](#authenticating)
-  - [Backup Codes](#backup-codes)
-  - [List Pairings](#list-pairings)
+**[Userbin](https://userbin.com) adds real-time monitoring of your authentication stack, instantly notifying you and your users on potential account hijacks.**
 
 ## Installation
 
 Add the `userbin` gem to your `Gemfile`
 
 ```ruby
-gem "userbin"
+gem 'userbin'
 ```
 
 Load and configure the library with your Userbin API secret in an initializer or similar.
 
 ```ruby
-Userbin.api_secret = "YOUR_API_SECRET"
+Userbin.api_secret = 'YOUR_API_SECRET'
 ```
 
-## Getting started
-
-### 1. Logging in and out
+A Userbin client instance will automatically be made available as `userbin` in your Rails, Sinatra or Padrino controllers.
 
-You should call `login` as soon as the user has logged in to your application to start the Userbin session. Pass a unique user identifier, and an *optional* hash of user properties which are used when searching for users in your dashboard.
+## Tracking security events
 
-```ruby
-def your_after_login_hook
-  userbin.login(current_user.id, email: current_user.email)
-end
-```
+`track` lets you record the security-related actions your users perform. The more actions you track, the more accurate Userbin is in identifying fraudsters.
 
-When a user logs out from within your application, call `logout` to tell Userbin to remove the session from the user's [active sessions](#active-sessions).
+When you have access to a logged in user, send along the same user identifier as when you initiated Userbin.js.
 
 ```ruby
-def your_after_logout_hook
-  userbin.logout
-end
+userbin.track(
+  user_id: user.id,
+  name: 'login.succeeded')
 ```
 
-**Check that it works** by logging in to your application and watch your user appear in the [Userbin dashboard](https://dashboard.userbin.com).
-
-### 2. Protecting routes
-
-Call `authorize!` just before your `current_user` is being initialized. Usually you'll want to override your normal authentication filter, e.g. `authenticate_user!` if you're using Devise.
-
-- `UserUnauthorizedError` will be raised if `login` has not yet been called, or if the session is no longer valid.
-- `ChallengeRequiredError` will be raised when the user has enabled two-factor authentication and is logging in from an untrusted device.
+If you don't have access to a logged in user just omit `user_id`, typically when tracking failed logins.
 
 ```ruby
-class ApplicationController < ActionController::Base
-  rescue_from Userbin::UserUnauthorizedError, with: :user_unauthorized
-  rescue_from Userbin::ChallengeRequiredError, with: :challenge_required
-
-  # IMPLEMENT: Override the authentication method from your framework
-  def authenticate_user!
-    userbin.authorize!
-    super
-  end
-
-  # IMPLEMENT: Log out your user locally
-  def user_unauthorized
-    sign_out
-    redirect_to root_path
-  end
-
-  # IMPLEMENT: Redirect to two-factor authentication login
-  def challenge_required
-    redirect_to show_challenge_path
-  end
-end
+userbin.track(name: 'login.failed')
 ```
 
-Then use the overridden filter in your protected routes as you normally would, and all your critical flows will be protected from account takeover.
-
-```ruby
-class AccountController < ApplicationController
-  before_filter :authenticate_user!
-end
-```
-
-## Active Sessions
-
-Show a list of sessions currently signed to a user's account.
-
-The *context* is from the last recorded [security event](#security-events) on a session.
-
-```ruby
-userbin.sessions.each do |session|
-  puts session.id          # => 'yt9BkoHzcQoou4jqbQbJUqqMdxyxvCBr'
-  puts session.context.ip  # => '88.12.129.1'
-end
-```
-
-Destroy a session to revoke access and trigger a `UserUnauthorizedError` the next time `authorize!` refreshes the session token, which is within 5 minutes.
-
-```ruby
-userbin.sessions.destroy('yt9BkoHzcQoou4jqbQbJUqqMdxyxvCBr')
-```
-
-## Security Events
-
-List a user's recent account activity, which include security events such as user logins and failed two-factor attempts. See the [Event API](https://api.userbin.com/#events) for a list of all the available events.
-
-```ruby
-userbin.events.each do |event|
-  puts event.name                        # => 'session.created'
-  puts event.context.ip                  # => '88.12.129.1'
-  puts event.context.location.country    # => 'Sweden'
-  puts event.context.user_agent.browser  # => 'Chrome'
-end
-```
-
-## Two-factor Authentication
-
-Using two-factor authentication involves two steps: **pairing** and **authenticating**.
-
-### Pairing
-
-Before your users can protect their account with two-factor authentication, they will need to pair their their preferred way of authenticating. The [Pairing API](https://api.userbin.com/#pairings) lets users add, verify, and remove authentication channels. Only *verified* pairings are valid for authentication.
-
-#### Pairing with Google Authenticator
-
-The user visits a page to add Google Authenticator to their account. First create a new Authenticator pairing to generate a QR code image.
-
-```ruby
-@authenticator = userbin.pairings.create(type: 'authenticator')
-```
-
-Render a page containing the QR code, which the user scans with Google Authenticator.
-
-```erb
-<img src="<%= @authenticator[:qr_url] %>">
-```
-
-After scanning the QR code, the user will enter the 6 digit token that Google Authenticator displays, and submit the form. Capture the response and verify the pairing.
-
-```ruby
-begin
-  userbin.pairings.verify(params[:pairing_id], response: params[:code])
-rescue Userbin::InvalidParametersError
-  flash.notice = 'Wrong code, try again'
-end
-```
-
-#### Pairing with Phone Number (SMS)
-
-Create a new phone number pairing which will send out a verification SMS.
-
-```ruby
-@phone_number = userbin.pairings.create(
-  type: 'phone_number', number: '+1739855455')
-```
-
-Catch the code from the user to pair the phone number.
-
-```ruby
-begin
-  userbin.pairings.verify(params[:pairing_id], response: params[:code])
-rescue Userbin::InvalidParametersError
-  flash.notice = 'Wrong code, try again'
-end
-```
-
-#### Pairing with YubiKey
-
-YubiKeys are immediately verified for two-factor authentication.
-
-```ruby
-begin
-  userbin.pairings.create(type: 'yubikey', otp: params[:code])
-rescue Userbin::InvalidParametersError
-  flash.notice = 'Wrong code, try again'
-end
-```
-
-#### Enabling and Disabling
-
-For the sake of flexibility, two-factor authentication isn't enabled automatically when you add your first pairing.
-
-```ruby
-userbin.enable_mfa!
-userbin.disable_mfa!
-```
-
-### Authenticating
-
-If the user has enabled two-factor authentication, `authorize!` might raise `ChallengeRequiredError`, which means they'll have to verify a challenge to proceed.
-
-Capture this error just as with UserUnauthorizedError and redirect the user to a path **not protected** by `authorize!`.
-
-If the user tries to reach a path protected by `authorize!` after a challenge has been created but still not verified, the session will be destroyed and UserUnauthorizedError raised.
-
-```ruby
-class ApplicationController < ActionController::Base
-  rescue_from Userbin::ChallengeRequiredError do |exception|
-    redirect_to show_challenge_path
-  end
-  # ...
-end
-```
-
-Create a challenge, which will send the user and SMS if this is the default pairing. After the challenge has been verified, `authorize!` will not throw any further exceptions until any suspicious behavior is detected.
-
-When you call `trust_device`, the user will not be challenged for secondary authentication when they log in to your application from that device for a set period of time. You could add this to your form as a checkbox option.
-
-```ruby
-class ChallengeController < ApplicationController
-  def show
-    @challenge = userbin.challenges.create
-  end
-
-  def verify
-    challenge_id = params.require(:challenge_id)
-    code = params.require(:code)
-
-    userbin.challenges.verify(challenge_id, response: code)
-
-    # Avoid verification on next login for better experience
-    userbin.trust_device if params[:trust_device]
-
-    # Yay, the challenge was verified!
-    redirect_to root_url
-
-  rescue Userbin::ForbiddenError => e
-    sign_out # log out your user locally
-
-    flash.notice = 'Wrong code, bye!'
-    redirect_to root_path
-  end
-end
-```
-
-### Backup Codes
-
-List or generate new backup codes used for when the user didn't bring their authentication device.
-
-```ruby
-userbin.backup_codes
-userbin.generate_backup_codes(count: 8)
-```
-
-### List Pairings
-
-List all pairings.
-
-```ruby
-# List all pairings
-userbin.pairings.each do |pairing|
-  puts pairing.id      # => 'yt9BkoHzcQoou4jqbQbJUqqMdxyxvCBr'
-  puts pairing.type    # => 'authenticator'
-  puts pairing.default # => true
-end
-```
-
-Set a pairing as the default one.
-
-```ruby
-userbin.pairings.set_default!('yt9BkoHzcQoou4jqbQbJUqqMdxyxvCBr')
-```
-
-Remove a pairing. If you remove the default pairing, two-factor authentication will be disabled.
-
-```ruby
-userbin.pairings.destroy('yt9BkoHzcQoou4jqbQbJUqqMdxyxvCBr')
-```
+All the available events are:
 
+- `login.succeeded`
+- `login.failed`
+- `logout.succeeded`
 
 ## Configuration
 
@@ -293,7 +54,7 @@ Userbin.configure do |config|
   # Same as setting it through Userbin.api_secret
   config.api_secret = 'secret'
 
-  # Userbin::RequestError is raised when timing out (default: 2.0)
+  # Userbin::RequestError is raised when timing out (default: 30.0)
   config.request_timeout = 2.0
 end
 ```

data/lib/userbin.rb

@@ -1,3 +1,4 @@
+require 'pry'
 require 'her'
 require 'userbin/ext/her'
 require 'faraday_middleware'

data/lib/userbin/client.rb

@@ -32,7 +32,8 @@ module Userbin
 
       @request_context = {
         ip: request.ip,
-        user_agent: request.user_agent
+        user_agent: request.user_agent,
+        cookie_id: cookies['__cid']
       }
     end
 
@@ -126,5 +127,9 @@ module Userbin
     def has_default_pairing?
       @store.session_token ? @store.session_token.has_default_pairing? : false
     end
+
+    def track(opts = {})
+      Userbin::Event.post('/v1/events', opts)
+    end
   end
 end

data/lib/userbin/request.rb

@@ -106,9 +106,11 @@ module Userbin
           return @app.call(env) unless userbin
 
           userbin.request_context.each do |key, value|
-            header =
+            if value
+             header =
               "X-Userbin-#{key.to_s.gsub('_', '-').gsub(/\w+/) {|m| m.capitalize}}"
-            env[:request_headers][header] = value
+              env[:request_headers][header] = value
+            end
           end
           @app.call(env)
         end

data/lib/userbin/version.rb

@@ -1,3 +1,3 @@
 module Userbin
-  VERSION = "1.6.1"
+  VERSION = "1.7.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: userbin
 version: !ruby/object:Gem::Version
-  version: 1.6.1
+  version: 1.7.0
 platform: ruby
 authors:
 - Johan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-20 00:00:00.000000000 Z
+date: 2014-12-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: her