userbin 0.4.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7a6270eb20148c6bebb1da458c2a6430ace408da
-  data.tar.gz: 2d901a0419f4604cb4a65e85c6a6b7c74a7e266b
+  metadata.gz: 0cdbc3c605fb145fe06f5586752132f09420cd82
+  data.tar.gz: cc87e2c5709a7070d2102f51ea609cb489c7f00e
 SHA512:
-  metadata.gz: d1f7c44451117fed832fc641fcf0116656c43d6ec9639065da58d8173974d48020a89e4c12f7b34dd304325b73e1952fce8b044dead9cd8aabdb17a8330be333
-  data.tar.gz: 02de0cea84a2f0bc8e3830e91754623f44b7e2d4fb0926b0ba90037b8e8b649397e67ea2b8cf5619eb548edb6f99770168243149f8c634cf827ef04763c7bd30
+  metadata.gz: 5939b5a66eb93ac00db2bcfe573edd1c31c4f961f7d11cc510a83a0c6daf7a43d1646474d65b3772ec1237fa0119b0178c99aa4986ee24502b250a03b7fe7577
+  data.tar.gz: d1cd8a693a8ae66770a497c34418452e31074ebbe1bb317d529155175c5ca02166885f404571c772bc66e270b863d99db5a33eca7f342b545af134312842e5a2

data/README.md

@@ -1,164 +1,140 @@
+
 [![Build Status](https://travis-ci.org/userbin/userbin-ruby.png)](https://travis-ci.org/userbin/userbin-ruby)
 [![Gem Version](https://badge.fury.io/rb/userbin.png)](http://badge.fury.io/rb/userbin)
 [![Dependency Status](https://gemnasium.com/userbin/userbin-ruby.png)](https://gemnasium.com/userbin/userbin-ruby)
 
-Userbin for Ruby
-================
-
-Userbin for Ruby adds user authentication, login flows and user management to your **Rails**, **Sinatra** or **Rack** app.
-
-[Userbin](https://userbin.com) provides a set of login, signup, and password reset forms that drop right into your application without any need of styling or writing markup. Connect your users via traditional logins or third party social networks. We take care of linking accounts across networks, resetting passwords, and keeping everything safe and secure.
-
-[Create a free account](https://userbin.com) at Userbin to start accepting users in your application.
+# Ruby SDK for Userbin
 
-Installation
-------------
+> Using Ruby on Rails? Install [Userbin for Devise](https://github.com/userbin/devise_userbin) for super-quick integration.
 
-1. Add the `userbin` gem to your `Gemfile`
+This library's purpose is to provide an additional security layer to your application by adding multi-factor authentication, user activity monitoring, and real-time threat protection in a white-label package. Your users **do not** need to be signed up or registered for Userbin before using the service.
 
-    ```ruby
-    gem "userbin"
-    ```
+Your users can now easily activate two-factor authentication, configure the level of security in terms of monitoring and notifications and take action on suspicious behaviour. These settings are available as a per-user security settings page which is easily customized to fit your current layout.
 
-1.  Install the gem
+## Getting started
 
-    ```shell
-    bundle install
-    ```
+Add the `userbin` gem to your `Gemfile`
 
-2.  Configure the Userbin module with the credentials you got from signing up.
-
-    In a Rails app, put the following code into a new file at `config/initializers/userbin.rb`, and in Sinatra put it in your main application file and add `require "userbin"`.
-
-    ```ruby
-    Userbin.configure do |config|
-      config.app_id = "YOUR_APP_ID"
-      config.api_secret = "YOUR_API_SECRET"
-    end
-    ```
-
-    If you don't configure the `app_id` and `api_secret`, the Userbin module will read the `USERBIN_APP_ID` and `USERBIN_API_SECRET` environment variables. This may come in handy on Heroku.
+```ruby
+gem "userbin"
+```
 
-3.  **Rack/Sinatra apps only**: Activate the Userbin Rack middleware
+Install the gem
 
-    ```ruby
-    use Userbin::Authentication
-    ```
+```bash
+bundle install
+```
 
+Load and configure the library with your Userbin API secret.
 
-Usage
------
+```ruby
+require 'userbin'
+Userbin.api_secret = "YOUR_API_SECRET"
+```
 
-### Forms
+## Authenticate
 
-An easy way to integrate Userbin is via the [Widget](https://userbin.com/docs/javascript#widget), which will take care of building forms, validating input and provides a drop-in design that adapts nicely to all devices.
+`authenticate` is the key component of the Userbin API. It lets you tie a user to their actions and record properties about them. Whenever any suspious behaviour is detected or a user gets locked out, a call to `authenticate` may throw an exception which needs to be handled by your application.
 
-The Widget is fairly high level, so remember that you can still use Userbin with your [own forms](https://userbin.com) if it doesn't fit your use-case.
+You’ll want to `authenticate` a user with any relevant information as soon as the current user object is assigned in your application. The method returns a *session token* that you store in a session or cookie for future reference. Either you use the Userbin session token as the ground truth for the user being logged in, or you can store it separately in tandem with your current session.
 
-The following links will open up the Widget with the login or the signup form respectively.
+#### Example
 
-```html
-<a class="ub-login">Log in</a>
-```
+```ruby
 
-```html
-<a class="ub-signup">Sign up</a>
-```
+options = {
+  properties: {
+    email: current_user.email,
+    name: current_user.full_name
+  },
+  context: {
+    ip: request.ip,
+    user_agent: request.user_agent
+  }
+}
 
-The logout link will clear the session and redirect the user back to your root path:
+session_token =
+  Userbin.authenticate(session[:userbin], current_user.id, options)
 
-```html
-<a class="ub-logout">Log out</a>
+session[:userbin] = session_token
 ```
 
-### The current user
+#### Arguments
 
-Userbin keeps track of the currently logged in user which can be accessed through the `current_user` property. This automatically taps into libraries such as the authorization solution [CanCan](https://github.com/ryanb/cancan).
+The first argument is a session token from a previous call to `authenticate`. This variable is obviously nil on the very first call, where a HTTP request will be made and a new session created.
 
-```erb
-Welcome to your account, <%= current_user.email %>
-```
+The second argument is a locally unique identifier for the logged in user, commonly the `id` field. This is the identifier you'll use further on when querying the user.
 
-To check if a user is logged in, use `user_logged_in?` (or its alias `user_signed_in?` if you prefer Devise conventions)
+- `properties` (Hash, optional) - A Hash of properties you know about the user. See the User reference documentation for available fields and their meaning.
+- `context` (Hash, optional) - A Hash specifying the user_agent and ip for the current request.
 
-```erb
-<% if user_logged_in? %>
-  You are logged in!
-<% end %>
-```
+> Note that every call to `authenticate` **does not** result in an HTTP request. Only the very first call, as well as expired session tokens result in a request. Session tokens expire every 5 minutes.
 
-**Rack/Sinatra apps only**: Since above helpers aren't available outside Rails, instead use `Userbin.current_user` and `Userbin.user_logged_in?`.
+## Two-factor authentication
 
-Configuration
--------------
+Two-factor authentication is available to your users out-of-the-box. By browsing to their Security Page, they're able to configure Google Authenticator and SMS settings, set up a backup phone number, and download their recovery codes.
 
-The `Userbin.configure` block supports a range of options additional to the Userbin credentials. None of the following options are mandatory.
+The session token returned from `authenticate` indicates if two-factor authentication is required from the user once your application asks for it. You can do this immediately after you've called `authenticate`, or you can wait until later. You have complete control over what actions you when you want to require two-factor authentication, e.g. when logging in, changing account information, making a purchase etc.
 
-### protected_path
+### Step 1: Prompt the user
 
-By default, Userbin reloads the current page on a successful login. If you set the `protected_path` option, users will be redirected to this path instead.
+`two_factor_authenticate!` acts as a gateway in your application. If the user has enabled two-factor authentication, this method will return the second factor that is used to authenticate. If SMS is used, this call will also send out an SMS to the user's registered phone number.
 
-Once set, this path and any sub-path of it will be protected from unauthenticated users by instead rendering a login form.
+When `two_factor_authenticate!` returns non-falsy value, you should display the appropriate form to the user, requesting their authentication code.
 
 ```ruby
-config.protected_path = '/dashboard'
+factor = Userbin.two_factor_authenticate!(session[:userbin])
+
+case factor
+when :authenticator
+  render 'two_factor_authenticator_form'
+when :sms
+  render 'two_factor_sms_form'
+end
 ```
 
-### root_path
+> Note that this call may return a factor more than once per session since Userbin continously scans for behaviour that would require another round of two-factor authentication, such as the user switching to another IP address or web browser.
 
-By default, Userbin reloads the current page on a successful logout. If you set the `root_path` option, users will be redirected to this path instead.
-
-```ruby
-config.root_path = '/login'
-```
+### Step 2: Verify the code
 
-### create_user and find_user
+The user enters the authentication code in the form and posts it to your handler. The last step is for your application to verify the code with Userbin by calling `verify_code`. The session token will get updated on a successful verification, so you'll need to update it in your local session or cookie.
 
-By default, `current_user` will reference a *limited* Userbin profile, enabling you to work without a database. If you override the functions `create_user` and `find_user`, the current user will instead reference one of your models. The `profile` object is an *extended* Userbin profile. For more information about the available attributes in the profile see the [Userbin profile](https://userbin.com/docs/concepts) documentation.
+`code` can be either a code from the Google Authenticator app, an SMS, or one of the user's recovery codes.
 
 ```ruby
-config.create_user = Proc.new { |profile|
-  User.create! do |user|
-    user.userbin_id = profile.id
-    user.email      = profile.email
-    user.photo      = profile.image
-  end
-}
-
-config.find_user = Proc.new { |userbin_id|
-  User.find_by_userbin_id(userbin_id)
-}
+begin
+  session[:userbin] =
+    Userbin.verify_code(session[:userbin], params[:code])
+
+  redirect_to logged_in_path
+rescue Userbin::UserUnauthorizedError => error
+  # invalid code, show the form again
+rescue Userbin::Forbidden => error
+  # no tries remaining, log out
+rescue Userbin::Error => error
+  # other error, log out
+end
 ```
 
-You'll need to migrate your users and add a reference to the Userbin profile:
+## Security page
 
-```ruby
-rails g migration AddUserbinIdToUsers userbin_id:integer:index
-```
+Every user has access to their security settings, which is a hosted page on Userbin. Here users can configure two-factor authentication, revoke suspicious sessions and set up notifications. The security page can be customized to fit your current layout by going to the appearance settings in your Userbin dashboard.
 
-### skip_script_injection
-
-By default, the Userbin middleware will automatically insert a `<script>` tag before the closing `</body>` in your HTML files in order to handle forms, sessions and user tracking. This script loads everything asynchronously, so it won't affect your page load speed. However if you want to have control of this procedure, set `skip_script_injection` to true and initialize the library yourself. To do that, checkout the [Userbin.js configuration guide](https://userbin.com/docs/javascript#configuration).
+**Important:** Since the generated URL contains a Userbin session token that needs to be up-to-date, it's crucial that you don't use this helper directly in your HTML, but instead create a new route where you redirect to the security page.
 
 ```ruby
-config.skip_script_injection = true
+get '/security'
+  redirect Userbin.security_page_url
+end
 ```
 
+## De-authenticate
 
-Further configuration and customization
----------------------------------------
-
-Your Userbin dashboard gives you access to a range of functionality:
+Whenever a user is logged out from your application, you should inform Userbin about this so that the active session is properly terminated. This prevents the session from being used further on.
 
-- Configure the appearance of the login widget to feel more integrated with your service
-- Connect 10+ OAuth providers like Facebook, Github and Google.
-- Use Markdown to generate mobile-ready transactional emails
-- Invite users to your application
-- See who is logging in and when
-- User management: block, remove and impersonate users
-- Export all your user data from Userbin
-
-
-Documentation
--------------
-For complete documentation go to [userbin.com/docs](https://userbin.com/docs)
+```ruby
+begin
+  token = session.delete(:userbin) # remove the local reference
+  Userbin.deauthenticate(token)
+rescue Userbin::Error; end
+```

data/lib/userbin.rb

@@ -1,48 +1,27 @@
+require 'pry'
+
 require 'her'
+require 'faraday_middleware'
 require 'multi_json'
 require 'openssl'
 require 'net/http'
+require 'request_store'
+require 'active_support/core_ext/hash/indifferent_access'
 
-require "userbin/userbin"
-require "userbin/basic_auth"
-
-require "userbin/railtie" if defined?(Rails::Railtie)
-
-api_endpoint = ENV.fetch('USERBIN_API_ENDPOINT') {
-  "https://api.userbin.com"
-}
-
-@api = Her::API.setup url: api_endpoint do |c|
-  c.use Userbin::BasicAuth
-  c.use Faraday::Request::UrlEncoded
-  c.use Her::Middleware::DefaultParseJSON
-  c.use Faraday::Adapter::NetHttp
-end
-
+require "userbin/version"
 require "userbin/configuration"
-require "userbin/events"
-require "userbin/current"
-require "userbin/session"
-require "userbin/authentication"
-
-class Userbin::Error < Exception; end
-class Userbin::SecurityError < Userbin::Error; end
-class Userbin::ConfigurationError < Userbin::Error; end
+require "userbin/request"
+require "userbin/jwt"
+require "userbin/utils"
+require "userbin/helpers"
+require "userbin/errors"
 
 module Userbin
-  class << self
-    def configure(config_hash=nil)
-      if config_hash
-        config_hash.each do |k,v|
-          config.send("#{k}=", v)
-        end
-      end
-
-      yield(config) if block_given?
-    end
-
-    def config
-      @configuration ||= Userbin::Configuration.new
-    end
-  end
+  API = Userbin.setup_api
 end
+
+# These need to be required after setting up Her
+require "userbin/models/base"
+require "userbin/models/challenge"
+require "userbin/models/session"
+require "userbin/models/user"

data/lib/userbin/configuration.rb

@@ -1,27 +1,25 @@
 module Userbin
-  class Configuration
-    attr_accessor :create_user
-    attr_accessor :find_user
-    attr_accessor :protected_path
-    attr_accessor :root_path
-    attr_accessor :skip_script_injection
-
-    # restricted_path is obsolete
-    alias :restricted_path :protected_path
-    alias :restricted_path= :protected_path=
+  class << self
+    def configure(config_hash=nil)
+      if config_hash
+        config_hash.each do |k,v|
+          config.send("#{k}=", v)
+        end
+      end
 
-    def initialize
-      self.skip_script_injection = false
+      yield(config) if block_given?
     end
 
-    def app_id
-      ENV['USERBIN_APP_ID'] || @_app_id
+    def config
+      @configuration ||= Userbin::Configuration.new
     end
 
-    def app_id=(value)
-      @_app_id = value
+    def api_secret=(api_secret)
+      config.api_secret = api_secret
     end
+  end
 
+  class Configuration
     def api_secret
       ENV['USERBIN_API_SECRET'] || @_api_secret
     end

data/lib/userbin/errors.rb

@@ -0,0 +1,5 @@
+class Userbin::Error < Exception; end
+class Userbin::Forbidden < Userbin::Error; end
+class Userbin::UserUnauthorizedError < Userbin::Error; end
+class Userbin::SecurityError < Userbin::Error; end
+class Userbin::ConfigurationError < Userbin::Error; end

data/lib/userbin/helpers.rb

@@ -0,0 +1,83 @@
+module Userbin
+  class << self
+
+    def authenticate(session_token, user_id, opts = {})
+      session = Userbin::Session.new(token: session_token)
+
+      user_data = opts.fetch(:properties, {})
+
+      if session.token
+        if session.expired?
+          session = Userbin.with_context(opts[:context]) do
+            session.refresh(user: user_data)
+          end
+        end
+      else
+        session = Userbin.with_context(opts[:context]) do
+          Userbin::Session.post(
+            "users/#{URI.encode(user_id.to_s)}/sessions", user: user_data)
+        end
+      end
+
+      session_token = session.token
+
+      # By encoding the context to the JWT payload, we avoid having to
+      # fetch the context for subsequent Userbin calls during the
+      # current request
+      jwt = Userbin::JWT.new(session_token)
+      jwt.merge!(context: opts[:context])
+      jwt.to_token
+    end
+
+    def deauthenticate(session_token)
+      return unless session_token
+
+      # Extract context from authenticated session token
+      jwt = Userbin::JWT.new(session_token)
+      context = jwt.payload['context']
+
+      Userbin.with_context(context) do
+        Userbin::Session.destroy_existing(session_token)
+      end
+    end
+
+    def two_factor_authenticate!(session_token)
+      return unless session_token
+
+      challenge = Userbin::JWT.new(session_token).payload['challenge']
+
+      if challenge
+        case challenge['type']
+        when 'otp_authenticator' then :authenticator
+        when 'otp_sms' then :sms
+        end
+      end
+    end
+
+    # TODO: almost the same as deauthenticate. Refactor?
+    def verify_code(session_token, response)
+      return unless session_token
+
+      # Extract context from authenticated session token
+      jwt = Userbin::JWT.new(session_token)
+      context = jwt.payload['context']
+
+      session = Userbin.with_context(context) do
+        Userbin::Session.new(token: session_token).verify(response: response)
+      end
+
+      session.token
+    end
+
+    def security_page_url(session_token)
+      return '' unless session_token
+      begin
+        app_id = Userbin::JWT.new(session_token).app_id
+        "https://security.userbin.com/?session_token=#{session_token}"
+      rescue Userbin::Error
+        ''
+      end
+    end
+
+  end
+end