mod_securid for Apache is an authentication module, and so a typical httpd.conf (extract) is:
# # Restrict access with SecurID # <Directory /.../private> AuthType "SecurID" require valid-user </Directory> |
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:
When all fails, check logs and read ACE docs...
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...
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 "VAR_ACE=/var/ace"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.
on | offAuthSecurID_Authoritative onSetting 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 logs/securid_authThe 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).
on | offAuthSecurID_SecureCookie onThe 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 nullThe 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 nullThe 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 client_ipOnce 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_FromAgent 10.1.2.0:X-Forwarded-For/255.255.255.0 \
10.2.3.0:null \
client_ip
|
AuthSecurID_UserAgent 32Once 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 nullThe 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:
| # # Custom directory for WAP devices # BrowserMatch "WAP" "AuthSecurID_CustomDir=conf/securid-wap" |
See also module customization.
AuthSecurID_CustomType text/htmlThe 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:
| # # Use WML files for WAP devices # BrowserMatch "WAP" "AuthSecurID_CustomType=text/vnd.wap.wml" |
on | offAuthSecurID_CustomSymLinks offThe AuthSecurID_CustomSymLinks directive enables
(on) or disables (off, this is the
default) symlinks for custom directory and files.
on | offAuthSecurID_NoCache offThe 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 AceHandleThe 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 webid2The AuthSecurID_WebidCookie directive sets the name
of the `webid2' cookie used for SecurID authentications.
name must be a valid cookie name.
AuthSecurID_MaxAuthGet 16Each 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 8Each 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 1024The 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.
Obsolete directive, not used anymore...
AuthSecurID_Proxy "libexec/securid_proxy"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 "logs/securid"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.
The AuthType directive sets the type of
authenticate. For SecurID, use AuthType "SecurID".
The require directive can be used with:
|
any user authenticated by ACE/Server, |
|
the username used by ACE/Server, |
|
the shell used by ACE/Server (iae one or more group names, separated by a comma; no whitespace is allowed between them; read ACE doc...), |
mod_securid uses 3 handlers: 2 for internal use and 1 you may use.
The 2 internal handlers are:
This is what you can see when a restricted and unauthenticated URI is accessed:
The handler you may use is:
<Location> restricts) that ends with
/securid/status will prints the authentication
status,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.
| <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> |
You may follow this template for err.0.N[.language]:
| <P> Authentication cannot be performed: raison <BR> Use BACK to retry... </P> |
You may follow this template for err.N[.language]:
| <P> Invalid authentication: raison <BR> Use BACK to retry... </P> |
Except for err.6[.language]:
| <HEAD> <META HTTP-EQUIV="Refresh" CONTENT="10; URL=%s"> </HEAD> <BODY> <P> Valid new PIN <BR> <A HREF="%s">Continue</A> </P> </BODY> |
When Next CODE or New PIN are required, "errors" values are:
You may follow this template for err.2[.language]:
| <FORM METHOD=POST ACTION="%s"> <INPUT TYPE=HIDDEN NAME=sd_action VALUE=next_code> <INPUT TYPE=HIDDEN NAME=sd_username VALUE="%s"> Tokencode: <INPUT TYPE=PASSWORD NAME=sd_passcode MAXLENGTH=32> <INPUT TYPE=HIDDEN NAME=sd_referer VALUE="%s"> </FORM> |
And do not search for "error" code next code ok because if next code is not bad, then authentication is performed.
You may follow those templates for err.5.XY[.language]:
And do not search for "error" code next code ok because if next code is not bad, then authentication is performed.
For err.5.0[.language] (system only pin):
| <FORM METHOD=POST ACTION="%s"> <INPUT TYPE=HIDDEN NAME=sd_action VALUE=new_pin_sys> <INPUT TYPE=HIDDEN NAME=sd_passcode VALUE="%s"> <INPUT TYPE=HIDDEN NAME=sd_referer VALUE="%s"> <INPUT TYPE=SUBMIT VALUE="Receive a system PIN"> </FORM> |
For err.5.1Y[.language] (user or system pin):
| Enter your New PIN: <!-- copy/paste err.5.2Y[.language] Or receive a system-generated PIN: <!-- copy/paste err.5.0[.language] |
For err.5.2Y[.language] (user only pin):
| <FORM METHOD=POST ACTION="%s"> New PIN must contain %d to %d digits/alphanumerics. <INPUT TYPE=HIDDEN NAME=sd_action VALUE=new_pin_usr> <INPUT TYPE=TEXT NAME=sd_username VALUE="%s" MAXLENGTH=32> New PIN: <INPUT TYPE=TEXT NAME=sd_passcode> <INPUT TYPE=HIDDEN NAME=sd_referer VALUE="%s"> <INPUT TYPE=SUBMIT VALUE="Send"> </FORM> |
You may follow this template for err.-5[.language]:
| <HEAD> <META HTTP-EQUIV="Refresh" CONTENT="10; URL=%s"> </HEAD> <BODY> <P> New PIN: %s <BR> <A HREF="%s">Continue</A> </P> </BODY> |
You may follow this template for status.-1[.language]:
| <P> You are not authenticated with <i>mod_securid</i>... </P> |
You may follow this template for status.0[.language]:
| <P> You were authenticated as user %s: username : %s group(s) : %s first used: %s s. ago Will see you later... </P> |
You may follow this template for status.1[.language]:
| <P> You are authenticated as user %s: username : %s group(s) : %s first used: %s s. ago expiration: in %s s. (even if you use your authentication) Use this <A HREF="%s">link</A> to logout </P> |
You may follow this template for status.2[.language]:
| <P> You are authenticated as user %s: username : %s group(s) : %s first used: %s s. ago expiration: in %s s. (if you do not use your authentication), or in %s s. Use this <A HREF="%s">link</A> to logout </P> |
You may follow this template for status.3[.language]:
| <P> You are authenticated as user %s: username : %s group(s) : %s first used: %s s. ago expiration: in %s s. (if you do not your authentication) Use this <A HREF="%s">link</A> to logout </P> |
Note: username is printed two times because first time is with $REMOTE_USER and second time is with SecurID cookie username field.
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).
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:
When using mod_securid with Apache running as a reverse proxy, there is no problem. A simple configuration could be:
# # Define a reverse proxy # ProxyPass / http://web/ ProxyPassReverse / http://web/ # # Restrict access with SecurID # <Directory proxy:http://web/> AuthType "SecurID" require valid-user </Directory> |
<Directory proxy:*> AuthType "SecurID" require valid-user </Directory> |
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:
#
# Define a standard proxy
#
ProxyRequests on
#
# As the browser is using http (not s) to talk to the proxy...
#
AuthSecurID_SecureCookie off
#
# Restrict access with SecurID for http only and relay https
#
<Directory proxy:*>
<LimitExcept CONNECT>
allow from all
</Limit>
<LimitExcept CONNECT>
AuthType "SecurID"
require valid-user
</Limit>
</Directory>
|
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.