|
The Pubcookie Apache module uses the following run-time configuration
directives:
Important Note: If you put the LoadModule and AddModule
directives for mod_pubcookie within <IfDefine HAVE_SSL> block
directives, you must do the same for other Pubcookie directives. Otherwise,
apachectl restart and apachectl configtest will fail.
Syntax: AuthType type
Context: directory, .htaccess
Compatibility: All versions of mod_pubcookie
and Apache 1.2 and later.
This directive selects the type of user authentication applied to a
resource. It must be accompanied by a require directive
when used with an authentication type handled by mod_pubcookie.
The type is case-insensitive and can be any name defined by PubcookieAuthTypeNames or supported as
an existing core AuthType (e.g.
Basic).
Syntax: PubcookieInactiveExpire
expire-time-in-seconds
Context: directory, .htaccess
Compatibility: All versions of mod_pubcookie and
Apache 1.2 and later.
The duration of inactivity allowed between a user and an application before
the session expires. Expiration due to inactivity causes a loop thru the login
server to obtain a new granting cookie.
The default value is 30 minutes which is defined as PBC_DEFAULT_INACT_EXPIRE
in pbc_config.h. Minimium inactivity timeout is five minutes.
A value of -1 turns off the check for inactivity.
Syntax: PubcookieHardExpire
expire-time-in-seconds
Context: directory, .htaccess
Compatibility: All versions of mod_pubcookie and
Apache 1.2 and later.
The maximum duration of an application session, regardless of user activity.
Expiration due to reaching the hard timeout causes a loop thru the login server
to obtain a new granting cookie.
The default value is eight hours which is defined as PBC_DEFAULT_HARD_EXPIRE
in pbc_config.h. The minimium is one hour; the maximium is twelve hours.
Syntax: PubcookieAppID application-name
Context: directory, .htaccess
Compatibility: All versions of mod_pubcookie and
Apache 1.2 and later.
The name of the application. The default is the directory path.
Use of this directive may require that you set AllowOverride
All in httpd.conf.
Syntax: PubcookieDirDepthforAppID
depth
Context: server config, virtual host
Compatibility: All versions of mod_pubcookie and
Apache 1.2 and later.
This directive causes appIDs to be defined by the depth of the
directory path requested. It allows you to limit the length of default
appIDs to a specific number of directories.
The depth is the number of directories that the appID will be truncated to.
e.g.:
| / |
0 |
| /blah/ |
1 |
| /blah/asdf/ |
2 |
Note: PubcookieDirDepthforAppID is overridden by PubcookieAppID unless PubcookieCatenateAppIDs is
enabled.
Syntax: PubcookieCatenateAppIDs on | off
Context: server config, virtual host
Compatibility: Versions of mod_pubcookie 3.3.1 and
higher Apache 1.2 and later.
This directive causes appIDs to be constructed by catenating all
configured values rather than replacing the value as subsequent
configuration is discovered.
When PubcookieCatenateAppIDs is enabled, PubcookieDirDepthforAppID and PubcookieAppID values are accumulative.
Syntax: PubcookieAppSrvID AppServerID
Context: server config, virtual host
Compatibility: All versions of mod_pubcookie and
Apache 1.2 and later.
Allows you to specify an AppSrvID string, instead of using the default based
on your ServerName.
Syntax: PubcookieLogin
url-of-login-server
Context: server config, virtual host
Compatibility: All versions of mod_pubcookie and
Apache 1.2 and later.
The location of the login cgi on the pubcookie login server.
Syntax: PubcookieLoginMethod GET | POST
Context: server config, virtual host
Compatibility: Versions of mod_pubcookie
3.2.0 and higher and Apache 1.2 and later.
This directive specifies how authentication requests and responses are
communicated between the module and the login server.
The default method, GET, is Pubcookie's classic cookie-based
messaging method. It communicates the request and response using meta-refresh
redirects and cookies scoped to the enterprise domain
(see PubcookieDomain).
The newer method, POST, is closer to the industry standard
SAML Browser/POST profile. It communicates the request and response using
HTTP POST message bodies and uses, but does not require, Javascript to
facilitate the process. It requires an additional
PubcookiePostURL endpoint to consume the
initial response sent by the login server.
All versions of the module prior to 3.2.0 can only use the GET method.
Versions 3.2.0 and higher support either method.
Syntax: PubcookiePostURL post-reply-url
Context: server config, virtual host
Compatibility: Versions of mod_pubcookie
3.2.0 and higher and Apache 1.2 and later.
This directive specifies the URL endpoint used to consume authentication
responses sent from the login server when using the POST
PubcookieLoginMethod.
The default location is /PubCookie.reply.
Syntax: PubcookieDomain domain
Context: server config, virtual host
Compatibility: Versions of mod_pubcookie 3.0.0 and
higher and Apache 1.2 and later.
The DNS domain used to scope the cookies that carry the messages in Pubcookie's classic
cookie-based messaging method. It must be at least a second level domain.
Note: Sites can use the POST-based messaging method to avoid DNS domain issues entirely.
Sites in country code top-level domains (e.g. example.ca) must do so, since browsers
don't allow cookies to be set to second level domains within country code top-level
domains. See
PubcookieLoginMethod.
Syntax: PubcookieGrantingCertfile
filename
Context: server config, virtual host
Compatibility: All versions of mod_pubcookie and
Apache 1.2 and later.
The name of the file containing the login server's certificate used to
verify granting cookies.
The default is /usr/local/pubcookie/pubcookie_granting.cert which is defined
as PBC_G_CERTFILE in pbc_config.h.
Syntax: PubcookieSessionKeyfile
filename
Context: server config, virtual host
Compatibility: All versions of mod_pubcookie and
Apache 1.2 and later.
The name of the file containing the private key for session cookies.
The default is /usr/local/pubcookie/pubcookie_session.key which is defined
as PBC_S_KEYFILE in pbc_config.h.
Syntax: PubcookieSessionCertfile
filename
Context: server config, virtual host
Compatibility: All versions of mod_pubcookie and
Apache 1.2 and later.
The name of the file containing the certificate for session cookies.
The default is /usr/local/pubcookie/pubcookie_session.cert which is defined
as PBC_S_CERTFILE in pbc_config.h.
Syntax: PubcookieCryptKeyfile filename
Context: server config, virtual host
Compatibility: All versions of mod_pubcookie and
Apache 1.2 and later
The name of the file containing the symmetric encryption key obtained
from your keyserver for encrypting/decrypting private data.
The default is /usr/local/pubcookie/c_key which is defined as
PBC_CRYPT_KEYFILE in pbc_config.h.
Syntax: PubcookieCryptKeyfile filename
Context: server config, virtual host
Compatibility: All versions of mod_pubcookie and
Apache 1.2 and later
The location of shared keys for encrypting/decrypting cookies.
Syntax: PubcookieEndSession redirect | clearLogin |
on | off
Context: directory, .htaccess
Compatibility: Versions of mod_pubcookie 1.69
and later and Apache 1.3 and later.
This directive is used to end an application session. It should be placed in
a child directory or explicitly have the same PubcookieAppID as the application it is going to affect.
(E.g., if /webapp/ defines the AuthType directive, then /webapp/logout/ would
typically be used to define PubcookieEndSession.)
With arguments on, redirect, and clearLogin the
session cookie is cleared. Re-requesting the resource will require a trip to
the login server to retrieve a new granting cookie. Note: session cookies of
other applications are not cleared by the PubcookieEndSession directive, only
the session cookie applicable to the scope of the current application.
After clearing the session cookie, the redirect and
clearLogin arguments redirect the browser back to the login server
which generates a response page. The clearLogin argument also causes
the login server to clear the user's login cookie.
The off argument turns off all PubcookieEndSession
functionality.
Syntax: PubcookieEncryption AES | DES | AES+DOMAIN
Context: directory, .htaccess
Compatibility: Versions of mod_pubcookie 3.3.0
and higher and Apache 1.2 and later.
This directive defines the encryption algorithm used by the module to
encrypt and decrypt private cookie data, including pre-session and session
cookies as well as the type of encryption it asks for and expects from the
login server for granting cookies and messages.
In version 3.3.0 and higher, AES encryption is the default (unless the module
has been built with the --enable-default-des option). The only
encryption method supported in earlier versions is DES. Therefore, you must set
this directive to use DES encryption to interoperate with login servers earlier
than version 3.3.0.
The AES+DOMAIN setting enables the module's
wildcard subdomain
capability.
Syntax: PubcookieSessionCauseReAuth on | off | grace-time-in-seconds
Context: directory, .htaccess
Compatibility: All versions of mod_pubcookie
and Apache 1.2 and later. mod_pubcookie version 3.1 and above required for grace time.
When set to on, the PubcookieSessionCauseReAuth directive causes the
user to be reauthenticated, thus overriding single sign-on. Users must re-enter
valid credentials to establish an application session.
Use a grace-time-in-seconds to indicate a grace time wherein no reauthentication
is necessary (e.g., 1800 for 30 minutes of grace time). This feature allows
an application to establish an acceptable balance between convenience and risk.
Syntax: PubcookieAuthTypeNames name1 [name2
...]
Context: server config, virtual host, directory
Compatibility: Versions of mod_pubcookie 1.77
and higher and Apache 1.3 and later.
This directive names the new authentication types added by
mod_pubcookie to the AuthType directive. For
example, PubcookieAuthTypeNames EGNetID allows you to use
AuthType EGNetID.
The ordered list of the names maps each new authentication type
directly to an intrinsic Pubcookie credential type: name1 is
credential type "1", name2 is credential type "2", and so on.
This is how Pubcookie ties each AuthType to a different "login flavor"
handled by the login server. Of course, most sites have only one login
flavor, the basic flavor, and therefore only need to specify one name.
Note: if necessary, a value of null can be used to define an
unused position in the ordered list of PubcookieAuthTypeNames.
PubcookieAuthTypeNames is required in mod_pubcookie 1.77 and
higher. All users upgrading to mod_pubcookie 1.77 or higher must add this
directive to their server configuration.
Syntax: PubcookieNoPrompt on | off
Context: directory, .htaccess
Override: AuthConfig
Compatibility: mod_pubcookie 3.1 and later;
it also requires a 3.1 or later login server
This directive prevents the login server from displaying the login
page, while still allowing single sign-on to the resource if the user has
already logged in.
If the user already has a valid login cookie they will be logged in
normally: i.e., returned to the application and given a standard session
cookie. If, on the other hand, they do not have a valid login cookie they
will be silently returned to the application (i.e., they won't be prompted
to log in) and given a session cookie with a blank id.
The AUTH_TYPE and REMOTE_USER environment variables will be set only if
the user has a valid login cookie, thus taking advantage of the no-prompt
option and single sign-on. These environment variables will not be set
(just like any other unauthenticated request) if the user has no valid
login cookie.
Notes: Users may find sites behave inconsistently when the no-prompt
option is in use, not realzing that the behavior depends on whether
they've already logged in. Also, because a session cookie with the blank
id is established when the user hasn't already logged in, the session will
remain anonymous for the duration of the session, even if the user
subsequently logs in elsewhere.
Syntax: PubcookieOnDemand key
directive1 directive2...
Context: directory, .htaccess
Override: AuthConfig
Compatibility: mod_pubcookie 3.1 and later;
it also requires a 3.1 or later login server
This directive controls the module's on-demand functionality.
Directives used on demand are normally quiescent and have no effect.
Only the presence of the activation cookie, OnDemandKey, with a
value matching the key, activates the associated on-demand
directives (directive1, directive2...) and sets the environment
variable ON_DEMAND_KEY to the active on-demand key. The activation cookie
must accompany each request for resource to be protected on demand.
The following directives can be used on demand (i.e. can be tied
to, and activated by, an on-demand key):
- AuthType
- Require
- PubcookieInactiveExpire
- PubcookieHardExpire
- PubcookieAppID
- PubcookieEndSession
- PubcookieSessionCauseReAuth
- PubcookieAddlRequest
- PubcookieNoPrompt
Activated PubcookieOnDemand directives will overrule any equivalent
directives specified elsewhere.
Notes: The activation cookie, OnDemandKey, and its key value
are plain text. Applications must query the ON_DEMAND_KEY environment
variable to make sure the remote user is authenticated and authorized
according to the desired on-demand key. Therefore, applications must also
allow for, and adjust to, missing or null REMOTE_USER and ON_DEMAND_KEY
environment variables.
Syntax: PubcookieAddlRequest
opt1=val1 [opt2=val2...]
Context: directory, .htaccess
Compatibility: Versions of mod_pubcookie
3.0 and higher and Apache 1.3 and later.
This directive allows the application to give arbitrary requests to
the login server. The directive causes the following options to be
sent to the login server along with authentication requests.
Currently, it is site-defined what options cause what sort of
responses from the login server and how these responses are
returned. Eventually, there will be a standardized mechanism for
returning answers. Likely they will be returned in extensions to the
granting response and set as environment variables.
Syntax: PubcookieNoObscureCookies on | off
Context: server config, virtual host
Compatibility: Versions of mod_pubcookie
3.2.1 and higher and Apache 1.3 and later.
By default, session cookies are obscured by the module before being
exposed to other handlers. To hand session cookies to other handlers (such
as CGI programs) set this directive.
Syntax: PubcookieNoCleanCreds on | off
Context: server config, virtual host
Compatibility: Versions of mod_pubcookie
3.3.2 and higher and Apache 1.3 and later.
By default mod_pubcookie runs a cleanup at the end of the request to
remove all credentials left by flavor_getcred. With this directive
enabled all credentials are left in place. This would be needed for an
application having running mod_pubcookie for authentication only, and
leaving all session handling to the application itself, thus not having
mod_pubcookie in the handler stack.
Syntax: PubcookieEgdDevice location
Context: server config, virtual host
Compatibility: Versions of mod_pubcookie
3.0 and higher and Apache 1.3 and later.
Location of EGD socket (e.g. /dev/egd-pool) if your system lacks entropy.
Syntax: PubCookieNoBlank on | off
Context: server config, virtual host
Compatibility: Versions of mod_pubcookie
3.0 and higher and Apache 1.3 and later.
This directive is deprecated in versions 3.2.1 and higher. Use the PubcookieNoObscureCookies directive
instead.
Syntax: PubcookieSuperDebug on | off
Context: directory, .htaccess
Compatibility: All versions of mod_pubcookie
and Apache 1.2 and later.
This directive is deprecated in version 3.0.0 and higher. Use the LogLevel
directive for debugging.
|
![[Pubcookie Home Page]](/img/41x35-rings-only.gif){kind=small}
