userbin 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: eda8c2ec2217b83cb4943e8302c0844f7d72c158
-  data.tar.gz: ad7583bd3627cd2898cd2f95a687393e8e48d2dd
+  metadata.gz: ffb023fc0244c53569a55984108c8f5e6a6d0376
+  data.tar.gz: 3edcb3bd8e9419fd0dbd4135044933b50c8888f6
 SHA512:
-  metadata.gz: 888dea6e532ce801149b4f3ae95cf875835f5c5a61fbc81fe636983b266e7310097052c64d2b4c3dcccee0c5440ff79b2abaca0fd21c813feafd6328258da2a4
-  data.tar.gz: b5abb4dc7fc8f4f5f8b9a3d4a89a6d409c31322ce7748996d093d2eb72b8260972c998f02cd7621824334c788d875d97a323d55051892f386f2330cf30e9c8ff
+  metadata.gz: b81972686bf51fa8f71b613de9dfb7def38cb4c86d2106d1e1e3568529ec9f54787adf10085ca471802147afc3737989b06ac389d584075852bdafc1de93c943
+  data.tar.gz: dd8e6bc2f5c2d6b69ee1c32df5d1683d6aa99dfe40e0f1a4d34510b9f459c6b1124a2611376d86d51c696d77c430a572aeb4e8bd0fc50b31e3da4c41759a60ee

data/README.md

@@ -9,6 +9,10 @@
 
 <!-- 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. -->
 
+### Using Devise?
+
+If you're using [Devise](https://github.com/plataformatec/devise) for authentication, check out the **[Userbin extension for Devise](https://github.com/userbin/devise_userbin)** for an even easier integration.
+
 ## Getting started
 
 Add the `userbin` gem to your `Gemfile`
@@ -23,66 +27,152 @@ Install the gem
 bundle install
 ```
 
-Load and configure the library with your Userbin API secret.
+Load and configure the library with your Userbin API secret in an initializer or similar
 
 ```ruby
 require 'userbin'
 Userbin.api_secret = "YOUR_API_SECRET"
 ```
 
-Initialize a Userbin client for every incoming HTTP request and add it to the environment so that it's accessible during the request lifetime.
-
-```ruby
-env['userbin'] = Userbin::Client.new(request)
-```
-
+## Monitor a user
 
+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.
 
-## Monitor a user
+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.
 
-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.
+### 1. Authorize the current user
 
 ```ruby
-# do this for *every* request, right after current_user is assigned
-env['userbin'].authorize!(current_user.id, { email: current_user.email })
+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
+  end
+end
 ```
 
-Clear the session when the user logs out.
+> **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
+
+As a last step, you'll need to **end the Userbin session** when the user logs out from your application.
 
 ```ruby
-env['userbin'].logout
-```
+def logout
+  # Your code for logging out a user
 
+  # End the Userbin session
+  env['userbin'].logout
+end
+```
 
-Done! Now log in to your application and watch the user appear in your Userbin dashboard.
+> **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.
 
 ## 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.
+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.
 
 ```ruby
-redirect_to env['userbin'].security_settings_url
+class UsersController < ApplicationController
+  def security_settings
+    redirect_to env['userbin'].security_settings_url
+  end
+end
 ```
 
-## Activate two-factor authentication
+> **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.*
+
+## Two-factor authentication
+
+
+### 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.
 
 ```ruby
-factor = env['userbin'].two_factor_authenticate!
-
-case factor
-when :authenticator then render 'authenticator_form'
-when :sms then render 'sms_form'
+class UsersController < ApplicationController
+  before_filter :authenticate_with_userbin!
+
+  # Your controller code here
+
+  private
+  def authenticate_with_userbin!
+    begin
+      # Checks if two-factor authentication is needed. Returns nil if not.
+      factor = env['userbin'].two_factor_authenticate!
+
+      # Show form and message specific to the current factor
+      case factor
+      when :authenticator
+        redirect_to '/verify/authenticator'
+      when :sms
+        redirect_to '/verify/sms'
+      end
+    rescue Userbin::Error
+      # logged out from Userbin; clear your current_user and logout
+    end
+  end
 end
 ```
 
-The user enters the authentication code in the form and posts it to your handler.
+> **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.
 
-```ruby
-env['userbin'].two_factor_verify(params[:code])
+### 2. Show the two-factor authentication form to the user
+
+```html
+<p>
+  Open the two-factor authentication app on your device to view your
+  authentication code and verify your identity.
+</p>
+<form action="/users/handle_two_factor_response" method="post">
+  <label for="code">Authentication code</label>
+  <input id="code" name="code" type="text" />
+  <input type="submit" value="Verify code" />
+</form>
 ```
 
-## Handling errors
+### 3. Verify the code from the user
+
+The user enters the authentication code in the form and posts it to your handler.
 
-If any request runs into an subclass of `Userbin::Error` will be raised with more details on what went wrong.
+```ruby
+def handle_two_factor_response
+  # Get the authentication code from the form
+  authentication_code = params[:code]
+
+  begin
+    env['userbin'].two_factor_verify(authentication_code)
+  rescue Userbin::UserUnauthorizedError
+    # invalid code, show the form again
+  rescue Userbin::ForbiddenError
+    # no tries remaining, log out
+  rescue Userbin::Error
+    # logged out from Userbin; clear your current_user and logout
+  end
+
+  # We made it through two-factor authentication!
+end
+```

data/lib/userbin/client.rb

@@ -42,7 +42,7 @@ module Userbin
 
       @session_store.user_id = user_id
 
-      if !session_token
+      unless session_token
         # Create a session, and implicitly a user with user_attrs
         session = Userbin::Session.post(
           "users/#{user_id}/sessions", user: user_attrs)
@@ -65,7 +65,8 @@ module Userbin
       # Destroy the current session specified in the session token
       begin
         Userbin::Session.destroy_existing('current')
-      rescue Userbin::Error; end
+      rescue Userbin::Error # ignored
+      end
 
       # Clear the session token
       self.session_token = nil
@@ -112,5 +113,9 @@ module Userbin
       return session_token.challenge_type
     end
 
+    def authorized?
+      !!session_token
+    end
+
   end
 end

data/lib/userbin/configuration.rb

@@ -20,6 +20,12 @@ module Userbin
   end
 
   class Configuration
+    attr_accessor :request_timeout
+
+    def initialize
+      self.request_timeout = 2.0
+    end
+
     def api_secret
       ENV['USERBIN_API_SECRET'] || @_api_secret
     end

data/lib/userbin/request.rb

@@ -17,7 +17,7 @@ module Userbin
 
     def self.get_uname
       `uname -a 2>/dev/null`.strip if RUBY_PLATFORM =~ /linux|darwin/i
-    rescue Errno::ENOMEM => ex # couldn't create subprocess
+    rescue Errno::ENOMEM # couldn't create subprocess
       "uname lookup failed"
     end
 
@@ -41,6 +41,21 @@ module Userbin
         end
       end
 
+      # Handle request errors
+      #
+      class RequestErrorHandler < Faraday::Middleware
+        def call(env)
+          env.request.timeout = Userbin.config.request_timeout
+          begin
+            @app.call(env)
+          rescue Faraday::ConnectionFailed
+            raise Userbin::RequestError, 'Could not connect to Userbin API'
+          rescue Faraday::TimeoutError
+            raise Userbin::RequestError, 'Userbin API timed out'
+          end
+        end
+      end
+
       # Adds details about current environment
       #
       class EnvironmentHeaders < Faraday::Middleware
@@ -48,7 +63,8 @@ module Userbin
           begin
             env[:request_headers]["X-Userbin-Client-User-Agent"] =
               MultiJson.encode(Userbin::Request.client_user_agent)
-          rescue => error; end
+          rescue # ignored
+          end
 
           env[:request_headers]["User-Agent"] =
             "Userbin/v1 RubyBindings/#{Userbin::VERSION}"
@@ -98,36 +114,43 @@ module Userbin
         end
       end
 
-      class JSONParser < Her::Middleware::DefaultParseJSON
-        # This method is triggered when the response has been received. It modifies
-        # the value of `env[:body]`.
-        #
-        # @param [Hash] env The response environment
-        # @private
+      class JSONParser < Faraday::Response::Middleware
         def on_complete(env)
-          env[:body] = '{}' if [204, 405].include?(env[:status])
-          env[:body] = case env[:status]
+          response = if env[:body].nil? || env[:body].empty?
+            {}
+          else
+            begin
+              MultiJson.load(env[:body], :symbolize_keys => true)
+            rescue MultiJson::LoadError
+              raise Userbin::ApiError, 'Invalid response from Userbin API'
+            end
+          end
+
+          case env[:status]
+          when 201..299
+            # OK
+          when 400
+            raise Userbin::BadRequestError, response[:message]
+          when 401
+            raise Userbin::UnauthorizedError, response[:message]
           when 403
-            raise Userbin::ForbiddenError.new(
-              MultiJson.decode(env[:body])['message'])
+            raise Userbin::ForbiddenError, response[:message]
           when 404
-            raise Userbin::NotFoundError.new(
-              MultiJson.decode(env[:body])['message'])
+            raise Userbin::NotFoundError, response[:message]
           when 419
-            raise Userbin::UserUnauthorizedError.new(
-              MultiJson.decode(env[:body])['message'])
-          when 400..599
-            begin
-              message = MultiJson.decode(env[:body])['message']
-              raise Userbin::Error.new(message)
-            rescue MultiJson::ParseError
-              raise Userbin::ApiError.new
-            end
+            raise Userbin::UserUnauthorizedError, response[:message]
+          when 422
+            raise Userbin::InvalidParametersError, response[:message]
           else
-            parse(env[:body])
+            raise Userbin::ApiError, response[:message]
           end
+
+          env[:body] = {
+            data: response
+          }
         end
       end
+
     end
 
   end

data/lib/userbin/session_token.rb

@@ -25,7 +25,7 @@ module Userbin
     end
 
     def challenge_type
-      @jwt.payload['chg']['typ'] if has_challenge?
+      @jwt.payload['chg']['typ'].to_sym if has_challenge?
     end
   end
 end

data/lib/userbin/utils.rb

@@ -9,6 +9,7 @@ module Userbin
 
       Her::API.setup url: api_endpoint do |c|
         c.use Userbin::Request::Middleware::BasicAuth, api_secret
+        c.use Userbin::Request::Middleware::RequestErrorHandler
         c.use Userbin::Request::Middleware::EnvironmentHeaders
         c.use Userbin::Request::Middleware::ContextHeaders
         c.use Userbin::Request::Middleware::SessionToken

data/lib/userbin/version.rb

@@ -1,3 +1,3 @@
 module Userbin
-  VERSION = "1.1.0"
+  VERSION = "1.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: userbin
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Johan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-09 00:00:00.000000000 Z
+date: 2014-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: her