diff --git a/lib/rack/auth/openid.rb b/lib/rack/auth/openid.rb index 46b606b4f..9aff4c817 100644 --- a/lib/rack/auth/openid.rb +++ b/lib/rack/auth/openid.rb @@ -86,36 +86,54 @@ class NoSession < RuntimeError; end # # == Options # - # :return_to defines the url to return to after the client authenticates with the openid service provider. This url should point to where Rack::Auth::OpenID is mounted. If :return_to is not provided, the url will be derived within the ruby-openid implementation. + # :return_to defines the url to return to after the client + # authenticates with the openid service provider. This url should point + # to where Rack::Auth::OpenID is mounted. If :return_to is not + # provided, :return_to will be the current url including all query + # parameters. # - # :session_key defines the key to the session hash in the env. It defaults to 'rack.session'. + # :session_key defines the key to the session hash in the env. + # It defaults to 'rack.session'. # - # :openid_param defines at what key in the request parameters to find the identifier to resolve. As per the 2.0 spec, the default is 'openid_identifier'. + # :openid_param defines at what key in the request parameters to + # find the identifier to resolve. As per the 2.0 spec, the default is + # 'openid_identifier'. # - # :immediate as true will make immediate type of requests the default. See the specification documentation. + # :immediate as true will make immediate type of requests the + # default. See OpenID specification documentation. # # === URL options # - # :login_good is the url to go to after the authentication process has completed. + # :login_good is the url to go to after the authentication + # process has completed. # - # :login_fail is the url to go to after the authentication process has failed. + # :login_fail is the url to go to after the authentication + # process has failed. # - # :login_quit is the url to go to after the authentication process + # :login_quit is the url to go to after the authentication + # process # has been cancelled. # # === Response options # - # :no_session should be a rack response to be returned if no or an incompatible session is found. + # :no_session should be a rack response to be returned if no or + # an incompatible session is found. # - # :auth_fail should be a rack response to be returned if an OpenID::DiscoveryFailure occurs. This is typically due to being unable to access the identity url or identity server. + # :auth_fail should be a rack response to be returned if an + # OpenID::DiscoveryFailure occurs. This is typically due to being unable + # to access the identity url or identity server. # - # :error should be a rack response to return if any other generic error would occur and options[:catch_errors] is true. + # :error should be a rack response to return if any other + # generic error would occur and options[:catch_errors] is true. # # === Extensions # - # :extensions should be a hash of openid extension implementations. The key should be the extension main module, the value should be an array of arguments for extension::Request.new + # :extensions should be a hash of openid extension + # implementations. The key should be the extension main module, the value + # should be an array of arguments for extension::Request.new # - # The hash is iterated over and passed to #add_extension for processing. Please see #add_extension for further documentation. + # The hash is iterated over and passed to #add_extension for processing. + # Please see #add_extension for further documentation. def initialize(realm, options={}) @realm = realm realm = URI(realm) @@ -163,15 +181,21 @@ def initialize(realm, options={}) attr_reader :options, :extensions - # It sets up and uses session data at :openid within the session. It sets up the ::OpenID::Consumer using the store specified by options[:store]. + # It sets up and uses session data at :openid within the + # session. It sets up the ::OpenID::Consumer using the store specified by + # options[:store]. # - # If the parameter specified by options[:openid_param] is present, processing is passed to #check and the result is returned. + # If the parameter specified by options[:openid_param] is + # present, processing is passed to #check and the result is returned. # - # If the parameter 'openid.mode' is set, implying a followup from the openid server, processing is passed to #finish and the result is returned. + # If the parameter 'openid.mode' is set, implying a followup from the + # openid server, processing is passed to #finish and the result is + # returned. # # If neither of these conditions are met, a 400 error is returned. # - # If an error is thrown and options[:catch_errors] is false, the exception will be reraised. Otherwise a 500 error is returned. + # If an error is thrown and options[:catch_errors] is false, the + # exception will be reraised. Otherwise a 500 error is returned. def call(env) env['rack.auth.openid'] = self session = env[@options[:session_key]] @@ -214,11 +238,15 @@ def call(env) 'OpenID has encountered an error.' ] end - # As the first part of OpenID consumer action, #check retrieves the data required for completion. - # - # * session[:openid][:openid_param] is set to the submitted identifier to be authenticated. - # * session[:openid][:site_return] is set as the request's HTTP_REFERER, unless already set. - # * env['rack.auth.openid.request'] is the openid checkid request instance. + # As the first part of OpenID consumer action, #check retrieves the data + # required for completion. + # + # * session[:openid][:openid_param] is set to the submitted + # identifier to be authenticated. + # * session[:openid][:site_return] is set as the request's + # HTTP_REFERER, unless already set. + # * env['rack.auth.openid.request'] is the openid checkid + # request instance. def check(consumer, session, req) session[:openid_param] = req.params[@options[:openid_param]] oid = consumer.begin(session[:openid_param], @options[:anonymous]) @@ -261,8 +289,9 @@ def check(consumer, session, req) # of specification occur, a 303 redirect will be returned with Location # determined by the OpenID response type. If none of the response type # :login_* urls are set, the redirect will be set to - # session[:openid][:site_return]. If session[:openid][:site_return] is - # unset, the realm will be used. + # session[:openid][:site_return]. If + # session[:openid][:site_return] is unset, the realm will be + # used. # # Any messages from OpenID's response are appended to the 303 response # body. @@ -273,19 +302,25 @@ def check(consumer, session, req) # * env['rack.auth.openid.response'] is the openid response. # # The four valid possible outcomes are: - # * failure: options[:login_fail] or session[:site_return] or the realm - # * session[:openid] is cleared and any messages are send to rack.errors + # * failure: options[:login_fail] or + # session[:site_return] or the realm + # * session[:openid] is cleared and any messages are send to + # rack.errors # * session[:openid]['authenticated'] is false - # * success: options[:login_good] or session[:site_return] or the realm + # * success: options[:login_good] or + # session[:site_return] or the realm # * session[:openid] is cleared # * session[:openid]['authenticated'] is true # * session[:openid]['identity'] is the actual identifier # * session[:openid]['identifier'] is the pretty identifier - # * cancel: options[:login_good] or session[:site_return] or the realm + # * cancel: options[:login_good] or + # session[:site_return] or the realm # * session[:openid] is cleared # * session[:openid]['authenticated'] is false - # * setup_needed: resubmits the authentication request. A flag is set for non-immediate handling. - # * session[:openid][:setup_needed] is set to true, which will prevent immediate style openid authentication. + # * setup_needed: resubmits the authentication request. A flag is set for + # non-immediate handling. + # * session[:openid][:setup_needed] is set to true, + # which will prevent immediate style openid authentication. def finish(consumer, session, req) oid = consumer.complete(req.params, req.url) pp oid if $DEBUG @@ -345,12 +380,17 @@ def finish(consumer, session, req) # The extension module should contain the constants: # * class Request, with OpenID::Extension as an ancestor # * class Response, with OpenID::Extension as an ancestor - # * string NS_URI, which defines the namespace of the extension, should be an absolute http uri + # * string NS_URI, which defines the namespace of the extension, should + # be an absolute http uri # - # All trailing arguments will be passed to extension::Request.new in #check. - # The openid response will be passed to extension::Response#from_success_response, #get_extension_args will be called on the result to attain the gathered data. + # All trailing arguments will be passed to extension::Request.new in + # #check. + # The openid response will be passed to + # extension::Response#from_success_response, #get_extension_args will be + # called on the result to attain the gathered data. # - # This method returns the key at which the response data will be found in the session, which is the namespace uri by default. + # This method returns the key at which the response data will be found in + # the session, which is the namespace uri by default. def add_extension ext, *args if not ext.is_a? Module raise TypeError, "Extension #{ext.inspect} is not a module" @@ -367,7 +407,8 @@ def add_extension ext, *args return ext::NS_URI end - # A conveniance method that returns the namespace of all current extensions used by this instance. + # A conveniance method that returns the namespace of all current + # extensions used by this instance. def extension_namespaces @extensions.keys.map{|e|e::NS_URI} end