Updating lots of documentation.
This commit is contained in:
parent
a6e1de9ca1
commit
f3dc0dd16f
|
@ -22,12 +22,12 @@ OmniAuth currently supports the following external providers:
|
||||||
* Foursquare
|
* Foursquare
|
||||||
* LinkedIn
|
* LinkedIn
|
||||||
* GitHub
|
* GitHub
|
||||||
* Identi.ca
|
* Identi.ca (credit: [dcu](http://github.com/dcu))
|
||||||
* Gowalla [credit: [kvnsmth](http://github.com/kvnsmth)]
|
* Gowalla (credit: [kvnsmth](http://github.com/kvnsmth))
|
||||||
* OpenID
|
* OpenID
|
||||||
* Google Apps (via OpenID)
|
* Google Apps (via OpenID)
|
||||||
* CAS (Central Authentication Service) [credit: [jamesarosen](http://github.com/jamesarosen)]
|
* CAS (Central Authentication Service) (credit: [jamesarosen](http://github.com/jamesarosen))
|
||||||
* LDAP [credit: **Ping Yu**]
|
* LDAP (credit: **Ping Yu**)
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
|
|
6
Rakefile
6
Rakefile
|
@ -136,17 +136,17 @@ end
|
||||||
task :default => :spec
|
task :default => :spec
|
||||||
|
|
||||||
begin
|
begin
|
||||||
|
YARD_OPTS = ['-m', 'markdown', '-M', 'maruku']
|
||||||
require 'yard'
|
require 'yard'
|
||||||
YARD::Rake::YardocTask.new(:doc) do |t|
|
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.files = OMNIAUTH_GEMS.inject([]){|a,g| a = a + ["#{g}/lib/**/*.rb"]; a} + ['README.markdown']
|
||||||
t.options = ["-o", "../omniauth.doc"]
|
t.options = YARD_OPTS
|
||||||
end
|
end
|
||||||
|
|
||||||
namespace :doc do
|
namespace :doc do
|
||||||
YARD::Rake::YardocTask.new(:pages) do |t|
|
YARD::Rake::YardocTask.new(:pages) do |t|
|
||||||
t.files = OMNIAUTH_GEMS.inject([]){|a,g| a = a + ["#{g}/lib/**/*.rb"]; a} + ['README.markdown']
|
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
|
end
|
||||||
|
|
||||||
namespace :pages do
|
namespace :pages do
|
||||||
|
|
|
@ -5,8 +5,9 @@ module OmniAuth
|
||||||
|
|
||||||
module Test
|
module Test
|
||||||
|
|
||||||
# Support for testing OmniAuth strategies. Usage:
|
# Support for testing OmniAuth strategies.
|
||||||
#
|
#
|
||||||
|
# @example Usage
|
||||||
# class MyStrategyTest < Test::Unit::TestCase
|
# class MyStrategyTest < Test::Unit::TestCase
|
||||||
# include OmniAuth::Test::StrategyTestCase
|
# include OmniAuth::Test::StrategyTestCase
|
||||||
# def strategy
|
# def strategy
|
||||||
|
|
|
@ -11,12 +11,12 @@ module OmniAuth
|
||||||
|
|
||||||
# @param [Hash] params configuration options
|
# @param [Hash] params configuration options
|
||||||
# @option params [String, nil] :cas_server the CAS server root URL; probably something like
|
# @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
|
# @option params [String, nil] :cas_login_url (:cas_server + '/login') the URL to which to
|
||||||
# redirect for logins; options if <tt>:cas_server</tt> is specified,
|
# redirect for logins; options if `:cas_server` is specified,
|
||||||
# required otherwise.
|
# required otherwise.
|
||||||
# @option params [String, nil] :cas_service_validate_url (:cas_server + '/serviceValidate') the
|
# @option params [String, nil] :cas_service_validate_url (:cas_server + '/serviceValidate') the
|
||||||
# URL to use for validating service tickets; optional if <tt>:cas_server</tt> is
|
# URL to use for validating service tickets; optional if `:cas_server` is
|
||||||
# specified, requred otherwise.
|
# specified, requred otherwise.
|
||||||
def initialize(params)
|
def initialize(params)
|
||||||
parse_params params
|
parse_params params
|
||||||
|
@ -26,8 +26,7 @@ module OmniAuth
|
||||||
#
|
#
|
||||||
# @param [String] service the service (a.k.a. return-to) URL
|
# @param [String] service the service (a.k.a. return-to) URL
|
||||||
#
|
#
|
||||||
# @return [String] a URL like
|
# @return [String] a URL like `http://cas.mycompany.com/login?service=...`
|
||||||
# "http://cas.mycompany.com/login?service=..."
|
|
||||||
def login_url(service)
|
def login_url(service)
|
||||||
append_service @login_url, service
|
append_service @login_url, service
|
||||||
end
|
end
|
||||||
|
@ -37,8 +36,7 @@ module OmniAuth
|
||||||
# @param [String] service the service (a.k.a. return-to) URL
|
# @param [String] service the service (a.k.a. return-to) URL
|
||||||
# @param [String] ticket the ticket to validate
|
# @param [String] ticket the ticket to validate
|
||||||
#
|
#
|
||||||
# @return [String] a URL like
|
# @return [String] a URL like `http://cas.mycompany.com/serviceValidate?service=...&ticket=...`
|
||||||
# "http://cas.mycompany.com/serviceValidate?service=...&ticket=..."
|
|
||||||
def service_validate_url(service, ticket)
|
def service_validate_url(service, ticket)
|
||||||
url = append_service @service_validate_url, service
|
url = append_service @service_validate_url, service
|
||||||
url << '&ticket=' << Rack::Utils.escape(ticket)
|
url << '&ticket=' << Rack::Utils.escape(ticket)
|
||||||
|
|
|
@ -31,7 +31,7 @@ module OmniAuth
|
||||||
|
|
||||||
private
|
private
|
||||||
|
|
||||||
# turns an <cas:authenticationSuccess> node into a Hash;
|
# turns an `<cas:authenticationSuccess>` node into a Hash;
|
||||||
# returns nil if given nil
|
# returns nil if given nil
|
||||||
def parse_user_info(node)
|
def parse_user_info(node)
|
||||||
return nil if node.nil?
|
return nil if node.nil?
|
||||||
|
@ -45,8 +45,8 @@ module OmniAuth
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
# finds an <cas:authenticationSuccess> node in
|
# finds an `<cas:authenticationSuccess>` node in
|
||||||
# a <cas:serviceResponse> body if present; returns nil
|
# a `<cas:serviceResponse>` body if present; returns nil
|
||||||
# if the passed body is nil or if there is no such node.
|
# if the passed body is nil or if there is no such node.
|
||||||
def find_authentication_success(body)
|
def find_authentication_success(body)
|
||||||
return nil if body.nil? || body == ''
|
return nil if body.nil? || body == ''
|
||||||
|
@ -62,7 +62,7 @@ module OmniAuth
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
# retrieves the <cas:serviceResponse> XML from the CAS server
|
# retrieves the `<cas:serviceResponse>` XML from the CAS server
|
||||||
def get_service_response_body
|
def get_service_response_body
|
||||||
result = ''
|
result = ''
|
||||||
http = Net::HTTP.new(@uri.host, @uri.port)
|
http = Net::HTTP.new(@uri.host, @uri.port)
|
||||||
|
|
|
@ -3,18 +3,16 @@ require 'multi_json'
|
||||||
|
|
||||||
module OmniAuth
|
module OmniAuth
|
||||||
module Strategies
|
module Strategies
|
||||||
#
|
|
||||||
# Authenticate to Facebook utilizing OAuth 2.0 and retrieve
|
# Authenticate to Facebook utilizing OAuth 2.0 and retrieve
|
||||||
# basic user information.
|
# basic user information.
|
||||||
#
|
#
|
||||||
# Usage:
|
# @example Basic Usage
|
||||||
#
|
# use OmniAuth::Strategies::Facebook, 'app_id', 'app_secret'
|
||||||
# use OmniAuth::Strategies::Facebook, 'app_id', 'app_secret'
|
|
||||||
#
|
|
||||||
# Options:
|
|
||||||
#
|
|
||||||
# <tt>:scope</tt> :: Extended permissions such as <tt>email</tt> and <tt>offline_access</tt> (which are the defaults).
|
|
||||||
class Facebook < OAuth2
|
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 = {})
|
def initialize(app, app_id, app_secret, options = {})
|
||||||
options[:site] = 'https://graph.facebook.com/'
|
options[:site] = 'https://graph.facebook.com/'
|
||||||
super(app, :facebook, app_id, app_secret, options)
|
super(app, :facebook, app_id, app_secret, options)
|
||||||
|
|
|
@ -3,7 +3,13 @@ require 'multi_json'
|
||||||
|
|
||||||
module OmniAuth
|
module OmniAuth
|
||||||
module Strategies
|
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
|
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 = {})
|
def initialize(app, app_id, app_secret, options = {})
|
||||||
options[:site] = 'https://github.com/'
|
options[:site] = 'https://github.com/'
|
||||||
options[:authorize_path] = '/login/oauth/authorize'
|
options[:authorize_path] = '/login/oauth/authorize'
|
||||||
|
@ -11,6 +17,8 @@ module OmniAuth
|
||||||
super(app, :github, app_id, app_secret, options)
|
super(app, :github, app_id, app_secret, options)
|
||||||
end
|
end
|
||||||
|
|
||||||
|
protected
|
||||||
|
|
||||||
def user_data
|
def user_data
|
||||||
@data ||= MultiJson.decode(@access_token.get('/api/v2/json/user/show'))['user']
|
@data ||= MultiJson.decode(@access_token.get('/api/v2/json/user/show'))['user']
|
||||||
end
|
end
|
||||||
|
|
|
@ -7,14 +7,13 @@ module OmniAuth
|
||||||
# Authenticate to Gowalla utilizing OAuth 2.0 and retrieve
|
# Authenticate to Gowalla utilizing OAuth 2.0 and retrieve
|
||||||
# basic user information.
|
# basic user information.
|
||||||
#
|
#
|
||||||
# Usage:
|
# @example Basic Usage
|
||||||
#
|
# use OmniAuth::Strategies::Gowalla, 'API Key', 'Secret Key'
|
||||||
# use OmniAuth::Strategies::Gowalla, 'API Key', 'Secret Key'
|
|
||||||
#
|
|
||||||
# Options:
|
|
||||||
#
|
|
||||||
# <tt>:scope</tt> :: Extended permissions such as <tt>email</tt> and <tt>offline_access</tt> (which are the defaults).
|
|
||||||
class Gowalla < OAuth2
|
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 = {})
|
def initialize(app, api_key, secret_key, options = {})
|
||||||
options[:site] = 'https://api.gowalla.com/api/oauth'
|
options[:site] = 'https://api.gowalla.com/api/oauth'
|
||||||
options[:authorize_url] = 'https://gowalla.com/api/oauth/new'
|
options[:authorize_url] = 'https://gowalla.com/api/oauth/new'
|
||||||
|
@ -22,12 +21,14 @@ module OmniAuth
|
||||||
super(app, :gowalla, api_key, secret_key, options)
|
super(app, :gowalla, api_key, secret_key, options)
|
||||||
end
|
end
|
||||||
|
|
||||||
|
protected
|
||||||
|
|
||||||
def user_data
|
def user_data
|
||||||
@data ||= MultiJson.decode(@access_token.get("/users/me.json"))
|
@data ||= MultiJson.decode(@access_token.get("/users/me.json"))
|
||||||
end
|
end
|
||||||
|
|
||||||
def request_phase
|
def request_phase
|
||||||
options[:scope] ||= "email,offline_access"
|
options[:scope] ||= "read"
|
||||||
super
|
super
|
||||||
end
|
end
|
||||||
|
|
||||||
|
|
|
@ -5,11 +5,21 @@ require 'omniauth/oauth'
|
||||||
|
|
||||||
module OmniAuth
|
module OmniAuth
|
||||||
module Strategies
|
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
|
class OAuth2
|
||||||
include OmniAuth::Strategy
|
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
|
class CallbackError < StandardError
|
||||||
attr_accessor :error, :error_reason, :error_uri
|
attr_accessor :error, :error_reason, :error_uri
|
||||||
|
|
||||||
|
@ -20,6 +30,13 @@ module OmniAuth
|
||||||
end
|
end
|
||||||
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 = {})
|
def initialize(app, name, client_id, client_secret, options = {})
|
||||||
super(app, name)
|
super(app, name)
|
||||||
self.options = options
|
self.options = options
|
||||||
|
|
|
@ -4,7 +4,7 @@ module OmniAuth
|
||||||
# OmniAuth::OpenID provides strategies for authenticating to providers
|
# OmniAuth::OpenID provides strategies for authenticating to providers
|
||||||
# using the OpenID standard.
|
# using the OpenID standard.
|
||||||
#
|
#
|
||||||
# == Installation
|
# # Installation
|
||||||
#
|
#
|
||||||
# To get just OpenID functionality:
|
# To get just OpenID functionality:
|
||||||
#
|
#
|
||||||
|
@ -14,7 +14,7 @@ module OmniAuth
|
||||||
#
|
#
|
||||||
# gem install omniauth
|
# gem install omniauth
|
||||||
#
|
#
|
||||||
# == Stand-Alone Example
|
# # Stand-Alone Example
|
||||||
#
|
#
|
||||||
# Use the strategy as a middleware in your application:
|
# 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/
|
# 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:
|
# If OpenID is one of several authentication strategies, use the OmniAuth Builder:
|
||||||
#
|
#
|
||||||
|
@ -41,7 +41,7 @@ module OmniAuth
|
||||||
# provider :campfire
|
# provider :campfire
|
||||||
# end
|
# end
|
||||||
#
|
#
|
||||||
# == Configured Identifiers
|
# # Configured Identifiers
|
||||||
#
|
#
|
||||||
# You may pre-configure an OpenID identifier. For example, to use Google's main OpenID endpoint:
|
# You may pre-configure an OpenID identifier. For example, to use Google's main OpenID endpoint:
|
||||||
#
|
#
|
||||||
|
|
Loading…
Reference in New Issue