browserid-rails 0.4.0

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Greg Look
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,141 @@
+# BrowserID::Rails
+
+This gem provides a simple authentication structure to a Rails application
+based on Mozilla's BrowserID protocol and Persona service. Users are uniquely
+authenticated by email address using public-key cryptography. The advantage of
+this is that the rails application does not need to worry about storing or
+securing user passwords.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'browserid-rails'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install browserid-rails
+
+## Usage
+
+To use this gem once it is installed, it must be integrated into your Rails
+application. The following sections cover the gem configuration, controller
+integration, and view integration.
+
+### Configuration
+
+There are several configuration options available. There are a number of default
+assumptions about the application, which may be overridden as needed.
+Configuration settings are properties of `config.browserid`.
+
+* `user_model` - The name of the ActiveModel class for application users.
+  The default is `"User"`.
+* `email_field` - The name of the attribute on the user model which contains
+  the user's email. The default is `"email"`.
+* `session_variable` - The location the authenticated email is stored in the
+  client's session. The default is `:browserid_email`.
+* `verifier` - The type of verifier to use to authenticate client BrowserID
+  assertions. The default is `:persona`, which sends the request to Mozilla's
+  Persona verification service. In the future, `:local` will enable local
+  verification code. Alternately, this configuration option may be set to any
+  class which responds to `#verify(assertion)` with the verified email and
+  identity provider on success and raises an error on failure.
+* `audience` - The BrowserID audience to authenticate to. This should consist
+  of a URI string containing the scheme (protocol), authority, and port of the
+  service (e.g., `"https://app.example.com:443"`). By default, the audience is
+  not hardcoded and the properties of the request object are used to construct
+  it dynamically. This gives greater flexibility while developing, but is also
+  a minor security risk. In production, this should be configured to a fixed
+  value.
+
+### Controller Integration
+
+The `BrowserID::Rails::Base` module makes several controller methods available
+to interact with the authentication system. To access information, use one of:
+
+* `browserid_email` - Returns the BrowserID-authenticated email address, if any.
+* `current_user` - Retrieves the model for the currently authenticated user, if
+  there is an authenticated email and a matching user exists.
+* `authenticated?` - Returns true if there is a current user.
+
+These methods are also available in views as helpers.
+
+To control authentication, the app should have a `SessionsController` which
+connects the in-browser authentication code to the server. The gem provides
+these methods:
+
+* `login_browserid` - Sets the given string as the authenticated email.
+* `logout_browserid` - Clears the current authenticated email.
+* `verify_browserid` - Uses the configured verifier to confirm a BrowserID
+  assertion is correct for the service audience.
+* `respond_to_browserid` - Wraps `verify_browserid` in logging and error
+  handling logic and generates controller responses to a `POST` assertion.
+
+Implementing the required methods for `SessionsController` is straightforward:
+
+    # POST /login
+    def create
+      respond_to_browserid
+    end
+
+    # POST /logout
+    def destroy
+      logout_browserid
+      head :ok
+    end
+
+TODO: write generator to create routes and session controller
+
+### Layout Integration
+
+The BrowserID javascript library needs to be loaded on your application pages.
+There are two steps to accomplish this:
+
+First, the coffeescript asset file needs to be loaded. In the
+`app/assets/javascripts/application.js` manifest, add the following line:
+
+    //= require browserid
+
+Second, the scripts need to be setup in your pages' `<head>` section. The
+`setup_browserid` helper method takes care of this for you and gives a couple
+of ways to control its behavior:
+
+    <!-- Perform basic BrowserID setup in the head section -->
+    <%= setup_browserid %>
+
+    <!-- Setup BrowserID with alert debugging -->
+    <%= setup_browserid debug: true %>
+
+    <!-- Setup BrowserID with a custom handler -->
+    <%= setup_browserid do %>
+      browserid.onLogin = function (data, status, xhr) {
+        // ...
+      }
+    <% end %>
+
+Once that's accomplished, the app is ready to use BrowserID for authentication.
+To add login and logout links to the site, use the `login_link` and
+`logout_link` helpers. These accept optional link text and targets as parameters:
+
+    <%= login_link "Login with Persona" %>
+
+    <%= login_link "Login", auth_path %>
+
+If the path is not provided, the link helpers will use `login_path` and
+`logout_path` if they are available, otherwise the link targets will be `#`.
+The coffeescript assets add on-click handlers to the links which trigger the
+Persona code to request new assertions or destroy existing ones.
+
+TODO: include Persona branding assets
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/app/assets/javascripts/browserid.js.coffee

@@ -0,0 +1,84 @@
+# BrowserID javascript functions
+
+@browserid = browserid =
+
+  ### PROPERTIES ###
+
+  # Public: Path used to verify browserID authentication assertions. Assertions
+  # are POSTed to this path.
+  loginPath: '/login'
+
+  # Public: Path used to unset persisted authentication state when logging out.
+  # This should clear the currently-logged-in user email.
+  logoutPath: '/logout'
+
+  # Internal: Debugging toggle - if true, the results of logins will be alert
+  # dialogs instead of page refreshes. This is useful to set if the application
+  # starts going into a refresh loop.
+  debug: false
+
+
+
+  ### HANDLERS ###
+
+  # Public: This method is called when a user successfully authenticates. By
+  # default, it reloads the current page.
+  onLogin: (data, status, xhr) ->
+    if @debug
+      alert("Login result: #{status} #{data}")
+    else
+      window.location.reload()
+
+  # Public: This method is called when a user fails to authenticate.
+  onLoginError: (xhr, status, err) ->
+    alert("Login #{err} - #{xhr.responseText}")
+
+  # Public: This method is called when a user clears their authentication. By
+  # default, it reloads the current page.
+  onLogout: (data, status, xhr) ->
+    if @debug
+      alert("Logout result: #{status} #{data}")
+    else
+      window.location.reload()
+
+  # Public: This method is called when a user fails to clear their
+  # authentication.
+  onLogoutError: (xhr, status, err) ->
+    alert("Logout #{err} - #{xhr.responseText}")
+
+
+  ### INITIALIZATION ###
+
+  # Public: Watches the authentication state and takes action when the user
+  # logs in or logs out. This method MUST be called on every page of the
+  # application.
+  setup: (currentUser = null) ->
+    navigator.id.watch
+      loggedInUser: currentUser
+      onlogin: (assertion) =>
+        $.ajax
+          type: 'POST'
+          url: @loginPath
+          data: { assertion: assertion }
+          success: (data, status, xhr) => @onLogin(data, status, xhr)
+          error: (xhr, status, err) => @onLoginError(xhr, status, err)
+      onlogout: =>
+        $.ajax
+          type: 'POST'
+          url: @logoutPath
+          success: (data, status, xhr) => @onLogout(data, status, xhr)
+          error: (xhr, status, err) => @onLogoutError(xhr, status, err)
+
+
+
+### Behavior Binding ###
+
+jQuery ->
+  $('.browserid_login').click ->
+    navigator.id.request()
+    false
+
+jQuery ->
+  $('.browserid_logout').click ->
+    navigator.id.logout()
+    false

data/app/views/layouts/_browserid.html.erb

@@ -0,0 +1,12 @@
+<script src="https://login.persona.org/include.js"></script>
+<script type="text/javascript">
+<% if options[:login_path] %>browserid.loginPath = "<%= options[:login_path] %>";<% end %>
+<% if options[:logout_path] %>browserid.logoutPath = "<%= options[:logout_path] %>";<% end %>
+<% if options[:debug] %>browserid.debug = true;<% end %>
+<%= yield :browserid_setup %>
+<% if browserid_email %>
+browserid.setup("<%= browserid_email %>");
+<% else %>
+browserid.setup();
+<% end %>
+</script>

data/lib/browserid-rails.rb

@@ -0,0 +1,41 @@
+require 'browserid/rails/base'
+require 'browserid/rails/helpers'
+require 'browserid/rails/version'
+
+module BrowserID
+  module Rails
+    # This class defines a Rails engine which extends the base controller with
+    # the library methods. The presence of this engine also causes assets to
+    # be included when the gem is added as a dependency.
+    class Engine < ::Rails::Engine
+      config.before_configuration do
+        BrowserIDConfig = Struct.new :user_model, :email_field, :session_variable, :verifier, :audience
+
+        config.browserid = BrowserIDConfig.new
+        config.browserid.user_model = 'User'
+        config.browserid.email_field = 'email'
+        config.browserid.session_variable = :browserid_email
+        config.browserid.verifier = :persona
+        # config.browserid.audience should only be set in production
+      end
+
+      initializer "browserid-rails.extend" do |app|
+        ActionController::Base.send :include, BrowserID::Rails::Base
+        ActionView::Base.send :include, BrowserID::Rails::Helpers
+      end
+
+      config.after_initialize do
+        cfg = config.browserid
+
+        # Replace type symbol with constructed verifier.
+        if cfg.verifier == :persona
+          cfg.verifier = BrowserID::Verifier::Persona.new
+        elsif cfg.verifier == :local
+          raise "Local BrowserID verification is not supported yet" # TODO
+        elsif !cfg.verifier.respond_to?(:verify)
+          raise "Unknown BrowserID verifier type #{cfg.verifier}"
+        end
+      end
+    end
+  end
+end

data/lib/browserid/rails/base.rb

@@ -0,0 +1,130 @@
+require 'browserid/verifier/persona'
+
+module BrowserID
+  module Rails
+    # Public: Base module for inclusion into a controller. This module includes
+    # methods for dealing with BrowserID user authentication.
+    module Base
+
+      ##### INTERNAL METHODS #####
+
+      # Internal: Modifies the controller this module is included in to provide
+      # authentication-related helper methods
+      #
+      # base - The Class this module is being included in.
+      def self.included(base)
+        base.send :helper_method, :browserid_email, :current_user, :authenticated?
+      end
+
+      # Internal: Gets the application configuration for this gem.
+      #
+      # Returns the app config structure.
+      def browserid_config
+        ::Rails.application.config.browserid
+      end
+
+
+
+      ##### AUTHENTICATION METHODS #####
+
+      # Public: Sets the given email address as the currently-authenticated user.
+      # The address is saved in the client's session.
+      #
+      # email - The String email address to consider authenticated.
+      def login_browserid(email)
+        session[browserid_config.session_variable] = email
+      end
+
+      # Public: Clears the saved email address for the currently-authenticated
+      # user. It is important to note that this does not remove the BrowserID
+      # assertion in the client's browser.
+      def logout_browserid
+        session[browserid_config.session_variable] = nil
+      end
+
+      # Public: Uses the configured verifier to check that a provided assertion
+      # is correct for the site audience.
+      #
+      # Returns the verified email, identity issuer, and audience on success.
+      # Raises an error with a failure message if the client was not
+      # successfully authenticated.
+      #
+      # Examples
+      #
+      #   verify_browserid(assertion)
+      #   # => "user@example.com", "persona.mozilla.com", "https://app.example.com:443"
+      #
+      def verify_browserid(assertion)
+        audience = browserid_config.audience
+        audience ||= "%s%s:%d" % [request.protocol, request.host, request.port]
+        browserid_config.verifier.verify(assertion, audience)
+      end
+
+      # Public: Handles a POST-ed BrowserID assertion, responding appropriately
+      # to the request. If successful, this logs-in the authenticated email and
+      # returns an OK status. If unsuccessful, it returns FORBIDDEN and an
+      # error message in the response body.
+      #
+      # Returns nothing.
+      #
+      # Examples
+      #
+      #   # POST /login
+      #   def create
+      #     respond_to_browserid
+      #   end
+      #
+      def respond_to_browserid
+        if params[:assertion].blank?
+          head :bad_request
+        else
+          email, issuer, audience = verify_browserid params[:assertion]
+          logger.info "Verified BrowserID assertion for #{email} issued by #{issuer} on #{audience}"
+          login_browserid email
+          head :ok
+        end
+      rescue StandardError => e
+        logger.warn "Failed to verify BrowserID assertion: #{e.message}"
+        render status: :forbidden, text: e.message
+      end
+
+
+
+      ##### HELPER METHODS #####
+
+      # Public: Gets the email address of the currently-authenticated user.
+      #
+      # Returns the authenticated email address String.
+      def browserid_email
+        session[browserid_config.session_variable]
+      end
+
+      # Public: Retrieves the user for the authenticated email address. This
+      # method uses the `browserid.user_model` and `browserid.email_field`
+      # config settings, which default to `User` and `email`.
+      #
+      # Returns the current authenticated user, or nil if no user exists.
+      def current_user
+        if browserid_email.nil?
+          nil
+        elsif @current_user
+          @current_user
+        else
+          config = browserid_config
+          user_model = config.user_model.constantize
+          find_method = "find_by_#{config.email_field}".intern
+
+          @current_user = user_model.send find_method, browserid_email
+        end
+      end
+
+      # Public: Determines whether the current client is authenticated as a
+      # registered User.
+      #
+      # Returns true if the client is authenticated and registered.
+      def authenticated?
+        !current_user.nil?
+      end
+    end
+  end
+end

data/lib/browserid/rails/helpers.rb

@@ -0,0 +1,62 @@
+module BrowserID
+  module Rails
+    # Public: Rails view helpers for use with BrowserID code.
+    module Helpers
+      # Public: Renders a layout partial which initializes the BrowserID
+      # system. This should be called in the head of the application layout.
+      #
+      # options - Hash used to adjust the browserid asset setup (default: {}).
+      #           :login_path  - String giving the path to POST assertions to
+      #                          for verification.
+      #           :logout_path - String giving the path to POST logout
+      #                          notifications to.
+      #           :debug       - Boolean determining whether the browserid
+      #                          javascript will refresh the page or show an
+      #                          alert dialog.
+      # block   - An optional block which can be used to provide additional
+      #           content to be rendered inside the browserid setup script tag.
+      #
+      # Examples
+      #
+      #   <!-- Perform basic BrowserID setup in the head section -->
+      #   <%= setup_browserid %>
+      #
+      #   <!-- Setup BrowserID with alert debugging -->
+      #   <%= setup_browserid debug: true %>
+      #
+      #   <!-- Setup BrowserID with a custom handler -->
+      #   <%= setup_browserid do %>
+      #     browserid.onLogin = function (data, status, xhr) {
+      #       // ...
+      #     }
+      #   <% end %>
+      #
+      def setup_browserid(options={}, &block)
+        content_for :browserid_setup, capture(&block) if block_given?
+        render 'layouts/browserid', options: options
+      end
+
+      # Public: Renders a login link which will request a new authentication
+      # assertion from the BrowserID javascript code.
+      #
+      # text - String to use as link text (default: 'Login').
+      # path - String path to link to. If not provided, the `login_path` helper
+      #        will be used if it exists. Otherwise, the link will be to '#'.
+      def login_link(text="Login", path=nil)
+        target = path || respond_to?(:login_path) && login_path || '#'
+        link_to text, target, class: :browserid_login
+      end
+
+      # Public: Renders a logout link which will clear the current BrowserID
+      # authentication status.
+      #
+      # text - String to use as link text (default: 'Logout').
+      # path - String path to link to. If not provided, the `logout_path` helper
+      #        will be used if it exists. Otherwise, the link will be to '#'.
+      def logout_link(text="Logout", path=nil)
+        target = path || respond_to?(:logout_path) && logout_path || '#'
+        link_to text, target, class: :browserid_logout
+      end
+    end
+  end
+end

data/lib/browserid/rails/version.rb

@@ -0,0 +1,5 @@
+module BrowserID
+  module Rails
+    VERSION = "0.4.0"
+  end
+end

data/lib/browserid/verifier/persona.rb

@@ -0,0 +1,85 @@
+require 'json'
+require 'net/https'
+
+module BrowserID
+  module Verifier
+    # Public: This class sends the assertion to Mozilla's Persona server for
+    # verification.
+    class Persona
+      attr_accessor :server, :path
+
+      # Public: String defining the endpoint of the server to perform Persona
+      # verifications against.
+      VERIFICATION_SERVER = 'verifier.login.persona.org'
+
+      # Public: String defining the normal path to POST assertion verifications
+      # to.
+      VERIFICATION_PATH = '/verify'
+
+      # Public: Constructs a new Persona verifier.
+      #
+      # server - Domain String of the server to send assertions to for
+      #          verifications (default: VERIFICATION_SERVER).
+      # path   - Path String to POST to on the server (default:
+      #          VERIFICATION_PATH).
+      #
+      def initialize(server=VERIFICATION_SERVER, path=VERIFICATION_PATH)
+        @server = server
+        @path = path
+      end
+
+      # Public: Verifies a Persona assertion for a given audience.
+      #
+      # assertion - Persona authentication assertion.
+      # audience  - Audience String to verify assertion against. This should be
+      #             the URI of the service with scheme, authority, and port.
+      #
+      # Returns the authenticated email address String and the issuing domain
+      # if the assertion is valid.
+      # Raises an exception with a failure message if the client was not
+      # successfully authenticated.
+      #
+      # Examples
+      #
+      #   verify(assertion, "https://app.example.com:443")
+      #   # => "user@example.com", "persona.mozilla.com"
+      #
+      def verify(assertion, audience)
+        http = Net::HTTP.new(@server, 443)
+        http.use_ssl = true
+
+        verification = Net::HTTP::Post.new(@path)
+        verification.set_form_data(assertion: assertion, audience: audience)
+
+        response = http.request(verification)
+        raise "Unsuccessful response from #{@server}: #{response}" unless response.kind_of? Net::HTTPSuccess
+        authentication = JSON.parse(response.body)
+
+        # Authentication response is a JSON hash which must contain a 'status'
+        # of "okay" or "failure".
+        status = authentication['status']
+        raise "Unknown authentication status '#{status}'" unless %w{okay failure}.include? status
+
+        # An unsuccessful authentication response should contain a reason string.
+        raise "Assertion failure: #{authentication['reason']}" unless status == "okay"
+
+        # A successful response looks like the following:
+        # {
+        #   "status": "okay",
+        #   "email": "user@example.com",
+        #   "audience": "https://service.example.com:443",
+        #   "expires": 1234567890,
+        #   "issuer": "persona.mozilla.com"
+        # }
+
+        auth_audience = authentication['audience']
+        raise "Persona assertion audience '#{auth_audience}' does not match verifier audience '#{audience}'" unless auth_audience == audience
+
+        expires = authentication['expires'] && Time.at(authentication['expires'].to_i/1000.0)
+        raise "Persona assertion expired at #{expires}" if expires && expires < Time.now
+
+        [authentication['email'], authentication['issuer']]
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: browserid-rails
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+  prerelease: 
+platform: ruby
+authors:
+- Greg Look
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-12-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+description: 
+email:
+- greg@mvxcvi.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- app/views/layouts/_browserid.html.erb
+- app/assets/javascripts/browserid.js.coffee
+- lib/browserid/rails/helpers.rb
+- lib/browserid/rails/version.rb
+- lib/browserid/rails/base.rb
+- lib/browserid/verifier/persona.rb
+- lib/browserid-rails.rb
+- LICENSE
+- README.md
+homepage: https://github.com/mvxcvi/browserid-rails
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -488449078399574217
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -488449078399574217
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Rails authentication framework using Mozilla Persona and the BrowserID protocol.
+test_files: []