Browse files

[project @ documentation updates and removed references to "consumer …

…only" library]
  • Loading branch information...
1 parent dfbfea4 commit dc35318f3ee9f9e9b011712bbdfee442631cd2ac tailor committed Feb 1, 2006
Showing with 171 additions and 22 deletions.
  1. +3 −2 COPYING
  2. +2 −2 INSTALL
  3. +34 −15 README
  4. +3 −1 TODO
  5. +129 −2 lib/openid/server.rb
View
5 COPYING
@@ -1,6 +1,6 @@
-Ruby-OpenID-Consumer Library
+Ruby OpenID Library
-Copyright (C) 2005 Janrain, Inc
+Copyright (C) 2006 Janrain, Inc
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
@@ -17,4 +17,5 @@ License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Contact:
+Brian Ellin
eng+ruby@janrain.com
View
4 INSTALL
@@ -1,4 +1,4 @@
-= Ruby OpenID Consumer Installation
+= Ruby OpenID Library Installation
== Installation
@@ -21,5 +21,5 @@ Go into the test directory and execute the *runtests* script.
* Run consumer.rb in the examples directory.
* Get started writing your own consumer using OpenID::OpenIDConsumer
-
+* Write your own server with OpenID::OpenIDServer
View
49 README
@@ -1,36 +1,55 @@
=OpenID Consumer
-A Ruby library for verifying OpenID identities.
+A Ruby library for verifying and serving OpenID identities.
-This library is a port of the Python OpenID library's consumer functionality. See http://www.openidenabled.com/openid/libraries/python for more info on the Python library.
+This library is a port of the Python OpenID library. See http://www.openidenabled.com/openid/libraries/python for more info on the Python library.
==Features
-* Easy to use interface (OpenID::OpenIDConsumer)
+* Easy to use API for verifying OpenID identites - OpenID::OpenIDConsumer
+* New support for serving OpenID identites - OpenID::OpenIDServer
* Does not depend on underlying web framework
* Supports multiple storage mechanisms (Filesystem, SQL)
-* Example code to help you get started
-* Test suite
+* Example code to help you get started, including:
+ * WEBrick based consumer
+ * Ruby on rails based consumer
+ * Ruby on rails based server
+ * OpeIDLoginGenerator for quickly getting creating a rails app that uses
+ OpenID for authentication
+ * ActiveRecord adapter for using an SQL store in rails
+* Comprehensive test suite
-==Getting Started
-Please read the INSTALL file, and then have a look at the examples
-directory. A fully functional example using Ruby's WEBrick HTTP
-server library is available. I encorage you to run the example, and
-have a look at the code.
+==Installing
+Before running the examples or writing your own code you'll need to install
+the library. See the INSTALL file.
-The library is well documented. To get started, have a look at the
-example source code(examples/consumer.rb) and OpenID::OpenIDConsumer.
+The library has been tested using Ruby 1.8,
+though it may work with earlier versions. Examples were tested with
+Rails 1.0.
+
+
+==Getting Started with OpenID::OpenIDConsumer
+OpenID::OpenIDConsumer is the place to start if you'd like to support
+OpenID login or verification on your website. The examples contains
+several working examples to help you get started, and the
+OpenID::OpenIDConsumer class is well documented.
+
+
+==Serving OpenID with OpenID::OpenIDServer
+The examples directory contains fully functional OpenID server that
+uses the Ruby on Rails framework. Start by reading about the
+OpenID::OpenIDServer interface documentation and looking at the example.
-The library and dependancies have been tested using Ruby 1.8,
-though it may work with earlier versions.
==Homepage
http://www.openidenabled.com/openid/libraries/ruby
+
==Author
-Copyright 2005, Janrain, Inc.
+Copyright 2006, Janrain, Inc.
Contact Brian Ellin: brian -at- janrain -dot- com
+
==License
LGPL. For more information see the COPYING file.
View
4 TODO
@@ -1,5 +1,7 @@
-===12/29/2005
+===2/1/2006
+* Feature requests?
+===12/29/2005
* Rails example!
* Rails savvy store
* Add more store types
View
131 lib/openid/server.rb
@@ -193,6 +193,94 @@ def initialize(server_url, store)
@store = store
end
+
+ # get_openid_response processes an OpenID request, and determines the
+ # proper way to respond. It then communicates what that
+ # response should be back to its caller via return codes.
+ #
+ # The return value of this method is an array, [status, info].
+ # The first value is the status code describing what action
+ # should be taken. The second value is additional information
+ # for taking that action, and varies based on the status.
+ #
+ # The following return codes are possible:
+ #
+ # 1. OpenID::REDIRECT - This code indicates that the server
+ # should respond with an HTTP redirect. In this case,
+ # info is the URL to redirect the client to.
+ #
+ # 2. OpenID::DO_AUTH - This code indicates that the server
+ # should take whatever actions are necessary to allow
+ # this authentication to succeed or be cancelled, then
+ # try again. In this case info is a
+ # AuthorizationInfo object, which contains additional
+ # useful information.
+ #
+ # 3. OpenID::DO_ABOUT - This code indicates that the server
+ # should display a page containing information about
+ # OpenID. This is returned when it appears that a user
+ # entered an OpenID server URL directly in their
+ # browser, and the request wasn't an OpenID request at
+ # all. In this case info is nil.
+ #
+ # 4. OpenID::REMOTE_OK - This code indicates that the server
+ # should return content verbatim in response to this
+ # request, with an HTTP status code of 200. In this
+ # case, info is a String containing the content to
+ # return.
+ #
+ # 5. OpenID::REMOTE_ERROR - This code indicates that the
+ # server should return content verbatim in response to
+ # this request, with an HTTP status code of 400. In
+ # this case, info is a String containing the content
+ # to return.
+ #
+ # 6. OpenID::LOCAL_ERROR - This code indicates an error that
+ # can't be handled within the protocol. When this
+ # happens, the server may inform the user that an error
+ # has occured as it sees fit. In this case, info is
+ # a short description of the error.
+ #
+ #
+ # ===Paramters
+ #
+ # [+http_method+]
+ # String describing the HTTP method used to make the current request.
+ # The only expected values are 'GET' and 'POST'. Case will be ignored.
+ #
+ # [+args+]
+ # Hash-like object that contains the unparsed, unescaped arguments that
+ # were sent with the OpenID request being handled. The keys and values
+ # in the args hash should all be String objects.
+ #
+ # [+is_authorized+]
+ # Proc object that get_openid_response uses to determine whether or
+ # not this OpenID request should succeed. This callback needs to perform
+ # two tasks, and only evaluate to true if they both succeed, otherwise
+ # it should return false.
+ #
+ # The first task is to determine the user making this request, and
+ # if they are authorized to claim the identity URL passed into the
+ # block. If the user making the request isn't authorized to claim the
+ # identity URL, the block should evaluate to false.
+ #
+ # The second task is to determine if the user will allow the trust_root
+ # in question to determine her identity. If they have have not
+ # previously authorized the trust_root, then the block should evaluate
+ # to false.
+ #
+ # If both above tasks evaluate to true, then the block should evaluate
+ # to true.
+ #
+ # An example:
+ #
+ # is_authorized = Proc.new do |identity_url, trust_root|
+ # if logged_in? and (url_for_user == identity_url)
+ # trust_root_approved?(trust_root)
+ # else
+ # false
+ # end
+ # end
def get_openid_response(http_method, args, is_authorized)
http_method.upcase!
@@ -460,11 +548,43 @@ def post_error(msg)
end
-
+ # This is a class to encapsulate information that is useful when
+ # interacting with a user to determine if an authentication request
+ # can be authorized to succeed. This class provides methods to get
+ # the identity URL and trust root from the request that failed.
+ # Given those, the server can determine what needs to happen in
+ # order to allow the request to proceed, and can ask the user to
+ # perform the necessary actions.
+ #
+ # The user may choose to either perform the actions or not. If they
+ # do, the server should try to perform the request OpenID request
+ # again. If they choose not to, and inform the server by hitting
+ # some form of cancel button, the server should redirect them back
+ # to the consumer with a notification of that for the consumer.
+ #
+ # This class provides two approaches for each of those actions. The
+ # server can either send the user redirects which will cause the
+ # user to retry the OpenID request, or it can help perform those
+ # actions without involving an extra redirect, producing output that
+ # works like that of OpenIDServer.get_openid_response.
+ #
+ # Both approaches work equally well, and you should choose the one
+ # that fits into your framework better.
+ #
+ # The AuthorizationInfo.retry and AuthorizationInfo.cancel methods produce
+ # [status,info] arrays that should be handled exactly like the responses
+ # from OpenIDServer.get_openid_response.
+ #
+ # The retry_url and cancel_url attributes return URLs
+ # to which the user can be redirected to automatically retry or
+ # cancel this OpenID request.
class AuthorizationInfo
attr_reader :cancel_url, :identity_url, :trust_root, :return_to
+ # creates a new AuthorizationInfo object for the
+ # given values. AuthorizationInfo objects are generated by the various
+ # methods in OpenIDServer, and should not be created directly by the user.
def initialize(server_url, args)
@server_url = server_url
@return_to = args['openid.return_to']
@@ -476,10 +596,14 @@ def initialize(server_url, args)
@args = args.dup
end
- def retry(openid_server, is_authorized)
+ # Retries an OpenID authentication request. Basically just calls
+ # OpenIDServer instance passed in with its request arguments,
+ # and the is_authorized Proc passed in.
+ def retry(openid_server, is_authorized)
openid_server.get_openid_response('GET', @args, is_authorized)
end
+ # Cancels an OpenID request
def cancel
return [REDIRECT, @cancel_url]
end
@@ -488,6 +612,9 @@ def retry_url
OpenID::Util.append_args(@server_url, @args)
end
+ # Generate a string representing this object. The string can be
+ # passed into the AuthorizationInfo.deserialize class method to
+ # recreate the instance.
def serialize
@server_url + '|' + OpenID::Util.urlencode(@args)
end

0 comments on commit dc35318

Please sign in to comment.