mod_auth_oid

mod_auth_oid
 

mod_auth_oid is an Apache 2.2 module implementing an OpenID 2.0 Relying Party (RP). It may be used to enable Apache based applications 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 (OP) without using third party libraries. 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 Apache 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:
1) The user requests an URL which is restricted to authenticated users.
2) The user is redirected to the login handler of mod_auth_oid.
4) mod_auth_oid presents a login page (HTML page with a login form).
5) The user sends his OpenID identity (HTTP reference) to mod_auth_oid.
6) - 9) mod_auth_oid discovers and establishs the associations with the OP.
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.
12) The OP redirects the user back to mod_auth_oid. This redirect includes the assertion created by the OP.
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 (and all other resources within the defined realm) until the authentication session cookie expires.

Configuration

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

The following steps are necessary to configure mod_auth_oid:

  • Base Server Settings
    Settings for communication to the OpenID Provider.
  • Realm
    Defines the URL name space a user is authorized to access after successful authentication.
  • User Mapping
    The OpenID identity must be mapped to a user id known by the application. Serveral mapping techniques are supported by mod_auth_oid.
  • Access Control
    User authentication is enforced by standard Apache directives such as Require. This configuration step is mandatory in order to enforce user authentication!
And theses sections describe optional settings:
  • Options
    Optional parameters of mod_auth_oid.
  • Variables
    Variables to be used within SSI pages.

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, see step "6)" to "9)" in the overview above. 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

# Optional (but highly recommended) is the CRL verification to validate
# the provides certificate using mod_ssl or mod_sslcrl
SSLProxyVerify            require
SSLProxyCheckPeerExpire   on
SSLProxyCARevocationFile  ssl/crl.pem

Realm

The realm defines the path (URL) a user has been authenticated to. A user can't access an URL 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, processed by mod_auth_oid, containing the required login form. The document's name (file name) must be equal to the base name of the login path plus the suffix defined by the AOID_LoginSuffix, see also the example below.

  • AOID_Realm <path>
    Specifies the path of URLs within the realm. Default is the path "/".
    You may override the path setting made by this directive by setting another path using the environment variable AOID_Realm.
  • 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.
    You may override the path setting made by this directive by setting another path using the environment variable AOID_LoginPath.
  • 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 login page may be an SHTML document processed by mod_include. mod_auth_oid sets 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 has tried to request, see step "1)" and "15)" in the overview above. 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.
    • aoid_logout is set if the user as a valid authentication session. It may be used to add a conditional logout link to the page.
Example:
# Allows authenticated users to access 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, has the name "login.shtml" and is located in the
# directory "/aoid" within the servers DocumentRoot.
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, see step "14)" in the overview. The login process is only successful, if a valid user mapping is available for the provided OpenID.

Apache Configuration

mod_auth_oid implements static user id mapping using the AOID_User* directives. The directives are set within the Apache configuration. A graceful 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.
  • AOID_UserPattern <regex> <local id>
    You may use a pattern matching alorithm if you use a dedicated OpenID Provider (your own provider instance) with a well defined pattern for the allowd OpenID identity names. This directive matches the defined regular expression against the OpenID identity and creates a new local user id. mod_auth_oid will recognize occurrences of $1..$9 within the local value and replace them by parenthesized subexpressions of the regular expression.
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

# Or using a pattern (one char of the first-name and two chars of the 
# surname, e.g. https://my.company.com/carol.green is mapped to cgr):
AOID_UserPattern          "^https://my\.company\.com/([a-z]{1})[a-z]+\.([a-z]{2})[a-z]+$" "$1$2"

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 the mapping 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.
  • LDAP
    The mod_auth_oid_ldap module uses an LDAP directory for OpenID to local user id mapping. It's part of the mod_auth_oid source package.

Writing Your Own Mapping Module

You may implement your own Apache module implementing user mapping. The hook of this module is called by mod_auth_oid in order to retrieve the local user id.
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 DECLINED 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 is enforced using the Apache directives AuthType and Require. The authentication type "OpenID" delegates authentication to mod_auth_oid. 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>
Please pay attention to the fact that the login page must be accessible without authentication. Use the Satisfy any directive on the login location if you enable access control on a upper (e.g., "/") 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.html
<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_CookieName <string>
    Name of the session cookie. Default is "aoid_s".
  • 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.
    Note: you may use mod_setenvifplus if you want to build any custom HTTP request headers propagating the user's identity to the application. See also the aoid_local_user variable below.
  • AOID_StartPage <path>
    The URL a user is redirected after successful login if no requested page is available. Default is the path defined by the AOID_Realm directive.
  • HttpOnlyCookie
    This is the Apache process environment variable to be set (e.g. using mod_setenvif or mod_setenvifplus) in order to add the HttpOnly attribute to the mod_auth_oid session cookie. This flag helps to prevent session hijacking.
  • SecureCookie
    If this Apache process environment variable has been set, the "secure" attribute is added to the session cookie which allows the usage of the cookie for HTTPS connections only (and not for HTTP).
  • Logout
    The user session can't be invalidated at server side but mod_auth_oid may overwrite the session cookie stored at the client. This happens when the client calls the login handler path (see AOID_LoginPath) with the query (parameter in the URL) cmd=logout.
    Example: /aoid/login?cmd=logout.
    See also the samle SHTML page about how to show a logout link.
  • auth-oid-info handler
    This handler may be used to determine the users OpenID for OpenID providers supporting idenity selection only (e.g. Google). Call the handler providing the OpenID provider URL within the get_openid_identifier parameter in order to start an OpenID login process to display your claimed id. The claimed id is set to the get_openid_identifier variable which may be displayed within a SHTML page.
Example:
# The client get redirected to ths URL after successful login if no "requested page" is available.
AOID_StartPage            /welcome.do

# HttpOnly flag for those browser supporting this Set-Cookie attribute:
BrowserMatch              "Mozilla.*Firefox/(3|4)" HttpOnlyCookie
BrowserMatch              "MSIE [6789]"            HttpOnlyCookie
BrowserMatch              "Opera/(10|9\.[56789])"  HttpOnlyCookie

# viewer to determine your OpenID
<Location /register>
   SetHandler             auth-oid-info      
   SetEnvIf               Request_Method GET  parp
   Options                Includes
   AddType                text/html .shtml
   AddOutputFilter        INCLUDES .shtml
</Location>

Variables

The following Apache environment variables (see also mod_setenvif or mod_setenvifplus about further possibilities of variable processing) are set by mod_auth_oid:

  • REDIRECT_ERROR_NOTES stores an optional error message after a failed login attempt which describes the reason for a failed login.
  • aoid_redirect_to stores the requested page a user has tried to open.
  • aoid_logout may be used within the login SHTML page to determin if a logout link/button should be displayed.
  • aoid_local_user stores the local user id of the authenticated user.

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:

  • mod_auth_oid(001): A prerequisite Apache module is missing.
  • mod_auth_oid(002): User mapping hook has been enabled|disabled.
  • mod_auth_oid(003): Internal error while compiling regular expressions.
  • mod_auth_oid(004): The module has not been configured correctly and can't enforce user authentication.
  • mod_auth_oid(010): Failed to decrypt the received data.
  • mod_auth_oid(011): Failed to encrypt data (internal error).
  • mod_auth_oid(012): Received an expired session cookie.
  • mod_auth_oid(013): Received an invalid session cookie.
  • mod_auth_oid(014): HTTPS peer verification has failed.
  • mod_auth_oid(015): Reason why the user has been redirected to the login page.
  • mod_auth_oid(016): Message written by the auth-oid-info handler.

Debug Messages

mod_auth_oid writes some debug messages to the Apache ErrorLog. These messages may be helpful 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 its 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 -lcrypto
apxs -i -c -I . mod_auth_oid_file.c


mod_auth_oid at SourceForge.net © 2009-2014, Pascal Buchbinder / Christoph Steigmeier