Class: Rack::Auth::OpenID

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

Rack::Auth::OpenID provides a simple method for permitting openid based logins. 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 functionality.

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

All responses from this rack application will be 303 redirects unless an error occurs, with the exception of an authentication request requiring an HTML form submission.

NOTE: Extensions are not currently supported by this implimentation of the OpenID rack application due to the complexity of the current ruby-openid extension handling.

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

### Methods

add_extension call check extension_namespaces finish new

### Classes and Modules

Class Rack::Auth::OpenID::NoSession

### Constants

OIDStore | = | ::OpenID::Store::Memory.new |  | Required for ruby-openid
HTML | = | '<html><head><title>%s</title></head><body>%s</body></html>'

### Attributes

extensions | [R] |
options | [R] |

### Public Class methods

new(realm, options={})

A Hash of options is taken as it‘s single initializing argument. For example:

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

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

      page_oid = OpenID.new('http://mysite.com/',
        :login_good => 'http://mysite.com/auth_good'
      )

      complex_oid = OpenID.new('http://mysite.com/',
        :return_to => 'http://mysite.com/openid',
        :login_good => 'http://mysite.com/user/preferences',
        :auth_fail => [500, {'Content-Type'=>'text/plain'},
          'Unable to negotiate with foreign server.'],
        :immediate => true,
        :extensions => {
          ::OpenID::SReg => [['email'],['nickname']]
        }
      )

# Arguments

The first argument is the realm, identifying the site they are trusting with their identity. This is required.

NOTE: In OpenID 1.x, the realm or trust_root is optional and the return_to url is required. As this library strives tward ruby-openid 2.0, and OpenID 2.0 compatibiliy, the realm is required and return_to is optional. However, this implimentation is still backwards compatible with OpenID 1.0 servers.

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 including all query parameters.

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

`: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_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 has been cancelled.

### Response options

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

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

The hash is iterated over and passed to add_extension for processing. Please see add_extension for further documentation.

### 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, 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

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)

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 ‘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.

check(consumer, session, req)

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` is the openid checkid request instance.

extension_namespaces()

A conveniance method that returns the namespace of all current extensions used by this instance.

finish(consumer, session, req)

This is the final portion of authentication. Unless any errors outside 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.

Any messages from OpenID‘s response are appended to the 303 response body.

Data gathered from extensions are stored in session[:openid] with the extension‘s namespace uri as the key.

- `env` 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
  - `session[:openid][‘authenticated’]` is `false`
- 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
  - `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.

[Validate]