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[‘rack.session’].

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