registrar 0.0.6.alpha → 0.0.7.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f158247d28c1d8ffca5dee9112ff36823492c3a4
-  data.tar.gz: cafdb99ac046bdfff54e1d2ca0b361d580e1763b
+  metadata.gz: e0846eb286e5dde2da78b35d401a5b12b799752e
+  data.tar.gz: a4f0585126ca74ef7691b024b343a71cacca09a0
 SHA512:
-  metadata.gz: 491145017a0c347b688c3422424c1e43600b3c4ff7a8c49397c9de654f8f9370897b583d7aabf3739efef9fdf9b60244767348db8237da7129d97355002af116
-  data.tar.gz: 055012c4c8af534797078740fc75ab109c267118d894d7affc0b10d42d826d19e8ecf086977e1976fe8e9f88df3ae2d6e96248064a66aa44359ed9215830f7d3
+  metadata.gz: d0caf9d2c2ddd141625bb46ab37cba7c185f03a141a81148bd2da9e38ac209cc640f3ecef331e7373373a16e84b13b5da26f487378d15febd3997d8c7d7af6f1
+  data.tar.gz: 65bd17e37f1accc74d8b81c3f3e146e5cda6726e045646a68fb0097593baadec87fe1be011416f94ad39922ada4fc7a4ff70a7cb28acbe5641412c918b2db770

data/README.md

@@ -4,7 +4,7 @@
 [gem-badge]: https://img.shields.io/gem/v/registrar.svg
 [rack-playground]: https://github.com/JanOwiesniak/rack-playground/blob/master/lib/app_builder.rb
 
-# Registrar
+# Registrar: Standardized Multi-Provider Registration
 
 [![Gem Version][gem-badge]][gem]
 
@@ -12,49 +12,225 @@
 [Source][github] |
 [Documentation][doc]
 
-# Description
+## Introduction
 
-Registrar standardizes Authentication Responses through Rack Middleware and works well with common authentication mechanisms like OmniAuth.
+Registrar standardizes the authentication process through [Rack Middleware](https://github.com/rack/rack#available-middleware) and works well with common authentication mechanisms like [OmniAuth](https://github.com/intridea/omniauth).
 
-## Installation
+## Description
 
-Add this line to your application's Gemfile:
+You can think of Registrar as a thin wrapper around your sign up / sign in process.
+
+Registrar already has [build in support](https://github.com/JanOwiesniak/registrar/blob/master/lib/registrar/auth_builder/omni_auth.rb) for the [OmniAuth Auth Hash Schema](https://github.com/intridea/omniauth/wiki/Auth-Hash-Schema).
+
+If you want to use a different authentication mechanism feel free to implement your own [AuthBuilder](https://github.com/JanOwiesniak/registrar/wiki/AuthBuilder).
+
+## Getting Started
+
+Let us start with a short example.
+
+I'm using a [fork](https://github.com/JanOwiesniak/omniauth-facebook-access-token) (see here why i use a [fork](https://github.com/JanOwiesniak/omniauth-facebook-access-token/commit/6df0d75d5b9a3c866eea63d2495da0376091cbbe)) of the [omniauth-facebook-access-token](https://github.com/JanOwiesniak/omniauth-facebook-access-token) OmniAuth strategy to authenticate my user.
+
+Add `registrar` and the authenticaton mechanism you want to use to your `Gemfile`
 
 ```ruby
 gem 'registrar'
+gem 'omniauth-facebook-access-token' # we are just using one OmniAuth strategy here
+```
+
+Add the authentication mechanism of your choice
+
+```ruby
+require 'omniauth-facebook-access-token'
+
+app = Rack::Builder.app do
+  # Store authenticated user in env['omniauth.auth']
+  use OmniAuth::Builder do
+    provider omniauth-facebook-access-token
+  end
+
+  run lambda { |env| [200, {'Content-Type' => 'text/plain'}, ['OK']] }
+end
+
+run app
+```
+
+Add a appropriate AuthBuilder to your Middleware Stack to transform the previous authentication result into registrar schema.
+
+```ruby
+require 'registrar'
+require 'omniauth-facebook-access-token'
+
+app = Rack::Builder.app do
+  # Store authenticated user in env['omniauth.auth']
+  use OmniAuth::Builder do
+    provider omniauth-facebook-access-token
+  end
+
+  # Transform the OmniAuth Schema env['omniauth.auth'] into the Registrar Schema env['registrar.auth']
+  use Registrar::AuthBuilder::OmniAuth
+
+  run lambda { |env| [200, {'Content-Type' => 'text/plain'}, ['OK']] }
+end
+
+run app
 ```
 
-And then execute:
+Go to the [Facebook Graph API Explorer](https://developers.facebook.com/tools/explorer/), generate an access token and copy it to your clipboard.
+
+Start the application, visit localhost:port/auth/facebook_access_token and paste the access token from your clipboard.
+Click the submit button.
+
+`env['omniauth.auth']` returns the schema OmniAuth builds for you 
+
+```bash
+!ruby/hash:OmniAuth::AuthHash
+  provider: facebook
+  uid: '100000100277322'
+  info: !ruby/hash:OmniAuth::AuthHash::InfoHash
+    email: janowiesniak@gmx.de
+    name: Jan Ow
+    first_name: Jan
+    last_name: Ow
+    image: http://graph.facebook.com/100000100277322/picture
+    urls: !ruby/hash:OmniAuth::AuthHash
+      Facebook: http://www.facebook.com/100000100277322
+    location: Bochum, Germany
+    verified: true
+  credentials: !ruby/hash:OmniAuth::AuthHash
+    token: CAACEdEose0cBABZBEayxJNmeCRdvrwT6RbiEbtYUyAZCY24E5xxCoPQJ0oCVR8XFsUEtTpnMjwrRMwvjliQe2xDRM2c76ONriaNQaMwuAKH1YjQki9lK8evIkN18TqPopB1blbeRuOIkes2l4JQ3Ga7HL9vHXHqhAjcbuZCHKhtOJMulZAN1wfWMlOxF7bBZCW0TdzJz654CW7ErAsIPj
+    expires: false
+  extra: !ruby/hash:OmniAuth::AuthHash
+    raw_info: !ruby/hash:OmniAuth::AuthHash
+      id: '100000100277322'
+      email: janowiesniak@gmx.de
+      first_name: Jan
+      gender: male
+      last_name: Ow
+      link: http://www.facebook.com/100000100277322
+      location: !ruby/hash:OmniAuth::AuthHash
+        id: '106544749381682'
+        name: Bochum, Germany
+      locale: en_US
+      name: Jan Ow
+      timezone: 1
+      updated_time: '2015-01-10T11:52:30+0000'
+      verified: true
+```
+
+`env['registrar.auth']` returns the schema which registrar builds (in this case Registrar::AuthBuilder::OmniAuth)
+
+```bash
+  provider:
+    name: facebook
+    uid: '100000100277322'
+    access_token: CAACEdEose0cBABZBEayxJNmeCRdvrwT6RbiEbtYUyAZCY24E5xxCoPQJ0oCVR8XFsUEtTpnMjwrRMwvjliQe2xDRM2c76ONriaNQaMwuAKH1YjQki9lK8evIkN18TqPopB1blbeRuOIkes2l4JQ3Ga7HL9vHXHqhAjcbuZCHKhtOJMulZAN1wfWMlOxF7bBZCW0TdzJz654CW7ErAsIPj
+  profile:
+    name: Jan Ow
+    email: janowiesniak@gmx.de
+    location: Bochum, Germany
+    image: http://graph.facebook.com/100000100277322/picture
+  trace:
+    ip: 127.0.0.1
+    user_agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko)
+      Chrome/40.0.2214.91 Safari/537.36
+    timestamp: '1427800292'
+```
 
-    $ bundle
+Currently, the AuthBuilder just transforms the Hash into a different structure.
 
-Or install it yourself as:
+To do something with the authenticated user (e.g. sign up or sign in), use the profile builder.
 
-    $ gem install registrar
+Open up you Middewarestack again.
 
-## Usage
+```ruby
+require 'registrar'
+require 'omniauth-facebook-access-token'
 
-Click [here][rack-playground] to see how to use the different components.
+app = Rack::Builder.app do
+  # Store authenticated user in env['omniauth.auth']
+  use OmniAuth::Builder do
+    provider omniauth-facebook-access-token
+  end
 
-## Short summary of the components
+  # Transform the OmniAuth Schema env['omniauth.auth'] into the Registrar Schema env['registrar.auth']
+  use Registrar::AuthBuilder::OmniAuth
 
-### Gatekeeper
+  # Handle Registrar Schema env['registrar.auth'] and store processed result into env['registrar.profile']
+  use Registrar::ProfileBuilder, Proc.new {|schema| #find_or_create_profile_in_persistence }
 
-It normalizes the interface.
+  run lambda { |env| [200, {'Content-Type' => 'text/plain'}, ['OK']] }
+end
 
-## Adapter
+run app
+```
 
-It normalizes the response.
+In this case I passed the Registrar Schema to an application related service called ProfileRegister which returned me a application specific Profile.
+
+This profile is stored in `env['registrar.profile']`
+
+```bash
+!ruby/object:ProfileRegister::Services::ProfileBoundary::Profile
+  o: 
+  t:
+    :profile_uid: '1'
+    :provider: facebook
+    :access_token: a39147c2f57f3797f58a
+    :external_uid: '100000100277322'
+    :display_name: Jan Ow
+    :country_code: 
+    :avatar: http://graph.facebook.com/100000100277322/picture
+    :email: janowiesniak@gmx.de
+    :terms_accepted: false
+    :registration_platform: 
+    :gender: 
+    :language: 
+    :birthday: 
+    :fresh: true
+    :last_login: &1 !ruby/object:ProfileRegister::Services::ProfileBoundary::LastLogin
+      o: 
+      t:
+        :time: 2015-03-31 11:11:32.000000000 Z
+        :address: 127.0.0.1
+        :user_agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like
+          Gecko) Chrome/40.0.2214.91 Safari/537.36
+```
 
-## ProfileFactory
+If your application supports the concept of a session your could store env['registrar.profile'] in your session to log the user in.
 
-It passes the normalized response to a profile factory and stores a hash version
-of the returned object in the env.
+```ruby
+if env['registrar.profile']
+  @session['current_profile'] = env['registrar.profile']
+end
+```
+
+If you decide to do this you could also add some helper methods.
+
+```ruby
+def current_profile
+  @session['current_profile']
+end
+
+def logged_in?
+  !!current_profile
+end
+
+def logged_out?
+  !logged_in?
+end
+```
+
+If you are using `Rails` you should probably check out [registrar-rails](https://github.com/JanOwiesniak/registrar-rails) which gives you a small interface to configure your middleware as well as some helper methods as suggested above.
 
 ## Contributing
 
+0. Check out the [Wiki](https://github.com/JanOwiesniak/registrar/wiki)
 1. Fork it ( https://github.com/JanOwiesniak/registrar/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
+
+## Related Projects
+
+* https://github.com/JanOwiesniak/registrar-rails
+* https://github.com/JanOwiesniak/omniauth-registrar

data/lib/registrar/mapper/params.rb

@@ -23,23 +23,27 @@ module Registrar
         end
 
         def build_registrar_params
-          @mapping.each do |from, to|
-            namespace_from, attr_from = from.split('#')
-            value = request.params[namespace_from]
+          begin
+            @mapping.each do |from, to|
+              namespace_from, attr_from = from.split('#')
+              value = request.params[namespace_from]
 
-            if value.class != String && attr_from
-              value = request.params[namespace_from][attr_from]
-            end
+              if value.class != String && attr_from
+                value = request.params[namespace_from][attr_from]
+              end
 
-            namespace_to, attr_to = to.split('#')
+              namespace_to, attr_to = to.split('#')
 
-            if namespace_to
-              if attr_to
-                params[namespace_to][attr_to] = value
-              else
-                params[namespace_to] = value
+              if namespace_to
+                if attr_to
+                  params[namespace_to][attr_to] = value
+                else
+                  params[namespace_to] = value
+                end
               end
             end
+          rescue NoMethodError
+            return
           end
         end
 

data/lib/registrar/version.rb

@@ -1,3 +1,3 @@
 module Registrar
-  VERSION = "0.0.6.alpha"
+  VERSION = "0.0.7.alpha"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: registrar
 version: !ruby/object:Gem::Version
-  version: 0.0.6.alpha
+  version: 0.0.7.alpha
 platform: ruby
 authors:
 - Jan Owiesniak
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-31 00:00:00.000000000 Z
+date: 2015-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: omniauth