Pubcookie Home > Documentation 
 
Pubcookie Homepage Pubcookie Apache Module
Configuration Directives
Component:  mod_pubcookie
Audience:  All
Modified:  September 20, 2006

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.


AuthType directive

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).

PubcookieInactiveExpire directive

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.

PubcookieHardExpire directive

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.

PubcookieAppID directive

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.

PubcookieDirDepthforAppID directive

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.

PubcookieCatenateAppIDs directive

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.

PubcookieAppSrvID directive

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.

PubcookieLogin directive

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.

PubcookieLoginMethod directive

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.

PubcookiePostURL directive

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.

PubcookieDomain directive

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.

PubcookieGrantingCertfile directive

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.

PubcookieSessionKeyfile directive

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.

PubcookieSessionCertfile directive

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.

PubcookieCryptKeyfile directive

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.

PubcookieKeyDir directive

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.

PubcookieEndSession directive

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.

PubcookieEncryption directive

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.

PubcookieSessionCauseReAuth directive

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.

PubcookieAuthTypeNames directive

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.

PubcookieNoPrompt directive

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.

PubcookieOnDemand directive

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.

PubcookieAddlRequest directive

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.

PubcookieNoObscureCookies directive

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.

PubcookieNoCleanCreds 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.

PubcookieEgdDevice directive

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.

PubcookieNoBlank directive

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.

PubcookieSuperDebug directive

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]
Copyright © 2002-2008 University of Washington
UW Technology Services
Pubcookie Contact Info
Modified: September 20, 2006