
= Apache OpenID module =

This is a library that you can use with Apache web server [1] and mod_python [2]
to enable OpenID [3] access control to web resources.

 [1] http://httpd.apache.org/
 [2] http://www.modpython.org/
 [3] http://openid.net/

== Configuration ==

To configure OpenID access control, you will only need to decide which users
should be authorized for this content. You'll need to get a list of those URLs,
separated by white space. You can either put them in the Apache configuration as
the value for the PythonOption authorized-users directive or in a file that is
pointed to by the PythonOption authorized-users-list-url directive. Other
handlers can be written to use other OpenID extensions to manage access. An
example which grants access based on Launchpad (http://launchpad.net/) team
membership in included and can be used by setting the 'handler' option to
'openidteams'.

The default setup for this module works best for protecting an entire directory
on a Web server. When using this configuration, you should be able to just
modify the example configuration below. When you're using this default
configuration, the location of the login screen will default to '+login' within
the root of the directory that you put the PythonAccessHandler directive.

=== General options ===

 * debug
    Enable debug messages.
    Values: '0', '1'
    Default: '0' (off)
 * external-cookie-names
    Cookie names from your protected app to be deleted on logout.
    Values: Space-separated list of cookie names
 * handler
    The authentication handler to use.
    Values: 'openid', 'openidteams', others as implemented.
    Default: 'openid'
 * store-type
    The OpenID store type to use.
    Values: 'memory', 'file', others as implemented.
    Default: 'memory'
 * store-directory
    The location of the store directory if store-type is 'file'.
    Values: directory location on filesystem
 * template-path
    The location of the template directory for alternative templates.
    Values: directory location on filesystem

=== OpenID options ===

 * allowed-op-list-url
    A file containing a list of OPs which support directed identity.
    Values: one per line, either 'http://hostname/' or 'http://hostname/=Label'
 * authorized-users
    A list of OpenIDs which can access the resources.
    Values: Space-separated list of OpenIDs
 * authorized-users-list-url
    A file containing a list of OpenIDs which can access the resources.
    Values: one per line

=== OpenID teams options ===

 * authorized-teams
    A list of teams whose members can access the resources.
    Values: Space-separated list of OpenID teams
 * authorized-teams-list-url
    A file containing a list of teams whose members can access the resources.
    Values: one team name per line
 * team-cache-lifetime
    The time before a user's team membership should be re-checked.
    Values: time in seconds

== Example .htaccess file ==

Most of this example .htaccess file can be used directly in a <Directory> or
<Location> block in any part of Apache configuration.

Example config::

  # This directive tells Apache to check for OpenID authentication before
  # continuing to serve the request.
  PythonAccessHandler apache_openid::protect

  # This directive tells the protection code which identifiers should be allowed
  # to access these resources. The format of the data is a text file containing
  # the identifiers. It can be any URL that is accessible to this server,
  # including a file:// URL.
  PythonOption authorized-users-list-url file:///my/directory/allowed-users.txt

  # You can also add authorized users inline in the apache config
  PythonOption authorized-users "http://me.example.com/ http://you.example.com/"

  # If you use both kinds of authorized user directive, both lists of users are
  # combined into a single list.

== Providing custom templates ==
