diff --git a/README.markdown b/README.markdown
index 4ab95fa..f3b464f 100644
--- a/README.markdown
+++ b/README.markdown
@@ -22,12 +22,12 @@ OmniAuth currently supports the following external providers:
* Foursquare
* LinkedIn
* GitHub
- * Identi.ca
- * Gowalla [credit: [kvnsmth](http://github.com/kvnsmth)]
+ * Identi.ca (credit: [dcu](http://github.com/dcu))
+ * Gowalla (credit: [kvnsmth](http://github.com/kvnsmth))
* OpenID
* Google Apps (via OpenID)
-* CAS (Central Authentication Service) [credit: [jamesarosen](http://github.com/jamesarosen)]
-* LDAP [credit: **Ping Yu**]
+* CAS (Central Authentication Service) (credit: [jamesarosen](http://github.com/jamesarosen))
+* LDAP (credit: **Ping Yu**)
## Usage
diff --git a/Rakefile b/Rakefile
index 958b3ba..836de24 100644
--- a/Rakefile
+++ b/Rakefile
@@ -136,17 +136,17 @@ end
task :default => :spec
begin
+ YARD_OPTS = ['-m', 'markdown', '-M', 'maruku']
require 'yard'
YARD::Rake::YardocTask.new(:doc) do |t|
- t.name = 'doc'
t.files = OMNIAUTH_GEMS.inject([]){|a,g| a = a + ["#{g}/lib/**/*.rb"]; a} + ['README.markdown']
- t.options = ["-o", "../omniauth.doc"]
+ t.options = YARD_OPTS
end
namespace :doc do
YARD::Rake::YardocTask.new(:pages) do |t|
t.files = OMNIAUTH_GEMS.inject([]){|a,g| a = a + ["#{g}/lib/**/*.rb"]; a} + ['README.markdown']
- t.options = ["-o", "../omniauth.doc"]
+ t.options = YARD_OPTS + ['-o', '../omniauth.doc']
end
namespace :pages do
diff --git a/oa-core/lib/omniauth/test/strategy_test_case.rb b/oa-core/lib/omniauth/test/strategy_test_case.rb
index 24429ba..48b8beb 100644
--- a/oa-core/lib/omniauth/test/strategy_test_case.rb
+++ b/oa-core/lib/omniauth/test/strategy_test_case.rb
@@ -5,8 +5,9 @@ module OmniAuth
module Test
- # Support for testing OmniAuth strategies. Usage:
+ # Support for testing OmniAuth strategies.
#
+ # @example Usage
# class MyStrategyTest < Test::Unit::TestCase
# include OmniAuth::Test::StrategyTestCase
# def strategy
diff --git a/oa-enterprise/lib/omniauth/strategies/cas/configuration.rb b/oa-enterprise/lib/omniauth/strategies/cas/configuration.rb
index 5aa2459..8414a38 100644
--- a/oa-enterprise/lib/omniauth/strategies/cas/configuration.rb
+++ b/oa-enterprise/lib/omniauth/strategies/cas/configuration.rb
@@ -11,12 +11,12 @@ module OmniAuth
# @param [Hash] params configuration options
# @option params [String, nil] :cas_server the CAS server root URL; probably something like
- # 'http://cas.mycompany.com' or 'http://cas.mycompany.com/cas'; optional.
+ # `http://cas.mycompany.com` or `http://cas.mycompany.com/cas`; optional.
# @option params [String, nil] :cas_login_url (:cas_server + '/login') the URL to which to
- # redirect for logins; options if :cas_server is specified,
+ # redirect for logins; options if `:cas_server` is specified,
# required otherwise.
# @option params [String, nil] :cas_service_validate_url (:cas_server + '/serviceValidate') the
- # URL to use for validating service tickets; optional if :cas_server is
+ # URL to use for validating service tickets; optional if `:cas_server` is
# specified, requred otherwise.
def initialize(params)
parse_params params
@@ -26,8 +26,7 @@ module OmniAuth
#
# @param [String] service the service (a.k.a. return-to) URL
#
- # @return [String] a URL like
- # "http://cas.mycompany.com/login?service=..."
+ # @return [String] a URL like `http://cas.mycompany.com/login?service=...`
def login_url(service)
append_service @login_url, service
end
@@ -37,8 +36,7 @@ module OmniAuth
# @param [String] service the service (a.k.a. return-to) URL
# @param [String] ticket the ticket to validate
#
- # @return [String] a URL like
- # "http://cas.mycompany.com/serviceValidate?service=...&ticket=..."
+ # @return [String] a URL like `http://cas.mycompany.com/serviceValidate?service=...&ticket=...`
def service_validate_url(service, ticket)
url = append_service @service_validate_url, service
url << '&ticket=' << Rack::Utils.escape(ticket)
diff --git a/oa-enterprise/lib/omniauth/strategies/cas/service_ticket_validator.rb b/oa-enterprise/lib/omniauth/strategies/cas/service_ticket_validator.rb
index 69b1326..a3fd001 100644
--- a/oa-enterprise/lib/omniauth/strategies/cas/service_ticket_validator.rb
+++ b/oa-enterprise/lib/omniauth/strategies/cas/service_ticket_validator.rb
@@ -31,7 +31,7 @@ module OmniAuth
private
- # turns an node into a Hash;
+ # turns an `` node into a Hash;
# returns nil if given nil
def parse_user_info(node)
return nil if node.nil?
@@ -45,8 +45,8 @@ module OmniAuth
end
end
- # finds an node in
- # a body if present; returns nil
+ # finds an `` node in
+ # a `` body if present; returns nil
# if the passed body is nil or if there is no such node.
def find_authentication_success(body)
return nil if body.nil? || body == ''
@@ -62,7 +62,7 @@ module OmniAuth
end
end
- # retrieves the XML from the CAS server
+ # retrieves the `` XML from the CAS server
def get_service_response_body
result = ''
http = Net::HTTP.new(@uri.host, @uri.port)
diff --git a/oa-oauth/lib/omniauth/strategies/facebook.rb b/oa-oauth/lib/omniauth/strategies/facebook.rb
index fcbb3e8..fafbcd9 100644
--- a/oa-oauth/lib/omniauth/strategies/facebook.rb
+++ b/oa-oauth/lib/omniauth/strategies/facebook.rb
@@ -3,18 +3,16 @@ require 'multi_json'
module OmniAuth
module Strategies
- #
# Authenticate to Facebook utilizing OAuth 2.0 and retrieve
# basic user information.
#
- # Usage:
- #
- # use OmniAuth::Strategies::Facebook, 'app_id', 'app_secret'
- #
- # Options:
- #
- # :scope :: Extended permissions such as email and offline_access (which are the defaults).
+ # @example Basic Usage
+ # use OmniAuth::Strategies::Facebook, 'app_id', 'app_secret'
class Facebook < OAuth2
+ # @param [Rack Application] app standard middleware application parameter
+ # @param [String] app_id the application id as [registered on Facebook](http://www.facebook.com/developers/)
+ # @param [String] app_secret the application secret as registered on Facebook
+ # @option options [String] :scope ('email,offline_access') comma-separated extended permissions such as `email` and `manage_pages`
def initialize(app, app_id, app_secret, options = {})
options[:site] = 'https://graph.facebook.com/'
super(app, :facebook, app_id, app_secret, options)
diff --git a/oa-oauth/lib/omniauth/strategies/github.rb b/oa-oauth/lib/omniauth/strategies/github.rb
index a20f79c..e2d0d8e 100644
--- a/oa-oauth/lib/omniauth/strategies/github.rb
+++ b/oa-oauth/lib/omniauth/strategies/github.rb
@@ -3,7 +3,13 @@ require 'multi_json'
module OmniAuth
module Strategies
+ # OAuth 2.0 based authentication with GitHub. In order to
+ # sign up for an application, you need to [register an application](http://github.com/account/applications/new)
+ # and provide the proper credentials to this middleware.
class GitHub < OAuth2
+ # @param [Rack Application] app standard middleware application argument
+ # @param [String] app_id the application ID for your client
+ # @param [String] app_secret the application secret
def initialize(app, app_id, app_secret, options = {})
options[:site] = 'https://github.com/'
options[:authorize_path] = '/login/oauth/authorize'
@@ -11,6 +17,8 @@ module OmniAuth
super(app, :github, app_id, app_secret, options)
end
+ protected
+
def user_data
@data ||= MultiJson.decode(@access_token.get('/api/v2/json/user/show'))['user']
end
diff --git a/oa-oauth/lib/omniauth/strategies/gowalla.rb b/oa-oauth/lib/omniauth/strategies/gowalla.rb
index fb27e31..a8f3a6d 100644
--- a/oa-oauth/lib/omniauth/strategies/gowalla.rb
+++ b/oa-oauth/lib/omniauth/strategies/gowalla.rb
@@ -7,14 +7,13 @@ module OmniAuth
# Authenticate to Gowalla utilizing OAuth 2.0 and retrieve
# basic user information.
#
- # Usage:
- #
- # use OmniAuth::Strategies::Gowalla, 'API Key', 'Secret Key'
- #
- # Options:
- #
- # :scope :: Extended permissions such as email and offline_access (which are the defaults).
+ # @example Basic Usage
+ # use OmniAuth::Strategies::Gowalla, 'API Key', 'Secret Key'
class Gowalla < OAuth2
+ # @param [Rack Application] app standard middleware application parameter
+ # @param [String] api_key the application id as [registered on Gowalla](http://gowalla.com/api/keys)
+ # @param [String] secret_key the application secret as [registered on Gowalla](http://gowalla.com/api/keys)
+ # @option options ['read','read-write'] :scope ('read') the scope of your authorization request; must be `read` or `read-write`
def initialize(app, api_key, secret_key, options = {})
options[:site] = 'https://api.gowalla.com/api/oauth'
options[:authorize_url] = 'https://gowalla.com/api/oauth/new'
@@ -22,12 +21,14 @@ module OmniAuth
super(app, :gowalla, api_key, secret_key, options)
end
+ protected
+
def user_data
@data ||= MultiJson.decode(@access_token.get("/users/me.json"))
end
def request_phase
- options[:scope] ||= "email,offline_access"
+ options[:scope] ||= "read"
super
end
diff --git a/oa-oauth/lib/omniauth/strategies/oauth2.rb b/oa-oauth/lib/omniauth/strategies/oauth2.rb
index 4b2da9d..ba79d2f 100644
--- a/oa-oauth/lib/omniauth/strategies/oauth2.rb
+++ b/oa-oauth/lib/omniauth/strategies/oauth2.rb
@@ -5,11 +5,21 @@ require 'omniauth/oauth'
module OmniAuth
module Strategies
+ # Authentication strategy for connecting with APIs constructed using
+ # the [OAuth 2.0 Specification](http://tools.ietf.org/html/draft-ietf-oauth-v2-10).
+ # You must generally register your application with the provider and
+ # utilize an application id and secret in order to authenticate using
+ # OAuth 2.0.
class OAuth2
include OmniAuth::Strategy
- attr_accessor :options, :client
+ # The options passed in to the strategy.
+ attr_accessor :options
+ # The `OAuth2::Client` for this strategy.
+ attr_accessor :client
+ # An error that is indicated in the OAuth 2.0 callback.
+ # This could be a `redirect_uri_mismatch` or other
class CallbackError < StandardError
attr_accessor :error, :error_reason, :error_uri
@@ -20,6 +30,13 @@ module OmniAuth
end
end
+ # Initialize a new OAuth 2.0 authentication provider.
+
+ # @param [Rack Application] app standard middleware application argument
+ # @param [String] name the name for this provider to be used in its URL, e.g. `/auth/name`
+ # @param [String] client_id the client/application ID of this provider
+ # @param [String] client_secret the client/application secret of this provider
+ # @param [Hash] options that will be passed through to the OAuth2::Client (see [oauth2 docs](http://rubydoc.info/gems/oauth2))
def initialize(app, name, client_id, client_secret, options = {})
super(app, name)
self.options = options
diff --git a/oa-openid/lib/omniauth/openid.rb b/oa-openid/lib/omniauth/openid.rb
index 26d0be3..515b250 100644
--- a/oa-openid/lib/omniauth/openid.rb
+++ b/oa-openid/lib/omniauth/openid.rb
@@ -4,7 +4,7 @@ module OmniAuth
# OmniAuth::OpenID provides strategies for authenticating to providers
# using the OpenID standard.
#
- # == Installation
+ # # Installation
#
# To get just OpenID functionality:
#
@@ -14,7 +14,7 @@ module OmniAuth
#
# gem install omniauth
#
- # == Stand-Alone Example
+ # # Stand-Alone Example
#
# Use the strategy as a middleware in your application:
#
@@ -28,7 +28,7 @@ module OmniAuth
#
# A list of all OpenID stores is available at http://github.com/openid/ruby-openid/tree/master/lib/openid/store/
#
- # == OmniAuth Builder
+ # # OmniAuth Builder
#
# If OpenID is one of several authentication strategies, use the OmniAuth Builder:
#
@@ -41,7 +41,7 @@ module OmniAuth
# provider :campfire
# end
#
- # == Configured Identifiers
+ # # Configured Identifiers
#
# You may pre-configure an OpenID identifier. For example, to use Google's main OpenID endpoint:
#