userbin 1.1.4 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1fff5de3f63cad930c9197795fb5f73bb3136fa9
-  data.tar.gz: 9736769ebafb7cb7766c4328feb1fc4084e2790f
+  metadata.gz: 744a85b12224637026c348146ce9e1baba43796a
+  data.tar.gz: 52e72314536f2f65636313f0efafd9b7901fb473
 SHA512:
-  metadata.gz: 8f6f88837d08d9a2dbc785c63f28933a84021f7361cf802af5f85df876bd46c3a9acbafb3fbd9a3abc8625550cb62b5e997b86fcd8f0b34e6254bd5379ea11ce
-  data.tar.gz: 21259c54e483df37fcfa39526f7f7247444b0ab1c536ecb5d88c343bca5622d4bd33c7786dc03b7c7372c581c18b859b180e8386f2e40dc4cb21005754a5e085
+  metadata.gz: 11c9a493bc34d29161da8657a397ea57c3a310a73758b8b2138075bf94ca9bcb52b55fc94c01622e8d90a73b6904d4d2563f68b438911dfd1ab02a2e09f645db
+  data.tar.gz: 6a29b61d8966dbb116f55711000a0e73cdef214cbca9faf6a3e366dcd7303eecca8d9d4def5b9d58e970cd82443c623d5d245886838e016f60d15aa684296c47

data/README.md

@@ -27,88 +27,123 @@ Install the gem
 bundle install
 ```
 
-Load and configure the library with your Userbin API secret in an initializer or similar
+Load and configure the library with your Userbin API secret in an initializer or similar.
 
 ```ruby
 require 'userbin'
 Userbin.api_secret = "YOUR_API_SECRET"
 ```
 
-## Monitor a user
+## The basics
 
-First you'll need to **initialize a Userbin client** for every incoming HTTP request and add it to the environment so that it's accessible during the request lifetime.
+First you'll need to initialize a Userbin client for every incoming HTTP request and preferrably add it to the environment so that it's accessible during the request lifetime.
 
-To **monitor a logged in user**, simply call `authorize!` on the Userbin object. You need to pass the user id, and optionally a hash of user properties, preferrable including at least `email`. This call only result in an HTTP request once every 5 minutes.
+```ruby
+env['userbin'] = Userbin::Client.new(request)
+```
 
-### 1. Authorize the current user
+At any time, a call to Userbin might result in an exception, maybe because the user has been logged out. You should catch these errors in one place and take action. Just catch and display all Userbin errors for now.
 
 ```ruby
 class ApplicationController < ActionController::Base
-  # Define a before filter which is run on all requests
-  before_filter :initialize_userbin
-
-  # Your controller code here
-
-  private
-  def initialize_userbin
-    # Initialize Userbin and add it to the request environment
-    env['userbin'] = Userbin::Client.new(request)
-
-    if current_user
-      # Optional details for text messages, emails and your dashboard
-      user_properties = {
-        email: current_user.email, # recommended
-        # Add `name`, `username` and `image` for improved experience
-      }
-
-      begin
-        # This checks against Userbin once every 5 minutes under the hood.
-        # The `id` MUST be unique across all your users and roles
-        env['userbin'].authorize!(current_user.id, user_properties)
-      rescue Userbin::Error
-        # Logged out from Userbin; clear your current_user and logout
-        # TODO: implement!
-      end
-    end
+  rescue_from Userbin::Error do |e|
+    redirect_to root_url, alert: e.message
   end
 end
 ```
 
-> **Verify that it works:** Log in to your Ruby application with an existing user, and [watch a user appear](https://dashboard.userbin.com/users) in your Userbin dashboard.
-
-### 2. Log out
+## Tracking user sessions
 
-As a last step, you'll need to **end the Userbin session** when the user logs out from your application.
+You should call `login` as soon as the user has logged in to your application. Pass a unique user identifier, and an optional hash of user properties. This starts the Userbin session.
 
 ```ruby
-def logout
-  # Your code for logging out a user
+def after_login_hook
+  env['userbin'].login(current_user.id, email: current_user.email)
+end
+```
+
+And call `logout` just after the user has logged out from your application. This ends the Userbin session.
 
-  # End the Userbin session
+```ruby
+def after_logout_hook
   env['userbin'].logout
 end
 ```
 
-> **Verify that it works:** Log out of your Ruby application and watch the number of sessions for the user in your Userbin dashboard return to zero.
+The session created by login expires typically every 5 minutes and needs to be refreshed with new metadata. This is done by calling authorize. Makes sure that the session hasn't been revoked or locked.
+
+```ruby
+before_filter do
+  env['userbin'].authorize
+end
+```
+
+> **Verify that it works:** Log in to your Ruby application and watch a user appear in the [Userbin dashboard](https://dashboard.userbin.com).
 
-## Add a link to the user's security settings
 
-Create a new route where you redirect the user to its security settings page, where they can configure two-factor authentication, revoke suspicious sessions and set up notifications.
+## Configuring two-factor authentication
+
+### Pairing
+
+#### Google Authenticator
+
+Create a new Authenticator pairing to get hold of the QR code image to show to the user.
 
 ```ruby
-class UsersController < ApplicationController
-  def security_settings
-    redirect_to env['userbin'].security_settings_url
-  end
+authenticator = env['userbin'].pairings.create(type: 'authenticator')
+
+puts authenticator.qr_url # => "http://..."
+```
+
+Catch the code from the user to pair the Authenticator app.
+
+```ruby
+authenticator = env['userbin'].pairings.build(id: params[:pairing_id])
+
+begin
+  authenticator.verify(response: params[:code])
+rescue
+  flash.notice = 'Wrong code, try again'
 end
 ```
 
-> **Verify that it works:** Log in to your Ruby application and visit your new route. This should redirect to https://security.userbin.com where you'll see that you have one active session. *Don't enable two-factor authentication just yet.*
+#### YubiKey
 
-## Two-factor authentication
+YubiKeys are immediately verified for two-factor authentication.
 
+```ruby
+begin
+  env['userbin'].pairings.create(type: 'yubikey', otp: code)
+rescue
+  flash.notice = 'Wrong code, try again'
+end
+```
 
-### 1. Protect routes
+#### SMS
+
+Create a new phone number pairing which will send out a verification SMS.
+
+```ruby
+phone_number = env['userbin'].pairings.create(
+  type: 'phone_number', number: '+1739855455')
+```
+
+Catch the code from the user to pair the phone number.
+
+```ruby
+phone_number = env['userbin'].pairings.build(id: params[:pairing_id])
+
+begin
+  phone_number.verify(response: params[:code])
+rescue
+  flash.notice = 'Wrong code, try again'
+end
+```
+
+
+### Usage
+
+#### 1. Protect routes
 
 If the user has enabled two-factor authentication, `two_factor_authenticate!` 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.
 
@@ -138,9 +173,7 @@ class UsersController < ApplicationController
 end
 ```
 
-> **Verify that it works:** Enable two-factor on your security settings page, followed by a logout and and login to your Ruby application. You should now be redirected to one of the routes in the case statement.
-
-### 2. Show the two-factor authentication form to the user
+#### 2. Show the two-factor authentication form to the user
 
 ```html
 <p>
@@ -154,7 +187,7 @@ end
 </form>
 ```
 
-### 3. Verify the code from the user
+#### 3. Verify the code from the user
 
 The user enters the authentication code in the form and posts it to your handler.
 

data/lib/userbin.rb

@@ -23,9 +23,11 @@ end
 
 # These need to be required after setting up Her
 require 'userbin/models/model'
+require 'userbin/models/event'
 require 'userbin/models/challenge'
 require 'userbin/models/channel'
-require 'userbin/models/token'
+require 'userbin/models/monitoring'
+require 'userbin/models/pairing'
+require 'userbin/models/recovery_code'
 require 'userbin/models/session'
 require 'userbin/models/user'
-require 'userbin/models/monitoring'

data/lib/userbin/client.rb

@@ -36,23 +36,31 @@ module Userbin
       Userbin::SessionToken.new(token) if token
     end
 
-    def authorize!(user_id, user_attrs = {})
+    def identify(user_id)
       # The user identifier is used in API paths so it needs to be cleaned
       user_id = URI.encode(user_id.to_s)
 
       @session_store.user_id = user_id
+    end
+
+    def login(user_id, user_attrs = {})
+      # Clear the session token if any
+      self.session_token = nil
 
-      unless session_token
-        # Create a session, and implicitly a user with user_attrs
-        session = Userbin::Session.post(
-          "users/#{user_id}/sessions", user: user_attrs)
+      identify(user_id)
 
-        # Set the session token for use in all subsequent requests
-        self.session_token = session.token
-      else
-        if session_token.expired?
-          Userbin::Monitoring.heartbeat
-        end
+      session = Userbin::Session.post(
+        "users/#{@session_store.user_id}/sessions", user: user_attrs)
+
+      # Set the session token for use in all subsequent requests
+      self.session_token = session.token
+    end
+
+    def authorize
+      return unless session_token
+
+      if session_token.expired?
+        Userbin::Monitoring.heartbeat
       end
     end
 
@@ -122,5 +130,41 @@ module Userbin
       session_token.has_challenge?
     end
 
+    def two_factor_enabled?
+      session_token.mfa_enabled?
+    end
+
+    def two_factor_required?
+      session_token.needs_challenge?
+    end
+
+    def events
+      Userbin::User.new('current').events
+    end
+
+    def sessions
+      Userbin::User.new('current').sessions
+    end
+
+    def pairings
+      Userbin::User.new('current').pairings
+    end
+
+    def channels
+      Userbin::User.new('current').channels
+    end
+
+    def recovery_codes
+      Userbin::User.new('current').recovery_codes
+    end
+
+    def enable_mfa
+      Userbin::User.new('current').enable_mfa
+    end
+
+    def disable_mfa
+      Userbin::User.new('current').disable_mfa
+    end
+
   end
 end

data/lib/userbin/errors.rb

@@ -6,7 +6,7 @@ class Userbin::ConfigurationError < Userbin::Error; end
 
 class Userbin::ApiError < Userbin::Error; end
 
-class Userbin::BadRequest < Userbin::ApiError; end
+class Userbin::BadRequestError < Userbin::ApiError; end
 class Userbin::UnauthorizedError < Userbin::ApiError; end
 class Userbin::ForbiddenError < Userbin::ApiError; end
 class Userbin::NotFoundError < Userbin::ApiError; end

data/lib/userbin/models/channel.rb

@@ -1,5 +1,6 @@
 module Userbin
   class Channel < Model
-    has_one :token
+    collection_path "users/:user_id/channels"
+    belongs_to :user
   end
 end

data/lib/userbin/models/event.rb

@@ -0,0 +1,6 @@
+module Userbin
+  class Event < Model
+    collection_path "users/:user_id/events"
+    belongs_to :user
+  end
+end

data/lib/userbin/models/pairing.rb

@@ -0,0 +1,7 @@
+module Userbin
+  class Pairing < Model
+    collection_path "users/:user_id/pairings"
+    instance_post :verify
+    belongs_to :user
+  end
+end

data/lib/userbin/models/recovery_code.rb

@@ -0,0 +1,4 @@
+module Userbin
+  class RecoveryCode < Model
+  end
+end

data/lib/userbin/models/user.rb

@@ -3,7 +3,12 @@ module Userbin
     custom_post :import
     instance_post :lock
     instance_post :unlock
+    instance_post :enable_mfa
+    instance_post :disable_mfa
 
+    has_many :channels
+    has_many :events
+    has_many :pairings
     has_many :sessions
   end
 end

data/lib/userbin/request.rb

@@ -138,6 +138,9 @@ module Userbin
           when 404
             raise Userbin::NotFoundError, response[:message]
           when 419
+            # session token is invalid so clear it
+            RequestStore.store[:userbin].session_token = nil
+
             raise Userbin::UserUnauthorizedError, response[:message]
           when 422
             raise Userbin::InvalidParametersError, response[:message]

data/lib/userbin/session_token.rb

@@ -24,6 +24,10 @@ module Userbin
       !!@jwt.payload['chg']
     end
 
+    def mfa_enabled?
+      @jwt.payload['mfa'] == 1
+    end
+
     def challenge_type
       @jwt.payload['chg']['typ'].to_sym if has_challenge?
     end

data/lib/userbin/version.rb

@@ -1,3 +1,3 @@
 module Userbin
-  VERSION = "1.1.4"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: userbin
 version: !ruby/object:Gem::Version
-  version: 1.1.4
+  version: 1.2.0
 platform: ruby
 authors:
 - Johan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-20 00:00:00.000000000 Z
+date: 2014-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: her
@@ -179,10 +179,12 @@ files:
 - lib/userbin/jwt.rb
 - lib/userbin/models/challenge.rb
 - lib/userbin/models/channel.rb
+- lib/userbin/models/event.rb
 - lib/userbin/models/model.rb
 - lib/userbin/models/monitoring.rb
+- lib/userbin/models/pairing.rb
+- lib/userbin/models/recovery_code.rb
 - lib/userbin/models/session.rb
-- lib/userbin/models/token.rb
 - lib/userbin/models/user.rb
 - lib/userbin/request.rb
 - lib/userbin/session_store.rb

data/lib/userbin/models/token.rb

@@ -1,4 +0,0 @@
-module Userbin
-  class Token < Model
-  end
-end