From f3dc0dd16fd4d708be5f7270f980a99e7e5efccd Mon Sep 17 00:00:00 2001 From: Michael Bleigh Date: Thu, 14 Oct 2010 16:21:08 -0500 Subject: [PATCH] Updating lots of documentation. --- README.markdown | 8 ++++---- Rakefile | 6 +++--- .../lib/omniauth/test/strategy_test_case.rb | 3 ++- .../omniauth/strategies/cas/configuration.rb | 12 +++++------- .../cas/service_ticket_validator.rb | 8 ++++---- oa-oauth/lib/omniauth/strategies/facebook.rb | 14 ++++++-------- oa-oauth/lib/omniauth/strategies/github.rb | 8 ++++++++ oa-oauth/lib/omniauth/strategies/gowalla.rb | 17 +++++++++-------- oa-oauth/lib/omniauth/strategies/oauth2.rb | 19 ++++++++++++++++++- oa-openid/lib/omniauth/openid.rb | 8 ++++---- 10 files changed, 63 insertions(+), 40 deletions(-) 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: #