Introduction : The Apache OpenID Module
mod_auth_openid is an authentication module for the Apache 2 webserver. It handles the functions of an OpenID consumer as specified in the OpenID 2.0 specification. See the FAQ for more information. Download the current release from the the releases page.
You can, now, specify an external program for authorization. That is, after a user has authenticated themselves their identity can be passed to an external program that then returns a value that either authorize them or not to see the resource being protected. See AuthUserProgram for more information.
Installation
These docs assume that you have Apache 2 installed and running already. Linux is the only officially supported operating system. YMMV on OSX/Irix/Solaris/etc.
Prerequisites
- libopkele (>= 2.0): a C++ implementation of important OpenID functions - http://kin.klever.net/libopkele/
- libsqlite: SQLite C libs - http://www.sqlite.org
- libpcre: You probably already have this if you’re running apache - http://www.pcre.org/
- libcurl: You also probably have this if you’re running apache - http://curl.haxx.se/
Get The Source
You can download the current stable release from the releases page or use git to get a development release:
git clone git://github.com/bmuller/mod_auth_openid.git
Note that if you download a development release you will need current versions of the autotools installed, and you must run ./autogen.sh first before following these instructions.
Compile
Enter the mod_auth_openid directory and type:
./configure
You can use the following to see additional configuration options:
./configure --help
Then:
make
su root
make install
Verify that the module has been enabled in your ‘‘httpd.conf’’:
# note that the path to your module might be different
LoadModule authopenid_module /usr/lib/apache2/modules/mod_auth_openid.so
Depending on where you specify your AuthOpenIDDBLocation (see below), you may need to touch the db file as the user that’s running Apache (or chown the directory it’s being stored in). For instance:
# /tmp/mod_auth_openid.db is the default location for the DB
su root
touch /tmp/mod_auth_openid.db
chown www-data /tmp/mod_auth_openid.db
Usage
Place the following directive in either a Directory, Location, or File directive in your httpd.conf (or in an .htaccess file if you have AllowOverride AuthConfig):
AuthType OpenID
require valid-user
The valid-user constraint can be replaced with require user http://myopenid.com/myusername/ if you want to restrict access to a specific user.
The following are optional:
AuthOpenIDDBLocation /some/location/my_file.db
AuthOpenIDTrusted ^http://myopenid.com/server$ ^http://someprovider.com/idp$
AuthOpenIDDistrusted ^http://hackerdomain ^http://openid.microsoft.com$
AuthOpenIDUseCookie Off
AuthOpenIDTrustRoot http://example.com
AuthOpenIDCookieName example_cookie_name
AuthOpenIDLoginPage /login.html
AuthOpenIDCookieLifespan 3600 # one hour
AuthOpenIDServerName http://example.com
AuthOpenIDUserProgram /path/to/authorization/program
AuthOpenIDCookiePath /path/to/protect
AuthOpenIDSingleIdP https://www.google.com/accounts/o8/id # use Google's OpenID
AuthOpenIDAXRequire email http://axschema.org/contact/email @example\.com$
AuthOpenIDAXUsername email # username is email address
AuthOpenIDSecureCookie On # always for production sites!
- AuthOpenIDDBLocation: Specifies the place the SQLite file should be stored. Default: /tmp/mod_auth_openid.db.
- AuthOpenIDTrusted: If specified, only users using providers that match one of the (Perl compatible) regular expressions listed will be allowed to authenticate. Default: Trust all providers.
- AuthOpenIDDistrusted: If specified, only users using providers that do not match one of the (Perl compatible) regular expressions listed will be allowed to authenticate. You can use this in combination with AuthOpenIDTrusted; in that case, only a domain that is listed as trusted and not listed as distrusted can be used. Default: No providers are distrusted.
- AuthOpenIDUseCookie: If “Off”, then a session cookie will not be set on the client upon successful authentication. The page will load once; if reloaded or if the user visits it again it will ask the user to reauthenticate. Default: On
- AuthOpenIDTrustRoot: User’s are asked to approve this value by their identity provider after redirection. Most providers will error out unless this value matches the URL they are being redirected from, or some subset of that URL. For instance, if a user is trying to access http://example.com/protected/index.html then either http://example.com or http://example.com/protected/ would work but http://example.com/protected/area/ would not. Default: The URL the user is trying to access (without filenames / query parameters at the end).
- AuthOpenIDCookieName: The name of the session cookie set by mod_auth_openid. Default: open_id_session_id
- AuthOpenIDLoginPage: The URL location of a customized login page. This could be a location on a different server or domain. Default: use the mod_auth_openid login page that exists in the module. See the custom login page howto for more information.
- AuthOpenIDCookieLifespan: The number of seconds that the session cookie should live after being set. Default: If the cookie lifespan is not set than it will expire at the end of the browser session (when the browser is closed).
- AuthOpenIDServerName: If mod_auth_openid is being used behind a proxy, this option can be used to specify a hostname that will be used to create redirection URLs.
- AuthOpenIDUserProgram: A user specified program for authorization functions. Please please oh please read the documentation before using this.
- AuthOpenIDCookiePath: Explicitly set the path of the auth cookie (for instance, if you want to explicitly grant access to a location other than the one the user is trying to access).
- AuthOpenIDSingleIdP: In general, OpenID users can directly enter the identity they want to claim, or they can enter the identity of their provider, and then the provider can show some UI for choosing an identity to claim. If your site only allows a single provider, as will be the case if you’re using Google’s OpenID for authenticating users to internal sites, use the
AuthOpenIDSingleIdP <provider URL>
directive to preset it and mod_auth_openid will skip the login form entirely. Your users won’t need to remember Google’s OpenID provider identity, and they’ll have less clicking to do. - AuthOpenIDAXRequire: When you claim an OpenID through Google’s IdP, the returned OpenID looks like
https://www.google.com/accounts/o8/id?id=ABig4324Blob_ofLetters90_8And43Numbers
, which doesn’t tell you which Google Apps domain they logged in from. If you want to find out who a user is for authorization purposes, you need to use the Attribute Exchange (AX) extension to OpenID to ask the IdP for something you can check against. In the case of Google Apps, you can get their Apps username and domain by requesting their email address. TheAuthOpenIDAXRequire <alias> <URI> <regex>
lets you require some attributes identified by URIs to be returned with an OpenID response, and then validate the returned attribute against a regex. If the attribute isn’t returned with the response, or if it doesn’t match the regex, validation fails. You can have more than oneAuthOpenIDAXRequire
directive; all must pass for successful authentication. - AuthOpenIDAXUsername: As noted above, OpenIDs are not required to be pretty or even readable. You can use
AuthOpenIDAXUsername <alias>
to set Apache’sREMOTE_USER
variable to the AX attribute with that alias. This is what shows up in log files, and it’s also accessible to whatever application you’re wrapping with OpenID authentication. - AuthOpenIDSecureCookie:
AuthOpenIDSecureCookie <On|Off>
controls whether theSecure
attribute is set on your session cookies. If you’re not using HTTPS for protecting authentication information in transit (ideally for everything), you’re doing it wrong, so I was tempted to make this feature always on. However, sometimes I’m too lazy to set up SSL/TLS on local-only development boxes.
Next, restart apache:
/path/to/apache2/bin/apachectl stop
/path/to/apache2/bin/apachectl start
After a user authenticates themselves, the user’s identity will be available in the REMOTE_USER cgi environment variable. A cookie named open_id_session_id is saved to maintain each user’s session.
Upgrading
If you’re upgrading, make sure you delete the old database file before upgrading and after stopping apache (the db file is in /tmp/mod_auth_openid.db by default).
Attribute Exchange
See the AttributeExchange page for more information.
Questions/Problems/Complaints
First, read the FAQ. If it’s a bug, report it by creating a new ticket (link at top). If it’s a complaint or question, email the mailing list.