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
| off
AuthSecurID_Authoritative on
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 logs/securid_auth
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).
on
| off
AuthSecurID_SecureCookie on
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 null
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 null
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 client_ip
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_FromAgent 10.1.2.0:X-Forwarded-For/255.255.255.0 \ 10.2.3.0:null \ client_ip |
AuthSecurID_UserAgent 32
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 null
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:
# # Custom directory for WAP devices # BrowserMatch "WAP" "AuthSecurID_CustomDir=conf/securid-wap" |
See also module customization.
AuthSecurID_CustomType text/html
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:
# # Use WML files for WAP devices # BrowserMatch "WAP" "AuthSecurID_CustomType=text/vnd.wap.wml" |
on
| off
AuthSecurID_CustomSymLinks off
The AuthSecurID_CustomSymLinks
directive enables
(on
) or disables (off
, this is the default)
symlinks for custom directory and files.
on
| off
AuthSecurID_NoCache off
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 AceHandle
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 webid2
The AuthSecurID_WebidCookie
directive sets the name of the
`webid2' cookie used for SecurID authentications. name
must be a valid cookie name.
AuthSecurID_MaxAuthGet 16
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 8
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 1024
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.
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:
valid-user : |
any user authenticated by ACE/Server, |
user : |
the username used by ACE/Server, |
group : |
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.