[APACHE DOCUMENTATION]

mod_securid: Reference documentation

Table of Contents


Usage

mod_securid for Apache is an authentication module, and so a typical httpd.conf (extract) is:

But first of all, mod_securid for Apache is an ACE/Client, and so you need to define the machine mod_securid is running on as an ACE/Client; here are the main steps:

  1. Create (or ajust) a client on ACE/Server with:

  2. Copy sdconf.rec from ACE/Server to the machine mod_securid is running on, under the directory set by the directive AuthSecurID_VarAce (usually called $VAR_ACE). Also delete any old Node Secret file $VAR_ACE/securid. directory.

  3. Check the new sdconf.rec with a local ACE client; 2 ways for this:

    1. The simplest way is to use an ACE/Client (sdauth for example), running as root (don't forget to set $VAR_ACE...). If your SecurID authentication is correct, then the Node Secret file $VAR_ACE/securid will be created.

    2. Another way is to make $VAR_ACE world writable (chmod 777 $VAR_ACE) and then to start Apache/mod_securid. If your SecurID authentication is correct, then the Node Secret file will also be created. Don't forget to restore the correct permissions/owner on $VAR_ACE and $VAR_ACE/securid.

    This will create the Node Secret file $VAR_ACE/securid; if this file does not exist, then ACE/Client is not yet initialized and mod_securid will not work...

  4. Adjust some SecurID files permissions
    This is because Apache has to initialize ACE communications and then need to read those files. As this initialization occurs during each user's authentication, the User/Group Apache is running on must be able to read those files.

When all fails, check logs and read ACE docs...


Module-Specific Directives

AuthSecurID_TTL

Syntax: AuthSecurID_TTL number [ always_after | if_not_used ]
Default: AuthSecurID_TTL 30 always_after
Context: server config, virtual host

The AuthSecurID_TTL directive sets the Time To Live (in minutes) for SecurID user authentications. An authentication may expire always after specified time (always_after, this is the default) or if not used for specified time (if_not_used). Default TTL is 30 (minutes). Use a TTL greater than 0...

AuthSecurID_MaxTTL

Syntax: AuthSecurID_MaxTTL number
Default: AuthSecurID_MaxTTL 0
Context: server config, virtual host

The AuthSecurID_MaxTTL directive sets the maximum Time To Live for SecurID user authentications, regardless of if_not_used in AuthSecurID_TTL directive. Default maximum TTL is 0 (minute), which means no limit...

Note 1: AuthSecurID_MaxTTL must be used after AuthSecurID_TTL;
Note 2: AuthSecurID_MaxTTL is useless when not using AuthSecurID_TTL N if_not_used...

AuthSecurID_VarAce

Syntax: AuthSecurID_VarAce "VAR_ACE=directory"
Default: AuthSecurID_VarAce "VAR_ACE=/var/ace"
Context: server config, virtual host

The AuthSecurID_VarAce directive sets the environnement (VAR_ACE) for ACE communications. You must install sdconf.rec under $VAR_ACE (see Usage).

Note for VirtualHost: mod_securid does support several ACE/Servers using VirtualHost directives and different VAR_ACE environment variables. The new design (with the securid_proxy child processes) allows this.

AuthSecurID_Authoritative

Syntax: AuthSecurID_Authoritative on | off
Default: AuthSecurID_Authoritative on
Context: directory, .htaccess

Setting the AuthSecurID_Authoritative directive explicitly to 'off' allows for both authentication and authorization to be passed on to lower level modules. Default is on.

Note: this directive is in fact useless because SecurID is not an HTTP/Basic authentication...
For HTTP/Basic, you could use:

      <Location /priv>
        # restrict access
        require valid-user
        AuthType "Basic"
        AuthName "private"
        # try file
        AuthAuthoritative off
        AuthUserFile a_file
        # or try DB
        AuthDBUserFile a_db
      </Location>
But no way to mix AuthType "Basic" and "SecurID":
      <Location /priv>
        require valid-user
        AuthType "Basic"
        AuthType "SecurID"
        ...
      </Location>
Perharps this directive should be removed... (if you have an idea, please email us).

AuthSecurID_Cache

Syntax: AuthSecurID_Cache filename [noreset]
Default: AuthSecurID_Cache logs/securid_auth
Context: server config, virtual host

The AuthSecurID_Cache directive sets the name of the file where the server caches user authentication (cookie). If the name does not begin with a slash ('/') then it is assumed to be relative to the Server Root.

The optionnal argument noreset can be used if you do not want mod_securid to reset the cache when starting (or restarting). This may be sometimes usefull (for example, several reverse-proxy/mod_securid that want to share SecurID authentications).

AuthSecurID_SecureCookie

Syntax: AuthSecurID_SecureCookie on | off
Default: AuthSecurID_SecureCookie on
Context: server config, virtual host

The AuthSecurID_SecureCookie directive enables (on, this is the default) or disables (off) "secure" cookies for SecurID authentications.

If a cookie is marked secure, it will only be transmitted if the communications channel with the host is a secure one. Currently this means that secure cookies will only be sent to HTTPS (HTTP over SSL) servers.

Note: if you use a un-secure HTTP server with mod_securid (you should not...), then you need to use "AuthSecurID_SecureCookie off".

AuthSecurID_DomainCookie

Syntax: AuthSecurID_DomainCookie .domain
Default: AuthSecurID_DomainCookie null
Context: server config, virtual host

The AuthSecurID_DomainCookie directive enables "domain" cookies for SecurID authentications. domain is a valid domainname, like toto.com (so the whole value of this directive is like .toto.com).
"domain" cookies are sent to all hostnames that belong to domain domainname, so you should use this directive carefully.

Note: domains must have at least two (2) periods in them to prevent domains of the form: ".fr", ".com", ...

AuthSecurID_PathCookie

Syntax: AuthSecurID_PathCookie path
Default: AuthSecurID_PathCookie null
Context: server config, virtual host

The AuthSecurID_PathCookie directive forces "path" cookies for SecurID authentications. path is a valid pathname, like / or /priv.

When this directive is not used, mod_securid auto-compute the path=... of the cookies used for SecurID authentications. For example, when using <Location /private/> to authenticate all the URIs beginning with /private/ with SecurID, mod_securid will then use for its cookie path=/private/.

So you should not use this directive except for some special cases.

Note: paths must begin with "/"...

AuthSecurID_FromAgent

Syntax: AuthSecurID_FromAgent [from:]key[/mask...
Default: AuthSecurID_FromAgent client_ip
Context: server config, virtual host

Once a user is authenticated, mod_securid checks that his FromAgent does not change. The default is to use the remote "agent" (client) IP address but this is not always a good idea; for example:

To solve those problems, the AuthSecurID_FromAgent directive may be used with one or several "[from:]key[/mask]", where:

Example:

AuthSecurID_UserAgent

Syntax: AuthSecurID_UserAgent length
Default: AuthSecurID_UserAgent 32
Context: server config, virtual host

Once a user is authenticated, mod_securid checks that his browser's User-Agent header does not change. The default is to truncate the value of this header because some browsers (IE...) don't always send the same User-Agent value; for example:
"Mozilla/4.0 (compatible; MSIE 5.01; Windows NT)" for "standard" requests, but
"Mozilla/4.0 (compatible; MSIE 5.0; Win32)" for "java" requests...

AuthSecurID_UserAgent sets the User-Agent's length to use. Default value is 32; this is to allow IE to work. Maximum value is 64; this is the size used by RSA in the WebID2 cookie. Minimum value is 0, which means no User-Agent checking.

Note: when mod_securid complains with the error message "invalid User-Agent" (see Authentication errors), you know you have to adjust AuthSecurID_UserAgent.

AuthSecurID_CustomDir

Syntax: AuthSecurID_CustomDir directory
Default: AuthSecurID_CustomDir null
Context: server config, virtual host

The AuthSecurID_CustomDir directive sets the name of the directory that contains the SecurID custom files. If the directory name does not begin with a slash ('/') then it is assumed to be relative to the Server Root. By default AuthSecurID_CustomDir is null, which means that custom files feature is disabled.

This directive can also be used as "environment variable", for example:

See also module customization.

AuthSecurID_CustomType

Syntax: AuthSecurID_CustomType MIME-type
Default: AuthSecurID_CustomType text/html
Context: server config, virtual host

The AuthSecurID_CustomType directive sets the Content-Type of the SecurID custom files. MIME-type must be a valid MIME type.

This directive can also be used as "environment variable", for example:

AuthSecurID_CustomSymLinks

Syntax: AuthSecurID_CustomSymLinks on | off
Default: AuthSecurID_CustomSymLinks off
Context: server config, virtual host

The AuthSecurID_CustomSymLinks directive enables (on) or disables (off, this is the default) symlinks for custom directory and files.

AuthSecurID_NoCache

Syntax: AuthSecurID_NoCache on | off
Default: AuthSecurID_NoCache off
Context: server config, virtual host

The AuthSecurID_NoCache directive enables (on) or disables (off, this is the default) browsers caching for SecurID authenticated URLs.

As SecurID (and then mod_securid) uses cookies to authenticate users, this could be a problem for proxies. A proxy (cache) does not search for a SecurID cookie to know if he may -or not- cache URLs.
So to prevent proxies caching, mod_securid adds the header "Expires: 0"; you don't have to worry about this.

But this is not enough to prevent browsers caching, and AuthSecurID_NoCache can then be used. Set to on, this directive adds the header "Pragma: no-cache" (for HTTP/1.0) or "Cache-Control: no-cache" (for HTTP/1.1).

Note: If you have some strange problems with your browser (for example: IE, talking https and downloading an URL that will be handled with an external program), don't use AuthSecurID_NoCache on...

AuthSecurID_HandleCookie

Syntax: AuthSecurID_HandleCookie name
Default: AuthSecurID_HandleCookie AceHandle
Context: server config, virtual host

The AuthSecurID_HandleCookie directive sets the name of the `AceHandle' cookie used for SecurID authentications. name must be a valid cookie name.

This directive could be usefull when you want to chain SecurID authentications. Let's imagine you are running mod_securid on a reverse-proxy and `ProxyPass' to another web server that also uses SecurID authentications. As the webid2 cookie from mod_securid is not compatible with other SecurID `webid2' cookie, you need to change its name. Same problem for `AceHandle'.

AuthSecurID_WebidCookie

Syntax: AuthSecurID_WebidCookie name
Default: AuthSecurID_WebidCookie webid2
Context: server config, virtual host

The AuthSecurID_WebidCookie directive sets the name of the `webid2' cookie used for SecurID authentications. name must be a valid cookie name.

AuthSecurID_MaxAuthGet

Syntax: AuthSecurID_MaxAuthGet number
Default: AuthSecurID_MaxAuthGet 16
Context: server config, virtual host

Each time a brand new user is authenticating, he is getting a new AceHandle cookie that is stored in authentication cache. Someone could then try to fill up the cache...

The AuthSecurID_MaxAuthGet directive sets the maximum number of AceHandle that can be stored for a from-agent. When this number is reached, a special HTML error message is returned (see err.0.3 in error responses section) and all non-authenticated entries for that from-agent are then deleted from cache.

Use 0 to disable this feature.

AuthSecurID_MaxAuthPost

Syntax: AuthSecurID_MaxAuthPost number
Default: AuthSecurID_MaxAuthPost 8
Context: server config, virtual host

Each time a user is POSTing a bad SecurID authentication to the ACE server, a counter is incremented. When this counter has reached its maximum value, a special HTML error message is returned (see err.0.4 in error responses section) and the authentication entrie is then deleted from cache.
The AuthSecurID_MaxAuthPost directive sets this maximum value to number.

Use 0 to disable this feature.

AuthSecurID_MaxCacheSize

Syntax: AuthSecurID_MaxCacheSize number
Default: AuthSecurID_MaxCacheSize 1024
Context: server config, virtual host

The better way to avoid the authentications cache to fill up is to set a hard limit. When this limit is reached, a special error message is logged (too many entries in AuthSecurID_Cache file) and new authentications cannot occur.
The AuthSecurID_MaxCacheSize directive sets this hard limit to number.

Use 0 to disable this feature.

AuthSecurID_AceTTL

Syntax: AuthSecurID_AceTTL number
Default: obsolete
Context: obsolete

Obsolete directive, not used anymore...

AuthSecurID_Proxy

Syntax: AuthSecurID_Proxy path
Default: AuthSecurID_Proxy "libexec/securid_proxy"
Context: server config

This directive sets the path to the SecurID proxy executable. It takes as only argument a path either absolute or relative to the Apache server root as set by the ServerRoot directive.

AuthSecurID_SockDir

Syntax: AuthSecurID_SockDir path
Default: AuthSecurID_SockDir "logs/securid"
Context: Server config, Virtual hosts

This directive sets the path to the directory where are stored the UNIX domain sockets used to communicate with the SecurID proxy. It takes as only argument a path either absolute or relative to the Apache server root as set by the ServerRoot directive.


Other Apache Directives

AuthType

The AuthType directive sets the type of authenticate. For SecurID, use AuthType "SecurID".

require

The require directive can be used with:


Module Handlers

mod_securid uses 3 handlers: 2 for internal use and 1 you may use.

The 2 internal handlers are:

The handler you may use is:


Module customization

Custom files are stored in the directory set by the AuthSecurID_CustomDir directive. The distribution includes some samples in the custom directory:

3 sorts of files may be customised:

language is based on the first token of the Accept-Language HTTP header value, sent by the browser (en, fr, ...). If custom_file.language is not found, then mod_securid looks for custom_file (without .language). If custom file is found, mod_securid checks its format; bad format logs an error (see Customization errors). If custom file uses a wrong format, then mod_securid prints default messages.

Authentication prompt

For authentication prompt, if auth[.language] exists, it must follow this template:
<FORM METHOD=POST ACTION="%s">
  <INPUT TYPE=HIDDEN NAME=sd_action VALUE=passcode>
  Username: <INPUT TYPE=TEXT NAME=sd_username MAXLENGTH=32>
  PASSCODE: <INPUT TYPE=PASSWORD NAME=sd_passcode MAXLENGTH=32>
  <INPUT TYPE=HIDDEN NAME=sd_referer VALUE="%s">
</FORM>
Please note that the order of "<INPUT TYPE=..." is important (because mod_securid checks this order...).
And don't forget to use two and only two %s...

Error responses

For error responses, you need to provide err.N[.language], where N is the error code.
Special error code 0 means that authentication cannot be performed (ACE server has not been called): Others valid error codes can be found in sdacmvls.h file (from ACE distribution). Authentication has been performed and errors values are:

When Next CODE or New PIN are required, "errors" values are:

Status messages

For status messages (printed by status handler, see Module Handlers), you need to provide status.N[.language], where N is an internal error code:

You can find some english and french custom files in the custom/ directory. To use those samples, you just have to copy this directory to conf/ (or whatever AuthSecurID_CustomDir is).


Logs

With "LogLevel debug", mod_securid logs a lot of debugging messages in ErrorLog. Use this to debug mod_securid, if you used -DSECURID_DEBUG during compilation.

With "LogLevel error", mod_securid logs some usefull messages:

Configuration [error]

Initialization [notice]

Initialization [warning]

Initialization [error]

Authentication [error]

Authentication [warning]

Customization [error]

Internal [emerg], [error] and [warning]


Notes for proxy

When using mod_securid with Apache running as a reverse proxy, there is no problem. A simple configuration could be:

For a standard proxy, there is no problem when relaying http. But because of SecurID cookie, you cannot relay https (if you have an idea, please email us). So a simple configuration could be:


Copyright

This module is free software; you can redistribute it and/or modify it under the same terms as Apache itself. This module is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. The copyright holder of this module can not be held liable for any general, special, incidental or consequential damages arising out of the use of the module.

Security Dynamics, the Security Dynamics logo, ACE, ACE/Server, SecurID, SoftID and WebID are registered trademarks of Security Dynamics Technologies, Inc.

All other products or services mentioned in this document are covered by the trademarks, service marks, or product names as designated by the companies who own or market them.


Apache HTTP Server Version 1.3

Index