omniauth 0.3.0.rc3 → 1.0.0.beta1

data/.gitignore

@@ -0,0 +1,56 @@
+!.autotest
+!.document
+!.gemtest
+!.gitignore
+!.rspec
+!.yardopts
+*.gem
+*.rbc
+*.sw[a-z]
+*.tmproj
+*.tmproject
+*.un~
+*~
+.*
+.DS_Store
+.Spotlight-V100
+.Trashes
+.\#*
+._*
+.bundle
+.config
+.directory
+.elc
+.loadpath
+.project
+.redcar
+.rvmrc
+.yardoc
+/.emacs.desktop
+/.emacs.desktop.lock
+/live
+Desktop.ini
+Gemfile.lock
+Icon?
+InstalledFiles
+Session.vim
+Thumbs.db
+\#*
+\#*\#
+_yardoc
+auto-save-list
+coverage
+dist/*
+doc
+doc/
+lib/bundler/man
+oa-live
+pkg
+pkg/*
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+tmtags
+tramp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format=progress

data/.travis.yml

@@ -0,0 +1,7 @@
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - jruby
+  - rbx
+  - rbx-2.0
+  - ree

data/.yardopts

@@ -0,0 +1,4 @@
+--markup markdown
+--markup-provider maruku
+-
+LICENSE

data/Gemfile

@@ -0,0 +1,11 @@
+source 'http://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'guard'
+  gem 'guard-rspec'
+  gem 'guard-bundler'
+  gem 'growl'
+  gem 'rb-fsevent'
+end

data/Guardfile

@@ -0,0 +1,10 @@
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec/" }
+end
+
+guard 'bundler' do
+  watch('Gemfile')
+  watch(/^.+\.gemspec/)
+end

data/{LICENSE.md → LICENSE}

@@ -1,4 +1,4 @@
-Copyright (c) 2010-2011 Michael Bleigh, Erik Michaels-Ober, and Intridea, Inc.
+Copyright (c) 2010-2011 Michael Bleigh and Intridea, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,155 +1,139 @@
 # OmniAuth: Standardized Multi-Provider Authentication
-OmniAuth is a new Rack-based authentication system for multi-provider external
-authentcation. OmniAuth is built from the ground up on the philosophy that
-**authentication is not the same as identity**, and is based on two
-observations:
-
-1. The traditional 'sign up using a login and password' model is becoming the
-   exception, not the rule. Modern web applications offer external
-   authentication via OpenID, Facebook, and/or OAuth.
-2. The interconnectable web is no longer a dream, it is a necessity. It is not
-   unreasonable to expect that one application may need to be able to connect
-   to one, three, or twelve other services. Modern authentication systems
-   should allow a user's identity to be associated with many authentications.
-
-## <a name="installation">Installation</a>
-To install OmniAuth, simply install the gem:
-
-    gem install omniauth
-
-## <a name="ci">Continuous Integration</a>
-[![Build Status](https://travis-ci.org/intridea/omniauth.png)](http://travis-ci.org/intridea/omniauth)
-
-## <a name="providers">Providers</a>
-OmniAuth currently supports the following external providers:
-
-* via OAuth (OAuth 1.0, OAuth 2, and xAuth)
-  * 37signals ID (credit: [mbleigh](https://github.com/mbleigh))
-  * AngelList (credit: [joshuaxls](https://github.com/joshuaxls))
-  * Bit.ly (credit: [philnash](https://github.com/philnash))
-  * Blogger (credit: [dsueiro-backing](https://github.com/dsueiro-backing))
-  * Cobot (credit: [kamal](https://github.com/kamal))
-  * DailyMile (credit: [cdmwebs](https://github.com/cdmwebs))
-  * Doit.im (credit: [chouti](https://github.com/chouti))
-  * Dopplr (credit: [flextrip](https://github.com/flextrip))
-  * Douban (credit: [quake](https://github.com/quake))
-  * Evernote (credit: [szimek](https://github.com/szimek))
-  * Facebook (credit: [mbleigh](https://github.com/mbleigh))
-  * Foursquare (credit: [mbleigh](https://github.com/mbleigh))
-  * GitHub (credit: [mbleigh](https://github.com/mbleigh))
-  * Glitch (credit: [harrylove](https://github.com/harrylove))
-  * GoodReads (credit: [cristoffer](https://github.com/christoffer))
-  * Google Health (credit: [jaigouk](https://github.com/jaigouk))
-  * Gowalla (credit: [kvnsmth](https://github.com/kvnsmth))
-  * Hyves (credit: [mrdg](https://github.com/mrdg))
-  * Identi.ca (credit: [dcu](https://github.com/dcu))
-  * Flattr (credit: [dcu](https://github.com/dcu))
-  * Instagram (credit: [kiyoshi](https://github.com/kiyoshi))
-  * Instapaper (credit: [micpringle](https://github.com/micpringle))
-  * LastFM (credit: [tictoc](https://github.com/tictoc))
-  * LinkedIn (credit: [mbleigh](https://github.com/mbleigh))
-  * Mailchimp (via [srbiv](http://github.com/srbiv))
-  * Mailru (credit: [lexer](https://github.com/lexer))
-  * Meetup (credit [coderoshi](https://github.com/coderoshi))
-  * Miso (credit: [rickenharp](https://github.com/rickenharp))
-  * Mixi (credit: [kiyoshi](https://github.com/kiyoshi))
-  * Netflix (credit: [caged](https://github.com/caged))
-  * Orkut (credit: [andersonleite](https://github.com/andersonleite))
-  * Plurk (credit: [albb0920](http://github.com/albb0920))
-  * Qzone (credit: [quake](https://github.com/quake))
-  * Rdio (via [brandonweiss](https://github.com/brandonweiss))
-  * Renren (credit: [quake](https://github.com/quake))
-  * Salesforce (via [CloudSpokes](http://www.cloudspokes.com))
-  * SmugMug (credit: [pchilton](https://github.com/pchilton))
-  * SoundCloud (credit: [leemartin](https://github.com/leemartin))
-  * T163 (credit: [quake](https://github.com/quake))
-  * Taobao (credit: [l4u](https://github.com/l4u))
-  * TeamBox (credit [jrom](https://github.com/jrom))
-  * Tqq (credit: [quake](https://github.com/quake))
-  * TradeMe (credit: [pchilton](https://github.com/pchilton))
-  * TripIt (credit: [flextrip](https://github.com/flextrip))
-  * Tsina (credit: [quake](https://github.com/quake))
-  * Tsohu (credit: [quake](https://github.com/quake))
-  * Tumblr (credit: [jamiew](https://github.com/jamiew))
-  * Twitter (credit: [mbleigh](https://github.com/mbleigh))
-  * Viadeo (credit: [guillaug](https://github.com/guillaug))
-  * Vimeo (credit: [jamiew](https://github.com/jamiew))
-  * Vkontakte (credit: [german](https://github.com/german))
-  * WePay (credit: [ryanwood](https://github.com/ryanwood))
-  * Yahoo (credit: [mpd](https://github.com/mpd))
-  * Yammer (credit: [kltcalamay](https://github.com/kltcalamay))
-  * YouTube (credit: [jamiew](https://github.com/jamiew))
-* CAS (Central Authentication Service) (credit: [jamesarosen](https://github.com/jamesarosen))
-* Flickr (credit: [pchilton](https://github.com/pchilton))
-* Google Apps (via OpenID) (credit: [mbleigh](https://github.com/mbleigh))
-* Google OpenID+OAuth (via Hybrid Protocol) (credit: [boyvanamstel](https://github.com/boyvanamstel))
-* LDAP (credit: [pyu10055](https://github.com/pyu10055))
-* OpenID (credit: [mbleigh](https://github.com/mbleigh))
-* Yupoo (credit: [chouti](https://github.com/chouti))
-
-## <a name="usage">Usage</a>
-OmniAuth is a collection of Rack middleware. To use a single strategy, you simply need to add the middleware:
-
-    require 'oa-oauth'
-    use OmniAuth::Strategies::Twitter, 'CONSUMER_KEY', 'CONSUMER_SECRET'
-
-Now to initiate authentication you merely need to redirect the user to `/auth/twitter` via a link or other means. Once the user has authenticated to Twitter, they will be redirected to `/auth/twitter/callback`. You should build an endpoint that handles this URL, at which point you will have access to the authentication information through the `omniauth.auth` parameter of the Rack environment. For example, in Sinatra you would do something like this:
-
-    get '/auth/twitter/callback' do
-      auth_hash = request.env['omniauth.auth']
+
+**NOTICE:** This documentation and code is for OmniAuth 1.0 in which
+each provider will become its own separate gem. If you're looking for
+the current released version, please visit [OmniAuth 0.3 Stable
+Branch](https://github.com/intridea/omniauth/tree/0-3-stable).
+
+## An Introduction
+
+OmniAuth is a libary that standardizes multi-provider authentication for
+web applications. It was created to be powerful, flexible, and do as
+little as possible. Any developer can create **strategies** for OmniAuth
+that can authenticate users via disparate systems. OmniAuth strategies
+have been created for everything from Facebook to LDAP.
+
+In order to use OmniAuth in your applications, you will need to leverage
+one or more strategies. These strategies are generally released
+individually as RubyGems, and you can see a [community maintained list](https://github.com/intridea/omniauth/wiki/List-of-Strategies) 
+on the wiki for this project.
+
+One strategy, called `Developer`, is included with OmniAuth and provides
+a completely unsecure, non-production-usable strategy that directly
+prompts a user for authentication information and then passes it
+straight through. You can use it as a placeholder when you start
+development and easily swap in other strategies later.
+
+## Getting Started
+
+Each OmniAuth strategy is a Rack Middleware. That means that you can use
+it the same way that you use any other Rack middleware. For example, to
+use the built-in Developer strategy in a Sinatra application I might do
+this:
+
+    require 'sinatra'
+    require 'omniauth'
+
+    class MyApplication < Sinatra::Base
+      use Rack::Session
+      use OmniAuth::Strategies::Developer
+    end
+
+Because OmniAuth is built for *multi-provider* authentication, I may
+want to leave room to run multiple strategies. For this, the built-in
+`OmniAuth::Builder` class gives you an easy way to specify multiple
+strategies. Note that there is **no difference** between the following
+code and using each strategy individually as middleware. This is an
+example that you might put into a Rails initializer at
+`config/initializers/omniauth.rb`:
+
+    Rails.application.config.middleware.use OmniAuth::Builder do
+      provider :developer unless Rails.env.production?
+      provider :twitter, ENV['TWITTER_KEY'], ENV['TWITTER_SECRET']
+    end
+
+You should look to the documentation for each provider you use for
+specific initialization requirements.
+
+## Integrating OmniAuth Into Your Application
+
+OmniAuth is an extremely low-touch library. It is designed to be a
+black box that you can send your application's users into when you need
+authentication and then get information back. OmniAuth was intentionally
+built not to automatically associate with a User model or make
+assumptions about how many authentication methods you might want to use
+or what you might want to do with the data once a user has
+authenticated. This makes OmniAuth incredibly flexible. To use OmniAuth,
+you need only to redirect users to `/auth/:provider`, where `:provider`
+is the name of the strategy (for example, `developer` or `twitter`).
+From there, OmniAuth will take over and take the user through the
+necessary steps to authenticate them with the chosen strategy.
+
+Once the user has authenticated, what do you do next? OmniAuth simply
+sets a special hash called the Authentication Hash on the Rack
+environment of a request to `/auth/:provider/callback`. This hash
+contains as much information about the user as OmniAuth was able to
+glean from the utilized strategy. You should set up an endpoint in your
+application that matches to the callback URL and then performs whatever
+steps are necessary for your application. For example, in a Rails app I
+would add a line in my `routes.rb` file like this:
+
+    match '/auth/:provider/callback', to: 'sessions#create'
+
+And I might then have a `SessionsController` with code that looks
+something like this:
+
+    class SessionsController < ApplicationController
+      def create
+        @user = User.find_or_create_from_auth_hash(auth_hash)
+        self.current_user = @user
+        redirect_to '/'
+      end
+
+      protected
+
+      def auth_hash
+        request.env['omniauth.auth']
+      end
     end
 
-The hash in question will look something like this:
-
-    {
-      'uid' => '12356',
-      'provider' => 'twitter',
-      'user_info' => {
-        'name' => 'User Name',
-        'nickname' => 'username',
-        # ...
-      }
-    }
-
-The `user_info` hash will automatically be populated with as much information about the user as OmniAuth was able to pull from the given API or authentication provider.
-
-## <a name="resources">Resources</a>
-The best place to find more information is the [OmniAuth Wiki](https://github.com/intridea/omniauth/wiki). Some specific information you might be interested in:
-
-* [CI Build Status](http://travis-ci.org/intridea/omniauth)
-* [Roadmap](https://github.com/intridea/omniauth/wiki/Roadmap)
-* [Changelog](https://github.com/intridea/omniauth/wiki/Changelog)
-* [Report Issues](https://github.com/intridea/omniauth/issues)
-* [Mailing List](http://groups.google.com/group/omniauth)
-
-## <a name="core">Core Team</a>
-* **Michael Bleigh** ([mbleigh](https://github.com/mbleigh))
-* **Erik Michaels-Ober** ([sferik](https://github.com/sferik))
-
-## <a name="rubies">Supported Rubies</a>
-This library aims to support and is [tested
-against](http://travis-ci.org/intridea/omniauth) the following Ruby
-implementations:
-
-* Ruby 1.8.7
-* Ruby 1.9.2
-* [JRuby](http://www.jruby.org/)
-* [Rubinius](http://rubini.us/)
-* [Ruby Enterprise Edition](http://www.rubyenterpriseedition.com/)
-
-If something doesn't work on one of these interpreters, it should be considered
-a bug.
-
-This library may inadvertently work (or seem to work) on other Ruby
-implementations, however support will only be provided for the versions listed
-above.
-
-If you would like this library to support another Ruby version, you may
-volunteer to be a maintainer. Being a maintainer entails making sure all tests
-run and pass on that implementation. When something breaks on your
-implementation, you will be personally responsible for providing patches in a
-timely fashion. If critical issues for a particular implementation exist at the
-time of a major release, support for that Ruby version may be dropped.
-
-## <a name="license">License</a>
-OmniAuth is released under the MIT License.
+The `omniauth.auth` key in the environment hash gives me my
+Authentication Hash which will contain information about the just
+authenticated user including a unique id, the strategy they just used
+for authentication, and personal details such as name and email address
+as available. For an in-depth description of what the authentication
+hash might contain, see the [Auth Hash Schema wiki page](https://github.com/intridea/omniauth/wiki/Auth-Hash-Schema).
+
+Note that OmniAuth does not perform any actions beyond setting some
+environment information on the callback request. It is entirely up to
+you how you want to implement the particulars of your application's
+authentication flow.
+
+## Resources
+
+The [OmniAuth Wiki](https://github.com/intridea/omniauth/wiki) has
+actively maintained in-depth documentation for OmniAuth. It should be
+your first stop if you are wondering about a more in-depth look at
+OmniAuth, how it works, and how to use it.
+
+## License
+
+Copyright (c) 2011 Intridea, Inc.
+
+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/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec
+task :test => :spec

data/lib/omniauth/auth_hash.rb

@@ -0,0 +1,51 @@
+require 'hashie/mash'
+
+module OmniAuth
+  # The AuthHash is a normalized schema returned by all OmniAuth
+  # strategies. It maps as much user information as the provider
+  # is able to provide into the InfoHash (stored as the `'info'`
+  # key).
+  class AuthHash < Hashie::Mash
+    def self.subkey_class; Hashie::Mash end
+
+    # Tells you if this is considered to be a valid
+    # OmniAuth AuthHash. The requirements for that
+    # are that it has a provider name, a uid, and a
+    # valid info hash. See InfoHash#valid? for
+    # more details there.
+    def valid?
+      uid? && provider? && info? && info.valid?
+    end
+
+    def regular_writer(key, value)
+      if key.to_s == 'info' && !value.is_a?(InfoHash)
+        value = InfoHash.new(value)
+      end
+      super
+    end
+
+    class InfoHash < Hashie::Mash
+      def self.subkey_class; Hashie::Mash end
+
+      def name
+        return self[:name] if self[:name]
+        return "#{first_name} #{last_name}".strip if first_name? || last_name?
+        return nickname if nickname?
+        return email if email?
+        nil
+      end
+
+      def name?; !!name end
+
+      def valid?
+        name?
+      end
+
+      def to_hash
+        hash = super
+        hash['name'] ||= name
+        hash
+      end
+    end
+  end
+end

data/lib/omniauth/builder.rb

@@ -0,0 +1,33 @@
+require 'omniauth'
+
+module OmniAuth
+  class Builder < ::Rack::Builder
+    def initialize(app, &block)
+      @app = app
+      super(&block)
+    end
+
+    def on_failure(&block)
+      OmniAuth.config.on_failure = block
+    end
+
+    def configure(&block)
+      OmniAuth.configure(&block)
+    end
+
+    def provider(klass, *args, &block)
+      if klass.is_a?(Class)
+        middleware = klass
+      else
+        middleware = OmniAuth::Strategies.const_get("#{OmniAuth::Utils.camelize(klass.to_s)}")
+      end
+
+      use middleware, *args, &block
+    end
+
+    def call(env)
+      @ins << @app unless @ins.include?(@app)
+      to_app.call(env)
+    end
+  end
+end