libopenid-ruby1.8 2.1.8debian-1 / usr / lib / ruby / 1.8 / openid / consumer.rb

require "openid/consumer/idres.rb"
require "openid/consumer/checkid_request.rb"
require "openid/consumer/associationmanager.rb"
require "openid/consumer/responses.rb"
require "openid/consumer/discovery_manager"
require "openid/consumer/discovery"
require "openid/message"
require "openid/yadis/discovery"
require "openid/store/nonce"

module OpenID
  # OpenID support for Relying Parties (aka Consumers).
  #
  # This module documents the main interface with the OpenID consumer
  # library.  The only part of the library which has to be used and
  # isn't documented in full here is the store required to create an
  # Consumer instance.
  #
  # = OVERVIEW
  #
  # The OpenID identity verification process most commonly uses the
  # following steps, as visible to the user of this library:
  #
  # 1. The user enters their OpenID into a field on the consumer's
  #    site, and hits a login button.
  #
  # 2. The consumer site discovers the user's OpenID provider using
  #    the Yadis protocol.
  #
  # 3. The consumer site sends the browser a redirect to the OpenID
  #    provider.  This is the authentication request as described in
  #    the OpenID specification.
  #
  # 4. The OpenID provider's site sends the browser a redirect back to
  #    the consumer site.  This redirect contains the provider's
  #    response to the authentication request.
  #
  # The most important part of the flow to note is the consumer's site
  # must handle two separate HTTP requests in order to perform the
  # full identity check.
  #
  # = LIBRARY DESIGN
  #
  # This consumer library is designed with that flow in mind.  The
  # goal is to make it as easy as possible to perform the above steps
  # securely.
  #
  # At a high level, there are two important parts in the consumer
  # library.  The first important part is this module, which contains
  # the interface to actually use this library.  The second is
  # openid/store/interface.rb, which describes the interface to use if
  # you need to create a custom method for storing the state this
  # library needs to maintain between requests.
  #
  # In general, the second part is less important for users of the
  # library to know about, as several implementations are provided
  # which cover a wide variety of situations in which consumers may
  # use the library.
  #
  # The Consumer class has methods corresponding to the actions
  # necessary in each of steps 2, 3, and 4 described in the overview.
  # Use of this library should be as easy as creating an Consumer
  # instance and calling the methods appropriate for the action the
  # site wants to take.
  #
  # This library automatically detects which version of the OpenID
  # protocol should be used for a transaction and constructs the
  # proper requests and responses.  Users of this library do not need
  # to worry about supporting multiple protocol versions; the library
  # supports them implicitly.  Depending on the version of the
  # protocol in use, the OpenID transaction may be more secure.  See
  # the OpenID specifications for more information.
  #
  # = SESSIONS, STORES, AND STATELESS MODE
  #
  # The Consumer object keeps track of two types of state:
  #
  # 1. State of the user's current authentication attempt.  Things
  #    like the identity URL, the list of endpoints discovered for
  #    that URL, and in case where some endpoints are unreachable, the
  #    list of endpoints already tried.  This state needs to be held
  #    from Consumer.begin() to Consumer.complete(), but it is only
  #    applicable to a single session with a single user agent, and at
  #    the end of the authentication process (i.e. when an OP replies
  #    with either <tt>id_res</tt>. or <tt>cancel</tt> it may be
  #    discarded.
  #
  # 2. State of relationships with servers, i.e. shared secrets
  #    (associations) with servers and nonces seen on signed messages.
  #    This information should persist from one session to the next
  #    and should not be bound to a particular user-agent.
  #
  # These two types of storage are reflected in the first two
  # arguments of Consumer's constructor, <tt>session</tt> and
  # <tt>store</tt>.  <tt>session</tt> is a dict-like object and we
  # hope your web framework provides you with one of these bound to
  # the user agent.  <tt>store</tt> is an instance of Store.
  #
  # Since the store does hold secrets shared between your application
  # and the OpenID provider, you should be careful about how you use
  # it in a shared hosting environment.  If the filesystem or database
  # permissions of your web host allow strangers to read from them, do
  # not store your data there!  If you have no safe place to store
  # your data, construct your consumer with nil for the store, and it
  # will operate only in stateless mode.  Stateless mode may be
  # slower, put more load on the OpenID provider, and trusts the
  # provider to keep you safe from replay attacks.
  #
  # Several store implementation are provided, and the interface is
  # fully documented so that custom stores can be used as well.  See
  # the documentation for the Consumer class for more information on
  # the interface for stores.  The implementations that are provided
  # allow the consumer site to store the necessary data in several
  # different ways, including several SQL databases and normal files
  # on disk.
  #
  # = IMMEDIATE MODE
  #
  # In the flow described above, the user may need to confirm to the
  # OpenID provider that it's ok to disclose his or her identity.  The
  # provider may draw pages asking for information from the user
  # before it redirects the browser back to the consumer's site.  This
  # is generally transparent to the consumer site, so it is typically
  # ignored as an implementation detail.
  #
  # There can be times, however, where the consumer site wants to get
  # a response immediately.  When this is the case, the consumer can
  # put the library in immediate mode.  In immediate mode, there is an
  # extra response possible from the server, which is essentially the
  # server reporting that it doesn't have enough information to answer
  # the question yet.
  #
  # = USING THIS LIBRARY
  #
  # Integrating this library into an application is usually a
  # relatively straightforward process.  The process should basically
  # follow this plan:
  #
  # Add an OpenID login field somewhere on your site.  When an OpenID
  # is entered in that field and the form is submitted, it should make
  # a request to the your site which includes that OpenID URL.
  #
  # First, the application should instantiate a Consumer with a
  # session for per-user state and store for shared state using the
  # store of choice.
  #
  # Next, the application should call the <tt>begin</tt> method of
  # Consumer instance.  This method takes the OpenID URL as entered by
  # the user.  The <tt>begin</tt> method returns a CheckIDRequest
  # object.
  #
  # Next, the application should call the redirect_url method on the
  # CheckIDRequest object.  The parameter <tt>return_to</tt> is the
  # URL that the OpenID server will send the user back to after
  # attempting to verify his or her identity.  The <tt>realm</tt>
  # parameter is the URL (or URL pattern) that identifies your web
  # site to the user when he or she is authorizing it.  Send a
  # redirect to the resulting URL to the user's browser.
  #
  # That's the first half of the authentication process.  The second
  # half of the process is done after the user's OpenID Provider sends
  # the user's browser a redirect back to your site to complete their
  # login.
  #
  # When that happens, the user will contact your site at the URL
  # given as the <tt>return_to</tt> URL to the redirect_url call made
  # above.  The request will have several query parameters added to
  # the URL by the OpenID provider as the information necessary to
  # finish the request.
  #
  # Get a Consumer instance with the same session and store as before
  # and call its complete() method, passing in all the received query
  # arguments and URL currently being handled.
  #
  # There are multiple possible return types possible from that
  # method. These indicate the whether or not the login was
  # successful, and include any additional information appropriate for
  # their type.
  class Consumer
    attr_accessor :session_key_prefix

    # Initialize a Consumer instance.
    #
    # You should create a new instance of the Consumer object with
    # every HTTP request that handles OpenID transactions.
    #
    # session: the session object to use to store request information.
    # The session should behave like a hash.
    #
    # store: an object that implements the interface in Store.
    def initialize(session, store)
      @session = session
      @store = store
      @session_key_prefix = 'OpenID::Consumer::'
    end

    # Start the OpenID authentication process. See steps 1-2 in the
    # overview for the Consumer class.
    #
    # user_url: Identity URL given by the user. This method performs a
    # textual transformation of the URL to try and make sure it is
    # normalized. For example, a user_url of example.com will be
    # normalized to http://example.com/ normalizing and resolving any
    # redirects the server might issue.
    #
    # anonymous: A boolean value.  Whether to make an anonymous
    # request of the OpenID provider.  Such a request does not ask for
    # an authorization assertion for an OpenID identifier, but may be
    # used with extensions to pass other data.  e.g. "I don't care who
    # you are, but I'd like to know your time zone."
    #
    # Returns a CheckIDRequest object containing the discovered
    # information, with a method for building a redirect URL to the
    # server, as described in step 3 of the overview. This object may
    # also be used to add extension arguments to the request, using
    # its add_extension_arg method.
    #
    # Raises DiscoveryFailure when no OpenID server can be found for
    # this URL.
    def begin(openid_identifier, anonymous=false)
      manager = discovery_manager(openid_identifier)
      service = manager.get_next_service(&method(:discover))

      if service.nil?
        raise DiscoveryFailure.new("No usable OpenID services were found "\
                                   "for #{openid_identifier.inspect}", nil)
      else
        begin_without_discovery(service, anonymous)
      end
    end

    # Start OpenID verification without doing OpenID server
    # discovery. This method is used internally by Consumer.begin()
    # after discovery is performed, and exists to provide an interface
    # for library users needing to perform their own discovery.
    #
    # service: an OpenID service endpoint descriptor.  This object and
    # factories for it are found in the openid/consumer/discovery.rb
    # module.
    #
    # Returns an OpenID authentication request object.
    def begin_without_discovery(service, anonymous)
      assoc = association_manager(service).get_association
      checkid_request = CheckIDRequest.new(assoc, service)
      checkid_request.anonymous = anonymous

      if service.compatibility_mode
        rt_args = checkid_request.return_to_args
        rt_args[Consumer.openid1_return_to_nonce_name] = Nonce.mk_nonce
        rt_args[Consumer.openid1_return_to_claimed_id_name] =
          service.claimed_id
      end

      self.last_requested_endpoint = service
      return checkid_request
    end

    # Called to interpret the server's response to an OpenID
    # request. It is called in step 4 of the flow described in the
    # Consumer overview.
    #
    # query: A hash of the query parameters for this HTTP request.
    # Note that in rails, this is <b>not</b> <tt>params</tt> but
    # <tt>params.reject{|k,v|request.path_parameters[k]}</tt>
    # because <tt>controller</tt> and <tt>action</tt> and other
    # "path parameters" are included in params.
    #
    # current_url: Extract the URL of the current request from your
    # application's web request framework and specify it here to have it
    # checked against the openid.return_to value in the response.  Do not
    # just pass <tt>args['openid.return_to']</tt> here; that will defeat the
    # purpose of this check.  (See OpenID Authentication 2.0 section 11.1.)
    #
    # If the return_to URL check fails, the status of the completion will be
    # FAILURE.

    #
    # Returns a subclass of Response. The type of response is
    # indicated by the status attribute, which will be one of
    # SUCCESS, CANCEL, FAILURE, or SETUP_NEEDED.
    def complete(query, current_url)
      message = Message.from_post_args(query)
      mode = message.get_arg(OPENID_NS, 'mode', 'invalid')
      begin
        meth = method('complete_' + mode)
      rescue NameError
        meth = method(:complete_invalid)
      end
      response = meth.call(message, current_url)
      cleanup_last_requested_endpoint
      if [SUCCESS, CANCEL].member?(response.status)
        cleanup_session
      end
      return response
    end

    protected

    def session_get(name)
      @session[session_key(name)]
    end

    def session_set(name, val)
      @session[session_key(name)] = val
    end

    def session_key(suffix)
      @session_key_prefix + suffix
    end

    def last_requested_endpoint
      session_get('last_requested_endpoint')
    end

    def last_requested_endpoint=(endpoint)
      session_set('last_requested_endpoint', endpoint)
    end

    def cleanup_last_requested_endpoint
      @session[session_key('last_requested_endpoint')] = nil
    end

    def discovery_manager(openid_identifier)
      DiscoveryManager.new(@session, openid_identifier, @session_key_prefix)
    end

    def cleanup_session
      discovery_manager(nil).cleanup(true)
    end


    def discover(identifier)
      OpenID.discover(identifier)
    end

    def negotiator
      DefaultNegotiator
    end

    def association_manager(service)
      AssociationManager.new(@store, service.server_url,
                             service.compatibility_mode, negotiator)
    end

    def handle_idres(message, current_url)
      IdResHandler.new(message, current_url, @store, last_requested_endpoint)
    end

    def complete_invalid(message, unused_return_to)
      mode = message.get_arg(OPENID_NS, 'mode', '<No mode set>')
      return FailureResponse.new(last_requested_endpoint,
                                 "Invalid openid.mode: #{mode}")
    end

    def complete_cancel(unused_message, unused_return_to)
      return CancelResponse.new(last_requested_endpoint)
    end

    def complete_error(message, unused_return_to)
      error = message.get_arg(OPENID_NS, 'error')
      contact = message.get_arg(OPENID_NS, 'contact')
      reference = message.get_arg(OPENID_NS, 'reference')

      return FailureResponse.new(last_requested_endpoint,
                                 error, contact, reference)
    end

    def complete_setup_needed(message, unused_return_to)
      if message.is_openid1
        return complete_invalid(message, nil)
      else
        setup_url = message.get_arg(OPENID2_NS, 'user_setup_url')
        return SetupNeededResponse.new(last_requested_endpoint, setup_url)
      end
    end

    def complete_id_res(message, current_url)
      if message.is_openid1
        setup_url = message.get_arg(OPENID_NS, 'user_setup_url')
        if !setup_url.nil?
          return SetupNeededResponse.new(last_requested_endpoint, setup_url)
        end
      end

      begin
        idres = handle_idres(message, current_url)
      rescue OpenIDError => why
        return FailureResponse.new(last_requested_endpoint, why.message)
      else
        return SuccessResponse.new(idres.endpoint, message,
                                     idres.signed_fields)
      end
    end
  end
end