mod_auth_oid

mod_auth_oid
 

mod_auth_oid is an Apache 2.2 module implementing an OpenID 2.0 Relying Party. It may be used to enable Apache base application to authenticate their users without needing access to user credentials such as a password. The module implements the necessary functions in order to verify the users OpenID identity using the appropriate OpenID Provider without using third party components. You only need an Apache server with some standard modules (e.g. mod_ssl) and the parameter parser module mod_parp.

mod_auth_oid is available at SourceForge.net under the GNU General Public License. The current version does not support all the options of the OpenID 2.0 specification and is provided as is without any warranty.

Overview

The following image shows the sequence of a login procedure:

sequence

The main steps are:
2) The user is redirected to the login handler of mod_auth_oid if access is denied because the user has not yet been authenticated.
4) mod_auth_oid presents a login page (HTML page with a login form).
5) The user sends his OpenID identity (HTTP reference).
6) - 9) mod_auth_oid discovers and establishs the associations.
10) The user is redirected to the OpenID Provider. mod_auth_oid sets a cookie to the browser.
11) The user is authenticated by the OpenID Provider.
13) mod_auth_oid receives and verfies the assertion.
14) The OpenID identity is mapped to a local user id konwn by the application.
15) mod_auth_oid starts a new authentication session for the user (cookie) and redirects him to the page he has required in step "1)".
16) - 17) The user is allowed to access the application until the authentication session cookie expires.

Configuration

Configuration is mainly made on a per server basis. Commands within a virtual host overwrite the global configuration settings.

Base Server Settings

The module requires mod_ssl and you have to provide the CA certificates which are used by the OpenID Providers. This is necessary because mod_auth_oid uses HTTPS with server authentication for providers using HTTPS for the users identity. It's recommended to use only OpenID Providers faturing discovery and association establishment over HTTPS.
Example:
# Allows SSL for outgoing requests to the provider.
SSLProxyEngine            on

# Defines the CA certificates to be used to verify the provider's certificate.
SSLProxyCACertificateFile ssl/cacert.pem

Realm

The realm defines the path (URL) a user has been authenticated to. A user can't access a path outside the defined path. The default realm is "/" which means that a user may access any path configured for a server after he has successfully been authenticated. The realm is defined by the AOID_Realm directive. Each realm MUST define a path for the handler processing authentication requests. This path is called "login path" and it is defined by the AOID_LoginPath directive. Each request to this path is handled by the login handler of mod_auth_oid. You may either let a user send his OpenID identity to this path using a HTML form which you had defined anywhere within your application or you may define a local (S)HTML document containing the required login form. The documents name must be equal to the base name of the login path using the prefix defined by the AOID_LoginSuffix.

  • AOID_Realm <path>
    Specifies the path of URLs within the realm. Default is the path "/".
  • AOID_LoginPath <path>
    Defines the URL where the login handler of mod_auth_oid is listening. This directive has no default value and the module is switched off as long as you don't specify this path.
  • AOID_LoginSuffix <suffix>
    Specifies the file suffix of the login page document. The file name of this document is build by concatenation of the values of AOID_LoginPath and AOID_LoginSuffix. Default is '.shtml'.
    The error document may be an SHTML document processed by mod_include. The module sets two enviroment variables which may be processed within the SHTML page. The REDIRECT_ERROR_NOTES shows an optional error message which describes the reason for a failed login. See the login.shtml file of the mod_auth_oid distribution archive to see how to handle the different messages. The aoid_redirect_to stores the requested page a user had tried to requiest. You should include this parameter as a hidden field within the login form in order to redirect the user after a successful login to the URL he has initially requested.
Example:
# Allows access for all URLs starting with "/".
AOID_Realm                /

# The login handler is available under the path "/aoid/login".
AOID_LoginPath            /aoid/login
# The file presenting the login page is "login.shtml" located in the directory "/aoid".
AOID_LoginSuffix          .shtml

# Definition for the access to the login page.
<Location /aoid>
   # Enable SSI for the login page (requires mod_include).
   Options                Includes
   AddType                text/html .shtml
   AddOutputFilter        INCLUDES .shtml
</Location>

User Mapping

The OpenID identity must be mapped to a user id known by the application.

Apache Configuration

mod_auth_oid implements static user id mapping using the AOID_User directive. The directive is set within the Apache configuration. A server restart is required in order to load new mapping definitions.

  • AOID_User <OpenID> <local id>
    Maps the specified OpenID to a local user id known by the application.
Example:
# Static user table.
AOID_User                 https://me.yahoo.com/bob      bobwhite
AOID_User                 https://me.yahoo.com/alice    alicebrown
AOID_User                 https://me.yahoo.com/carol    carolgreen
AOID_User                 http://dave.myopenid.com/     daveblack
AOID_User                 https://me.yahoo.com/bigadmin administrator

Optional Apache Modules

Optional Apache modules may provide OpenID to local user id mapping by implementing the mapping hook of mod_auth_oid. You may either write your own Apache module (see the sample code below) or use one of the available mapping modules.
Note: You must compile mod_auth_oid defining AOID_MOD_EXT_HOOKS because this hook is disabled otherwise.

Available modules:

  • Flat file
    The mod_auth_oid_file module, which is part of the mod_auth_oid source package, allows OpenID to local user id mapping using a flat file.

Writing your own mapping module:
Sample code to implement a user mapping module:
#include <mod_auth_oid.h>

/**
 * Function which implements mapping from an OpenID to a local user id.
 * @param openid IN OpenID to map.
 * @param user OUT Local user id known by the application.
 * @return DECLINE if mod_auth_oid should continue to search
 *         for an alternative user mapping.
 */
static apr_status_t my_mapper(request_rec *r, const char *openid, const char **user) {
  if(strcmp(openid, "https://me.yahoo.com/alice") == 0) {
    *user = apr_pstrdup(r->pool, "alicebrown");
    return APR_SUCCESS;
  }
  return DECLINED;
}

/**
 * Register the funtion which implements user mapping. The function "my_mapper()"
 * will be called for each user which has been authenticated.
 */
APR_OPTIONAL_HOOK(aoid, map_user_hook, my_mapper, NULL, NULL, APR_HOOK_MIDDLE);

Access Control

User authentication may be enforced using the Apache directives AuthType and Require. The authentication type "OpenID" ensures that mod_auth_oid enforces user authentication. A user is authenticated if the OpenID assertion has been successfully verified and the OpenID identity has been mapped to a local user id.
Example:
# Restrict access to "/path" to users which has been authenticated by mod_auth_oid.
<Location /path>
   AuthType               OpenID
   Require                valid-user
</Location>

Basic Authentication

OpenID user authentication may also used as an alternative to HTTP basic authentication using mod_auth_basic. mod_auth_oid does not enforce user authentication in such a setup but grants access to users which has been authenticated by mod_auth_oid. User authentication by mod_auth_oid may be initiated either by configuring a HTML login form anywhere of the application's HTML documents or by setting the 401 ErrorDocument to the mod_auth_oid login handler.
Example:
ErrorDocument             401 /aoid/login.shtml
<Location /path>
   AuthType               Basic
   AuthUserFile           auth/htpasswd
   AuthName               private
   Require                valid-user
</Location>

Options

These optional settings may be used to customize mod_auth_oid to suite your demands.

  • AOID_Timeout <seconds>
    Specifies the timeout for the authenticated session. Default are 14400 seconds (4 hours).
  • AOID_Passphrase <string>
    Defines the passphrase which is used to encrypt/sign the session cookie. A random passphrase is used by default which changes with every server restart.
  • AOID_AuthorizationHeader on|off
    Creates a HTTP authorization header (basic auth header) using a dummy password. This directive may be used on a per server or location level.
  • AOID_StartPage <path>
    The URL a user is redirected after successful login if no requested page is available. Default is the path defined by AOID_Realm.
  • HttpOnlyCookie
    This is the Apache process environment variable to be set (e.g. using mod_setenvif) in order to add the HttpOnly attribute to the mod_auth_oid session cookie. This flag helps to prevent session hijacking.
  • Logout
    The user session can't be invalidated at server side but mod_auth_oid may overwrite the client session cookie. This happens when the client calls the login handler path (see AOID_LoginPath) with the query (parameter in the URL) cmd=logout. See also the samle SHTML page about how to show a logout link.
Example:
# HttpOnly flag for those browser supporting this Set-Cookie attribute:
BrowserMatch              "Mozilla.*Firefox/3"  HttpOnlyCookie
BrowserMatch              "MSIE [678]{1}"       HttpOnlyCookie
BrowserMatch              "Opera/9\.[56789]{1}" HttpOnlyCookie

Log Messages

Error Codes

Error messages are written to the Apache ErrorLog. Each message is prefixed by the module name and an error code. The following error codes are used:

  • 001: A prerequisite Apache module is missing.
  • 002: User mapping hook has been enabled|disabled.
  • 003: Internal error while compiling regular expressions.
  • 004: The module has not been configured correctly and can't enforce user authentication.
  • 010: Failed to decrypt the received data.
  • 011: Failed to encrypt data (internal error).
  • 012: Received an expired session cookie.
  • 013: Received an invalid session cookie.
  • 014: HTTPS peer verification has failed.

Debug Messages

mod_auth_oid writes some debug messages to the Apache ErrorLog. These messages may help when integrating new OpenID Providers. Use the AOID_LogLevel directive to set the message severity either to debug or info.

  • AOID_LogLevel debug|info
    Defines the severity of debug messages written to Apache's error log.

Build

You may download the source code of mod_auth_oid and it supplementary modules at SourceForge.net and build the shared libraries using apxs.
Example:
cd apache2
apxs -i -c -I . -D AOID_MOD_EXT_HOOKS mod_auth_oid.c
apxs -i -c -I . mod_auth_oid_file.c


mod_auth_oid at SourceForge.net © 2009, Pascal Buchbinder