Class: Rack::Auth::OpenID

Class | Rack::Auth::OpenID
In: | lib/rack/auth/openid.rb
Parent: | Object

Rack::Auth::OpenID provides a simple method for setting up an OpenID Consumer. It requires the ruby-openid library from janrain to operate, as well as a rack method of session management.

The ruby-openid home page is at openidenabled.com/ruby-openid/.

The OpenID specifications can be found at openid.net/specs/openid-authentication-1_1.html and openid.net/specs/openid-authentication-2_0.html. Documentation for published OpenID extensions and related topics can be found at openid.net/developers/specs/.

It is recommended to read through the OpenID spec, as well as ruby-openid‘s documentation, to understand what exactly goes on. However a setup as simple as the presented examples is enough to provide Consumer functionality.

This library strongly intends to utilize the OpenID 2.0 features of the ruby-openid library, which provides OpenID 1.0 compatiblity.

NOTE: Due to the amount of data that this library stores in the session, Rack::Session::Cookie may fault.

### Methods

access_denied add_extension bad_request call check confirm_post_params finish foreign_server_failure include? new redirect unauthorized valid_extension? within_realm?

### Classes and Modules

Class Rack::Auth::OpenID::BadExtension
Class Rack::Auth::OpenID::NoSession

### Constants

ValidStatus | = | [:success, :setup_needed, :cancel, :failure] |  | Required for ruby-openid

### Attributes

extensions | [R] |
immediate | [R] |
openid_param | [R] |
realm | [R] |
return_to | [R] |
session_key | [R] |
store | [R] |

### Public Class methods

new(realm, options={})

# Arguments

The first argument is the realm, identifying the site they are trusting with their identity. This is required, also treated as the trust_root in OpenID 1.x exchanges.

The optional second argument is a hash of options.

## 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, return_to will be the current url which allows flexibility with caveats.

`: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’.

`:store` defined what OpenID Store to use for persistant information. By default a Store::Memory will be used.

`:immediate` as true will make initial requests to be of an immediate type. This is false by default. See OpenID specification documentation.

`: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.

## Examples

      simple_oid = OpenID.new('http://mysite.com/')

      return_oid = OpenID.new('http://mysite.com/', {
        :return_to => 'http://mysite.com/openid'
      })

      complex_oid = OpenID.new('http://mysite.com/',
        :immediate => true,
        :extensions => {
          ::OpenID::SReg => [['email'],['nickname']]
        }
      )

# Advanced

Most of the functionality of this library is encapsulated such that expansion and overriding functions isn‘t difficult nor tricky. Alternately, to avoid opening up singleton objects or subclassing, a wrapper rack middleware can be composed to act upon Auth::OpenID‘s responses. See check and finish for locations of pertinent data.

## Responses

To change the responses that Auth::OpenID returns, override the methods redirect, bad_request, unauthorized, access_denied, and foreign_server_failure.

Additionally confirm_post_params is used when the URI would exceed length limits on a GET request when doing the initial verification request.

## Processing

To change methods of processing completed transactions, override the methods success, setup_needed, cancel, and failure. Please ensure the returned object is a rack compatible response.

The first argument is an OpenID::Response, the second is a Rack::Request of the current request, the last is the hash used in ruby-openid handling, which can be found manually at env[:openid].

This is useful if you wanted to expand the processing done, such as setting up user accounts.

      oid_app = Rack::Auth::OpenID.new realm, :return_to => return_to
      def oid_app.success oid, request, session
        user = Models::User[oid.identity_url]
        user ||= Models::User.create_from_openid oid
        request['rack.session'][:user] = user.id
        redirect MyApp.site_home
      end

      site_map['/openid'] = oid_app
      map = Rack::URLMap.new site_map
      ...

### Public Instance methods

add_extension(ext, *args)

The first argument should be the main extension module. The extension module should contain the constants:

      * class Request, should have OpenID::Extension as an ancestor
      * class Response, should have OpenID::Extension as an ancestor
      * string NS_URI, which defining the namespace of the extension

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.

call(env)

Sets up and uses session data at `:openid` within the session. Errors in this setup will raise a NoSession exception.

If the parameter ‘openid.mode’ is set, which implies a followup from the openid server, processing is passed to finish and the result is returned. However, if there is no appropriate openid information in the session, a 400 error is returned.

If the parameter specified by `options[:openid_param]` is present, processing is passed to check and the result is returned.

If neither of these conditions are met, unauthorized is called.

check(consumer, session, req)

As the first part of OpenID consumer action, check retrieves the data required for completion.

If all parameters fit within the max length of a URI, a 303 redirect will be returned. Otherwise confirm_post_params will be called.

Any messages from OpenID‘s request are logged to env

`env` is the openid checkid request instance.

`session[:openid_param]` is set to the openid identifier provided by the user.

`session[:return_to]` is set to the return_to uri given to the identity provider.

finish(consumer, session, req)

This is the final portion of authentication. If successful, a redirect to the realm is be returned. Data gathered from extensions are stored in session[:openid] with the extension‘s namespace uri as the key.

Any messages from OpenID‘s response are logged to env

`env` will contain the openid response.

include?(uri)

Alias for within_realm?

valid_extension?(ext)

Checks the validitity, in the context of usage, of a submitted extension.

within_realm?(uri)

Checks the provided uri to ensure it‘d be considered within the realm. is currently not compatible with wildcard realms.

### Protected Instance methods

access_denied()

Returns a basic access denied 403 response.

bad_request()

Returns an empty 400 response.

confirm_post_params(oid, realm, return_to, immediate)

Returns an html form page for posting to an Identity Provider if the GET request would exceed the upper URI length limit.

foreign_server_failure()

Returns a 503 response to be used if communication with the remote OpenID server fails.

redirect(uri)

Returns a 303 redirect with the destination of that provided by the argument.

unauthorized()

Returns a basic unauthorized 401 response.

[Validate]