Overview
This guide helps site
administrators run a Pubcookie login server. Everything from setup and configuration to integration and customization is covered below.
Application server administrators should refer to the Pubcookie Apache module guide or ISAPI filter guide for instructions on deploying a Pubcookie application server which authenticates using your local login server.
What’s New
Significant improvements and changes to the login server components included in Pubcookie 3.3.4:
- Added support for 4096-bit private keys to login cgi.
- Modified login cgi to log user’s IP address on Redirect log line.
Significant improvements and changes to the login server components included in Pubcookie 3.3.2d:
- Applied security fixes to address vulnerability described in June 28, 2007 security advisory.
Significant improvements and changes to the login server components included in Pubcookie 3.3.2c:
- Fixed strlcpy.c bug. Pubcookie’s implementation of strlcpy.c had a null termination bug when the source string (length – 1) exactly fits the destination string buffer.
- Fixed Javascript call in login cgi when posting data back to the application server. Added ‘()’ to document.query.submit.
Significant improvements and changes to the login server components included in Pubcookie 3.3.2:
- Added LDAPS support to LDAP verifier. Enable it with new ldap_tls config file variable. Configure TLS authentication with new ldap_key_file, ldap_cert_file, and ldap_ca_file variables.
- Fixed a bug to avoid a possible loop condition with unexpired PBC_CLEAR_COOKIE cookies.
Significant improvements and changes to the login server components included in Pubcookie 3.3.1:
- New default login CGI templates with more standard XHTML, CSS, and utf-8 encoding.
- Added clear_username_at_logout site policy to login cgi to control whether the username is cleared on logout.
- Modified session reauthentication messaging. The login cgi now includes in the granting message whether or not it handled a reauthentication request.
- Fixed null pointer usage in LDAP verifier when version is empty.
- Modified login cgi to use more consistent audit logging strings. Prepended the “first kiss” timestamp to authentication success and failure log file messages.
- Modified login cgi to allow ‘http:’ and ‘https:’ in app server uri query strings without percent encoding the colon.
Significant improvements and changes to the login server components included in Pubcookie 3.3.0a:
- Applied security fixes to address vulnerabilities described in March 6, 2006 security advisory.
- Fixed problems found in 3.3.0 release with “getcred” flavor’s Kerberos ticket passing.
Significant improvements and changes to the login server components included in Pubcookie 3.3.0:
- Added AES encryption support. The login cgi will encrypt authentication messages with the encryption algorithm specified in the authentication request.
- Changed login cgi to use AES encryption on its private login cookies.
- Added PUBCOOKIE_LOGIN_CONFIG_FILE environment variable for defining an alternate config file for the login cgi.
- Added support for the Apache module’s wildcard subdomain key encryption mode for large multi-user web-hosting environments.
- Added kerberos5_extralife config file variable to extend the lifetime of delegated tickets past the SSO lifetime.
- Added lowercase_username and uppercase_username site policies to the login cgi for modifying the case of the username.
- Modified minimum LDAP_VENDOR_VERSION in configure script for better compatibility with Sun LDAP SDK.
- Better handling of stray, malicious, and other spurious cookies. The login cgi will read all available login cookies to find a valid one. Previously, it only checked the first one, which might be invalid.
- Other minor login cgi fixes to error handling and cookie clearing.
See
doc/CHANGES.txt for bug fixes and other improvements.
Upgrading & Compatibility
In general, the login server components can be upgraded (built and installed) on a live system while safely maintaining your existing configuration file (
PREFIX/config) and login templates (
PREFIX/login_templates).
Running
make install on such a system will do the following:
- install new keyserver, keyclient, and login cgi binaries into PREFIX/keyserver, PREFIX/keyclient, and PREFIX/login/index.cgi, respectively.
- install a set of (possibly updated) generic login templates is installed into PREFIX/login_templates.default but not into PREFIX/login_templates if it already exists.
- install a new sample configuration file (PREFIX/config.login.sample).
Sites should compare their current config file and current templates against the new ones and resolve significant differences before copying the new login cgi and other binaries in production locations.
Here are some additional compatibility notes for upgrading between specific versions:
- Upgrading to 3.3.4:
- User’s IP address added to Redirect log line: Sites that parse the login cgi’s log file data should be aware that the user’s IP address has been added to support additional business purposes (e.g. usage metrics, forensics, troubleshooting). Any scripts or programs that depend on the format of this data should be tested for compatibility prior to deploying the new version.
- Upgrading to 3.3:
- AES encryption impact on SSO: Sites upgrading to 3.3 should be aware that in version 3.3 the login cgi uses AES encryption on all login cookies, while earlier versions have used DES encryption. As a result, login cookies obtained by users prior to upgrading the login cgi will be invalid after the upgrade. This will affect some users’ SSO experience in the following ways: first, after the upgrade some users will have to reauthenticate where they might not have had to before; others might notice that the login page no longer remembers (i.e. no longer pre-fills) their username. Again, this is only around the time of the upgrade and only for browsing sessions that were started before the upgrade occurs.
- Upgrading from version 3.2 to 3.3:
- Template changes: The only template changes between versions 3.2 and 3.3 are those from the February 2006 login server security patch release. Therefore, sites upgrading an unpatched 3.2 login server (3.2.1a or earlier) to a patched 3.3 login server (3.3.0a or higher) should update their templates accordingly. Namely, explicit Content-Type definitions have been added to the following templates: error, login, nonpost_redirect, notok, status, pinit_response1, and logout_part1. Also, the entire HTML comment containing an unnecessary %url% variable substitution was removed from the nonpost_redirecttemplate. These files can all be found in PREFIX/login_templates.default.Sites upgrading to 3.3 from the patched 3.2.1b release or from a manually patched 3.2 version should already have these template changes as they are part of the patch.
- Upgrading from version 3.0/3.1 to 3.3:
- Template changes: Sites upgrading from 3.0/3.1 to version 3.3 must update their templates to account for changes that were introduced in versions 3.2 and carried into 3.3, as well as for those from the February 2006 login server security patch release. As noted above, the patch release updated to the following templates: error, login, nonpost_redirect, notok, status, pinit_response1, and logout_part1. These changes are on top of those from version 3.2, which introduced new variable substitutions in several templates. Sites should identify these substitutions by comparing these templates relative to their own production templates:
- login (adds new %reason% and %version% variables)
- form_expired (adds new %time variable)
- logout_part2 (adds new %version% variable)
- pinit_response2 (adds new %version% variable)
The following templates are new (in version 3.2, and therefore in 3.3) and should be reviewed and added to your production templates:
- notok, notok_badagent, notok_form_multipart, notok_generic, notok_need_ssl
Finally, the following templates have been removed (in version 3.2, and therefore in 3.3) and therefore can be removed from your production template directory after upgrading:
- Compatibility note on version 3.1 relays:
- Third-party relays deprecated: The need for the cgi-based relays introduced in version 3.1 to authenticate across DNS domains was redressed by the POST-based messaging method introduced in version 3.2 and, thenceforth, use of third-party 3.1 relays has been deprecated. To continue to support third-party relays at all, you must use the --enable-unsafe-relay configure option while building the login cgi. Preferably, upgrade all your application servers using third-party relays to version 3.2 or higher, and configure them to use the POST-based messaging method. Then there will be no need to support third-party relays in your login cgi.
System Components
The Pubcookie login server really consists of two separate components with separate purposes:
- login server cgi
- The Pubcookie login server uses a CGI program to handle browser requests. This CGI program, hereafter referred to as the login cgi or index.cgi, is compiled from C and is a site’s central Pubcookie component. End-users rely on it to authenticate; application servers rely on it for authentication assertions. The login cgi is typically powered by Apache HTTP Server software.
- keyserver
- The Pubcookie login server uses the keyserver component to generate and distribute symmetric encryption keys for participating servers, including your Pubcookie login server and all application servers. The keyserver runs as a service under inetd or xinetd.
Basic Login Flavor
The login cgi supports an abstraction called a
login flavor. A login flavor encapsulates a specific set of functionality and features that influence how and when end-user authentication takes place.
The distribution comes with one login flavor called the
basic login flavor. This login flavor has a rich feature set, including single sign-on (SSO) user authentication, a pluggable backend authentication service interface, kiosk mode, and much more.
This guide might, in fact, be described as a guide to the basic login flavor, it is so tailored to its installation and use.
Authentication Types
What the login cgi calls a
login flavor, the application server components call an
authentication type. The naming is rooted in Apache’s
AuthType directive and it’s somewhat regrettable since they aren’t quite the same thing.
For now it’s probably enough to say that, unless you build another login flavor, most application servers will be configured with a single choice of Pubcookie authentication types, one corresponding directly with the basic login flavor.
How primary authentication takes place (that is, how usernames and passwords are actually authenticated) depends on how the basic login flavor verifies credentials with your backend authentication service.
Verifiers & Authentication Services
The basic login flavor performs username-and-password credential verification through a simple pluggable interface to backend authentication services. These plug-ins are called
verifiers and the distribution comes with several:
- kerberos_v5
- verifies credentials using a Kerberos 5 KDC
- ldap
- verifies credentials using an LDAP server
- shadow
- verifies credentials using /etc/shadow
- fork
- verifies credentials using custom forked program
- alwaystrue
- verifies all credentials as successful. good for testing.
Compile-time decisions and run-time configuration determines which verifier is used by basic login flavor.
More About Abstractions
These login cgi abstractions help applications to remain independent of the method, or methods, used by the login server to authenticate user credentials.
For example, a site might migrate from LDAP-based authentication to Kerberos authentication. It’s attractive to hide the transition from applications. Here applications would continue to use their institutional “netid” authentication type, corresponding with their site’s basic login flavor, while the login server administrators transition, transparently, from one verifier to another.
Other sites may want to be able to choose from different backend authentication services. For example, the University of Washington uses the basic login flavor along side and a more secure flavor that uses SecurID in addition to username and password for primary authentication. Applications choose which flavor they want by configuring the appropriate authentication type.
Building Components
The
configure script included in the distribution helps you build and install the login cgi and keyserver according to your platform and individual preferences.
To build and install a barebones login server for evaluation and testing, run the following commands:
$ ./configure --enable-login --disable-apache
$ make
$ make install
This builds the login cgi with support for the basic flavor and the “alwaystrue” verifier. It also builds the keyserver and keyclient binaries.
Files are installed, and directories created, according to the default installation directory prefix, henceforth called
PREFIX, which defaults to
/usr/local/pubcookie. Use the
--prefix configure option to define an alternative location.
Review the results by listing the installation
PREFIX directory contents.
$ ls
total 240
-rw-r--r-- root root 935 config # config file
-rw-r--r-- root root 935 config.login.sample # sample config
-rwxr-xr-x root root 92229 keyclient* # keyclient
drwxr-xr-x root root 4096 keys/ # keystore
-rwxr-xr-x root root 92929 keyserver* # keyserver
drwxr-xr-x root root 4096 login/ # login cgi dir
drwxr-xr-x root root 4096 login_templates/ # templates
drwxr-xr-x root root 4096 login_templates.default/ # originals
-rw-r--r-- root root 2048 starter.key # starter key
$ ls login
total 204
drwxr-xr-x root root 4096 images/ # images
-rwxr-xr-x root root 99299 index.cgi* # login cgi
Note: initial file permissions assigned by the installation process may not be acceptable for production use. Please refer to Appendix B: Permissions & Security section for a discussion of this subject.
Continue through the setup and configration instructions using the alwaystrue verifier. After you’ve gained some familiarity with a working system, you can rebuild the login cgi to use a different verifier that goes against your local authentication service. Review the configure help for the build options.
$ ./configure --help
Refer also to the Kerberos, LDAP, and FastCGI configuration sections.
SSL & Granting Key Pairs
SSL key pairs have several functions in the operation of a Pubcookie login server. One key pair may suffice for all of them, but two key pairs often works better in practice.
SSL key pair:
The SSL private key and certificate used to SSL-enable Apache can be reused for the first keypair. This key pair is particularly suited for use with the keyclient and keyserver because the SSL public key certificate most likely has been signed and issued by a trusted Certificate Authority. The login cgi also uses this key pair, but only for signing and verifying “login” cookies.
Note: the login cgi and keyserver cannot read encrypted RSA private keys because they can’t prompt for the passphrase. To reuse an encrypted SSL key, you’ll first have to remove the passphrase. Refer to Appendix C: OpenSSL Commands for help.
The
ssl_key_file and
ssl_cert_file config file variables will point to these keys.
Granting key pair:
A second key pair is used to sign and verify “granting” cookies, the authentication assertions generated and signed by the login cgi and verified by application servers. Here the certificate issuer isn’t important, but the SSL public key certificate must be distributed to other servers. Therefore, a separate “granting” key pair is often used. Refer to Appendix C: OpenSSL Commands if you need help generating this key pair.
The
granting_cert_file and
granting_key_file config file variables will point to these keys.
Note: the key pairs described in this section (used for SSL and message signing primarily) are in addition to the symmetric encryption keys Pubcookie uses for data encryption.
Run-Time Config File Setup
The login cgi and keyserver read configuration settings from a run-time configuration file. The default location,
PREFIX/config, is compiled in by default.
The login cgi will use an alternate config file if a
PUBCOOKIE_LOGIN_CONFIG_FILE environment variable defines one. This is useful when more than one logical login server is running on the same machine (using virutal hosts in Apache).
The keyserver will use an alternate config file if the
-f <filename> command-line option defines one.
The config file format is one variable name-value pair per line, except where a trailing backslash
character continues a value to the next line.
A sample config file appropriate for a login server is provided (see
PREFIX/config or
PREFIX/config.login.sample if you’re upgrading) as a starting point. It will look something like this:
# 1 is a good starting point
logging_level: 1
# the credential verifier used by the basic flavor
basic_verifier: alwaystrue
# SSL session keypair
ssl_key_file: /etc/httpd/conf/ssl.key/server.key
ssl_cert_file: /etc/httpd/conf/ssl.crt/server.crt
# granting keypair
granting_key_file: /usr/local/pubcookie/keys/pubcookie_granting.key
granting_cert_file: /usr/local/pubcookie/keys/pubcookie_granting.cert
# login server config
login_uri: https://login.example.edu/
login_host: login.example.edu
enterprise_domain: .example.edu
logout_prog: /logout/index.cgi
# keyserver config
keymgt_uri: https://login.example.edu:2222
keyserver_client_list: login.example.edu trusted.example.edu
ssl_ca_file: /etc/httpd/conf/ssl.crt/ca-bundle.crt
# site-specific policies
default_l_expire: 8h
Begin editing your config file, using the config file variable reference as needed for examples and descriptions.
Notes:
- See how several variables in the example above are derived from the login server name, login.example.edu. This will be true for your config file too.
- The example login server appears to be reusing its SSL key pair located in server.key and server.crt.
- The example login server has a separate “granting” key pair. Refer to Appendix C: OpenSSL Commands if you need help generating this key pair.
- The example keyserver appears to be using a file bundle of trusted Certificate Authorities (i.e., ca-bundle.crt). This file must contain all the trusted CA root certificates the site is using to verify keyclient certificates.
Keyserver Setup
Keyserver is designed to run as a service under inetd or xinetd.
If you use inetd, add a line like the following to
/etc/inetd.conf:
2222 stream tcp nowait root /usr/local/pubcookie/keyserver keyserver
If you use xinetd, create
/etc/xinetd.d/keyserver with the following contents:
# description: pubcookie keyserver
service keyserver
{
type = UNLISTED
protocol = tcp
port = 2222
disable = no
socket_type = stream
wait = no
user = root
group = tty
server = /usr/local/pubcookie/keyserver
}
After adding the line to inetd.conf, or the file to xinetd, restart your inetd or xinetd service.
Note: keyserver requires
ssl_key_file and
ssl_cert_file, and either
ssl_ca_file or
ssl_ca_path depending on how you handle trusted root CA certificates. Keyserver also uses
granting_cert_file for distributing your “granting” certificate. And if you want control over which hosts can request keys, you can do so by defining a
keyserver_client_list for authorizing new hosts.
Key Management Methodology
This section describes how symmetric encryption keys are managed by the Pubcookie keyserver. It issues keys to all participating servers, including all login servers and application servers.
The keystore:
A master copy of each 2048-byte host key is stored on the login server in its keystore,
PREFIX/keys, in a filename based on the server’s SSL certificate’s Common Name. For example, a site with a login server and three application servers might have a keystore like this:
$ ls /usr/local/pubcookie/keys
total 204
-rw-r--r-- root root 2048 weblogin.example.edu
-rw-r--r-- root root 2048 appserver.example.edu
-rw-r--r-- root root 2048 mail.example.edu
-rw-r--r-- root root 2048 my.example.edu
-rw-r--r-- root root 887 pubcookie_granting.key
-rw-r--r-- root root 1224 pubcookie_granting.cert
Each host key can be used for DES encryption or AES encryption. The login cgi (as of version 3.3) uses AES encryption for login cookies. It uses either AES or DES for granting cookies, depending on the algorithm specified by the application server in its authentication request.
New key generation:
New host keys are generated and issued by the keyserver upon request. Running keyclient on a host initiates the request. If the keyclient host is authorized, and the keyclient and keyserver trust each other, the request is fulfilled.
New keyclient host authorization:
If the
keyserver_client_list config variable is set, keyserver performs authorization on all keyclient requests. If it is not set, keyserver will issue host keys to any trusted keyclient.
When authorization is enabled, grant-or-deny decisions are based on the presence a host in the keystore. If keyserver finds a host in the keystore, then that host can request a key. This seems like a catch-22:
to create a new host key in the keystore, the key must already exist in the keystore. But it’s not: site administrators can use the keyclient’s “permit” option to authorize new servers to request host keys. For example:
$ keyclient -P new.example.edu
Host new.example.edu is permitted
This can be done manually by the login server administrator or by some kind of automated web-based registration service. The
keyserver_client_list defines which hosts are authorized to use the permit option, allowing you to authorize new hosts without necessarily having to log in to the login server to do so.
Trust: SSL/TLS mutual authentication
Pubcookie uses elements of Public-Key Infrastructure (PKI) and SSL/TLS for mutual server authentication and data privacy between keyclient and keyserver. Trust is anchored by the Certificate Authorities used to sign, issue, and verify the certificates exchanged during keyclient connections.
Mutual authentication means the keyclient and keyserver must identify each other. The keyclient must verify the SSL certificate presented by the keyserver. Likewise, the keyserver must verify the SSL certificates presented by keyclients. To do so, they both require trusted CA root certificates to do the verification. This is configured via
ssl_ca_file or
ssl_ca_path, which might point to your own institutional CA root certificate or pehaps the CA root certificate bundle that comes with OpenSSL, whatever you happen to be basing your trust policy on.
Working with untrusted keyclients:
An untrusted keyclient is one using a SSL certificate signed by a Certificate Authority the keyserver doesn’t trust. To allow such keyclients to request host keys without having to obtain another certificate, there’s a workaround. The login server administrator can cache the keyclient’s SSL certificate (public key) in the keystore. The keyserver can then use the public key itself to verify the keyclient. As a result, an otherwise untrusted keyclient can request host keys without changing the overall CA trust policy and configuration.
Note: the keyclient’s
-U cert_file option will upload a certificate to the keyserver, e.g.:
$ ./keyclient -U untrusted.example.edu.crt
This command can only be run from a trusted host, i.e. in the
keyserver_client_list list.
Run Keyclient For Login Server
To generate a symmetric encryption key for your login server, copy the starter key found in the distribution into your keystore. Use your
login_host name for the filename. For example:
$ cd /usr/local/pubcookie
$ cp starter.key keys/login.example.edu
The starter key allows keyserver to initialize when the keystore would otherwise be empty. Now you should be able to run keyclient to request a new host key for the login server based on your current config file settings:
$ ./keyclient
Set crypt key for login.example.edu
Note: if keyclient is unable to set a new host key, look in syslog for keyserver error messages.
Deploying Login CGI
The login cgi doesn’t depend on its own filename or location, so your primary concern in deploying it should be to create a simple URL that’s easy for users to recognize and trust with their password.
The most common approach is to copy it from
PREFIX/login/index.cgi to your Apache server’s root directory, resulting in a URL such as
https://weblogin.example.edu/.
The default HTML templates use relative links to locate the default stylesheet and inline images. These files are found in a
media subdirectory. Copy the
PREFIX/login/media directory to the same location as the login cgi. It should include one stylesheet file and three GIF images.
Refer to Appendix A: Apache Configuration if you’re unfamiliar with the directives that control how Apache detects and handles cgi scripts, particularly as a directory index like
index.cgi.
Testing Login CGI
The login cgi can be opened directly in a browser. This is sometimes called a
pinit (for Pubcookie init, like kinit) since authentication is requested without being tied to an application. It’s a good way to test your current config file and verifier. Go ahead and try it now. The login page you see comes from the
PREFIX/login_templates/login and
PREFIX/login_templates/login_pinit templates.
If authentication succeeds, congratulations, you now can deploy an application server using the Pubcookie Apache module or Pubcookie ISAPI Filter to test the components together. Then you can go on to build and configure another verifier that goes against your authentication service and customize the login cgi templates for your site.
If authentication fails, don’t panic, look in your syslog for error messages from the login cgi and refer to the Logging & Debugging section for further advice.
Logging & Debugging
The login cgi uses syslog to log all messages. Logging can be configured using the
logging_level variable. A value of
1 gets you basic audit activity such as logins and redirects which is most likely sufficient for normal operation. When additional debugging information is needed increase the value to
3.
The keyserver also uses syslog and tends to log all critical error messages. Keyclient uses standard output for its messages.
Login CGI Templates
The login cgi reads HTML templates from the
PREFIX/login_templates directory in order to create login, logout, error, and redirect pages.
The login cgi will read from an alternative location if the
template_root config file variable is defined.
A set of generic, sample templates is copied into place during initial installation. A backup set is also copied to
PREFIX/login_templates.default.
Edit these templates (which represent “Example University”) to brand the login server for your organization and to meet local web design standards.
Refer to the login cgi template reference for descriptions of each template.
Custom Login Messages
This is all about branding. Some application owners require branding of the login page with their own login prompt text and icons. The login cgi support this capability through the use of custom login message templates (small HTML snippets) configured on the login server. They can’t take over the entire design of the login page, but it does provide a place for friendlier, custom messages.
A custom login message applies to a single application, so the corresponding template is stored in a file according to the server name and application id. The file path is based on the custom_login_message_dirconfiguration variable (the directory containing all the custom login message templates, which defaults to the same directory as all the other login templates). The filename is based on thecustom_login_file_prefix configuration variable (the filename prefix for all custom login message templates) plus the server name and application id.
For example, to configure a custom login message for an application on
appserver.example.edu with an application id of
testapp, you would place the custom message (HTML snippet) in the following file (based on default values, of course):
PREFIX/login_templates/custom_login_msg-appserver.example.ed-testapp
You can see where custom login messages are positioned relative to other elements on the login page by viewing the HTML source of the login template. They come just before the reason the user has to authenticate.
Browser Acceptance Configuration
The optional
PREFIX/ok_browsers file contains a list of browsers accepted by the login cgi. This file provides a way to block browsers that either have a known security flaw (i.e., don’t forget cookies when they should) or don’t work with Pubcookie. The ok_browsers file is optional.
Logout Configuration
The login cgi handles logout requests initiated by, and redirected from, applications configured with Pubcookie’s per-application logout functionality. Handling these logout requests is built in; no configuration is necessary to the login cgi itself.
However, through additional configuration you can create a separate, direct logout URL for your login server (e.g.
https://weblogin.example.edu/logout). You can also tailor the logout response messages for your favorite applications. Those are the two subjects of this section.
Note: Pubcookie does not support “global” logout, that is, logout of all sessions, all cookies, all at once. Rather, it supports per-application-session logout with optional ability also to logout of the login server. Therefore, users still must be educated not to leave their browsers open and unattended without proper precautions such as locking their computer and using password-protected screensavers. Exiting the browser remains the best way for users to get logged out of everything at once.
Configuring a Direct Logout URI:
If you want to provide a URL where users can go directly to clear their single sign-on session (by way of clearning their “login” cookie), it can be created with the
logout_prog config variable and a Unix symbolic link. Here’s an example.
Suppose the login cgi has been installed in the DocumentRoot directory (e.g. in
/var/www/html) with a URL of
https://weblogin.example.edu. To create a logout URI of
/logout/ just below that, i.e.,
https://weblogin.example.edu/logout/, you’d do this:
Change to the appropriate directory, create the subdirectory, and make the symbolic link to your login cgi:
$ cd /var/www/html
$ mkdir logout
$ cd logout
$ ln -s ../index.cgi index.cgi
Adjust the directory according to the location of your login cgi. Now any request to
/logout/ on the server will map to your login cgi.
Now add the appropriate
logout_prog variable to your config file:
logout_prog: /logout/index.cgi
Customizing Logout Responses For Special Apps:
The login cgi builds logout response pages from several templates. One template,
logout_app, which is the most specific to each application, can be overridden on a per-application basis, as configured and identified by the originating server name and application id. It requires one
app_logout_string config file variable for each application, where the server name and id are tacked on using dashes. For example:
# custom logout msgs
app_logout_string-appserver.example.edu-testapp:
<font size="+1">Testapp logout worked just fine.</font>
app_logout_string-webmail.example.edu-webmail:
<font size="+1">Webmail Logout Successful!</font>
Note: Since the login cgi reads the config file and its HTML templates on each request, there’s no need to recompile the login cgi in order to modify response messages.
Kiosk Configuration
Use the
kiosk variable to apply a site policy for reduced single sign-on duration for identified kiosks. The login cgi supports matching by user-agent string, remote IP address, or IP address ranges. For example:
kiosk: 20m Safari/85.6
15m Safari
10m ExampleKiosk 140.142.14.39 140.142.21.*
1h 140.142.15.10-200
This sets a curiously elaborate, but nonetheless illustrative, kiosk policy: a 20-minute SSO duration for Safari 85.6, a 15-minute SSO for all other versions of Safari, a 10-minute SSO to remote browsers with “ExampleKiosk” in the user-agent string as well as to the remote IP address 140.142.14.39 and the 140.142.21 subdomain, and a one-hour SSO duration for IP addresses in the range 140.142.15.10-200.
Matching by user-agent string is particularly useful for applying reduced SSO to managed kiosks that have a locally customized user-agent string such as:
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; ExampleKiosk; Windows NT 5.0)
How to customize user-agent strings is beyond the scope of this guide, but resources and tools, such as the Internet Explorer Administration Kit, do exist to help with this task.
Site Policy Configuration
This section highlights some of the possible site policies you can define in your config file. These options may be overlooked, but they can enhance the user experience and shape the security policy of your login server.
- Use default_l_expire to define your default single sign-on duration. Primary authentication occurs when user-provided credentials are verified directly. Subsequent authentication is based on checking the “login” cookie. This setting defines how long this cookie is valid.
- Use form_expire_time to define how long users have to log in. Taking too long will result in a new login form (with the form_expired template message included). The default expiration is 60 seconds.
- Use static_user_field to define the editability of the userid field during a single browsing session. You may want to allow some flexibility or force users to close the browser before switching between users.
- Use the retain_username_on_failed_authn to define whether the userid is retained after a failed login attempt. Users will appreciate this if they mistyped their password, not their userid.
- Use trim_username_to_atsign to define whether users can enter a userid that looks like an email address. Sites that aren’t verifying full Kerberos principals (e.g. joe@example.edu) or userids that look like email addresses can use this feature to provide some flexibility in this regard, i.e., to trim off the extra realm info the user added and verify just the proper userid.
- Use lowercase_username or uppercase_username to change the userid to lowercase or uppercase.
Refer to the config file variable reference to review these variables and the values they take.
Kerberos 5 Verifier Configuration
To build the login cgi with support for the Kerberos 5 verifier, run the configure script with the Kerberos option enabled:
./configure --enable-login --disable-apache --enable-krb5
If needed, the configure script has other options for adjusting the location of the Kerberos header files and libraries.
To configure the login cgi to use the Kerberos verifier, edit your config file and set
basic_verifier to
kerberos_v5. Additionally, two other config file variables control the Kerberos 5 verifier:
kerberos5_service_nameand
kerberos5_keytab. For example:
# kerberos verifier config
basic_verifier: kerberos_v5
kerberos5_service_name: pubcookie
kerberos5_keytab: /usr/local/pubcookie/keys/pubcookie.keytab
Enable the
append_realm variable if you want the Kerberos authentication realm to be appended to the user name after authentication but before issuing cookies (i.e., target servers will receive
user@REALM.)
Use the
default_realm variable to define a default Kerberos authentication realm to pass to the verifier when none is submitted via the login form.
To authenticate responses from your Kerberos server, the login server and Kerberos server must share a service key. You can use an existing service key or generate a new one with the help of your Kerberos administrator. Keep in mind that the keytab file that contains your service key must be readable by the login cgi. Since the login cgi will most likely run as a non-root user, it’s recommended that you use a service key other than the “host” service key typically stored in
/etc/krb5.keytab.
Similar to user keys, service keys have a principal of the form
<service_name>/<hostname>@<realm>. The hostname is the fully qualified hostname for your login server, and the realm is the Kerberos realm. But the service name is what counts most to the Kerberos 5 verifier. Your service name can be set with the
kerberos5_service_name variable.
Contact your local Kerberos domain administrator if you need help creating a service key, generating a keytab file, or otherwise configuring Kerberos (e.g.
/etc/krb5.conf) on your login server.
See
doc/krb5-getcred.html for details on how to configure and use Kerberos credential passing.
LDAP Verifier Configuration
To build the login cgi with support for the LDAP verifier, run the configure script with the LDAP option enabled:
./configure --enable-login --disable-apache --enable-ldap
Note: Other configure options can help you specify the location of your LDAP header files and libraries. See
./configure --help.
To configure the login cgi to use the LDAP verifier, set
basic_verifier to
ldap in your config file.
To configure the LDAP verifier itself, add an
ldap_uri to your config file. This variable defines how the verifier connects to your LDAP directory. To enable LDAPS with TLS authentication, configure
ldap_tls,
ldap_key_file,
ldap_cert_file, and
ldap_ca_file.
# ldap verifier config
basic_verifier: ldap
ldap_uri: ldaps://host/o=searchbase???(uid=%s)?x-BindDN=Bind%20DN,x-Password=Password
Note: LDAP in general is not case sensitive, so most implementations don’t enforce case sensitivity on the username (uid) attribute. This may result in usernames of mixed case being sent to application servers for the same authenticated user (e.g. jon, Jon, jOn). To prevent this, use the
lowercase_username site policy to change the username entered to lowercase.
Redundant Login Server Configuration
The login cgi and keyserver can be deployed in a redundant configuration, provided that they share the same cluster name and settings. Use the
login_servers variable to configure keyserver to push new host keys to its peers.
FastCGI Configuration
The login cgi can run as a FastCGI process. This allows one or more instances of the login cgi to persist and handle many requests rather than just one.
FastCGI support is enabled with the
--with-fcgi=<path to fcgi> option. Example Apache configuration follows below; modify as needed.
LoadModule fastcgi_module libexec/mod_fastcgi.so
FastCgiConfig
-appConnTimeout 0
-idle-Timeout 30
-init-start-delay 2
-killInterval 300
-listen-Queue-Depth 50
-maxProcesses 10
-maxClassProcesses 2
-minProcesses 1
-startDelay 10
Supporting Application Servers
To support application servers, other system administrators will need to know the location of your login server, keyserver, and how trust is handled on your keyserver. That is, which CAs the keyserver trusts to verify keyclient certificates; and which CA can be used by the keyclient to verify your keyserver certificate.
Appendix A: Apache Configuration
The default filename for the login cgi,
index.cgi, is a common name for a cgi program that is executed when a directory’s URL is requested. The DirectoryIndex directive defines how Apache handles such requests, typically choosing the first file it finds in its DirectoryIndex list. With appropriate configuration, this can be your login cgi.
For example, you might use the follow
DirectoryIndex directive:
DirectoryIndex index.cgi index.html
Apache also needs to know how to identify cgi scripts by the
.cgi filename extension. Some distributions of Apache have the cgi handler disabled. Make sure the following line is in your httpd.conf and not commented out.
AddHandler cgi-script .cgi
Finally, Apache must allow execution of cgi scripts in the directory where the login cgi is located. If it’s outside of a ScriptAlias directory, you can control this with the Options directive.
Options Indexes FollowSymLinks ExecCGI
Appendix B: Permissions & Security
Due to the important nature of the Pubcookie login server, the only other services that should be run on the same system are those which receive an equally high level of scrutiny for security.
Some of the login cgi’s supporting files are sensitive, particularly the two private keys,
ssl_key_file and
granting_key_file. In a production environment, non-root users shouldn’t be able to read these files.
However, in a typical Apache configuration the login cgi runs within a restricted user context defined by the User and Group server directives. They are usually set to some non-privileged user and group (e.g.
nobody.nobody).
One approach to permissions is simply to make the sensitive files owned and readable by the non-privileged Apache user (
nobody.nobody and octal
600,
700 for the keys directory).
drwx------ nobody nobody 4096 keys/
-rw------- nobody nobody 4096 keys/pubcookie_granting.key
-rw------- nobody nobody 4096 keys/pubcookie_session.key
Another approach is to run Apache as a non-privileged user but use a group that no users are allowed to be in (e.g.
nobody.www where no users are in the
www group). Then sensitive files can be restricted to just root and to the empty group (
root.www and octal
640,
750 for the keys directory). Since the login cgi runs in the context of the group, it can read the files it needs to.
drwxr-x--- root www 4096 keys/
-rw-r----- root www 4096 keys/pubcookie_granting.key
-rw-r----- root www 4096 keys/pubcookie_session.key
Note: since the keyserver is run by inetd or xinetd, it is most likely run as root and therefore can read and write supporting files as needed.
Appendix C: OpenSSL Commands
To generate a new RSA private key and self-signed public key certificate, (for example, for the “granting” key pair), change to the
PREFIX/keys directory and use the following OpenSSL command as an example:
$ cd /usr/local/pubcookie/keys
$ openssl req -new -x509 -out pubcookie_granting.cert
-newkey rsa:1024 -nodes -keyout pubcookie_granting.key
To remove the pass phrase on an SSL private key:
$ openssl rsa -in server.key -out unencrypted.key
The man pages for
x509,
rsa, and
req have many other useful OpenSSL command examples.
Appendix D: Version History
Significant improvements and changes to the login server components included in Pubcookie 3.2.1:
- Added kerserver support for subjectAltName wildcards.
- Fixed login cgi to put redirect messages into the normal audit logging stream.
- Added login_host_cookie_domain to make login cookie domain configurable.
- Added remote realm, if present, to authentication success message in flavor_basic logging.
- Fixed LDAP verifier to default to LDAPv3 for all LDAP SDKs and added “x-Version” parameter to the LDAP URL.
- Revised “fork” verifier to pass username and password via stdin to the forked executable. The config file variable has been changed from fork_exe to verify_exe to avoid accidentally running the wrong executable.
Significant improvements and changes to the login server components included in Pubcookie 3.2.0:
- Added support for custom per-application login messages
- Added keyserver support to allow keyclient authentication by wildcard certificates and Subject Alt Names
- Added keyserver support to allow keyclient certificates signed by untrusted CAs to cache a public key on the keyserver and use it in server authentication
- Added keyclient -U <certfile> option for admins to upload a public key certificate to the keyserver
- Added version string to login server template as HTML comment
- Improved POST-based messaging between application servers and login server
- Deprecated the use of third-party relay cgi
What Do You Need For Your Career?
Only you know what type of equipment you need for your career. Before investing in-ear monitors, you will need to sit down and ask yourself, will you earn money by using these products?
Will you improve your overall playing abilities by taking advantage of such products?
How much time each week are you going to spend playing or practicing?
It can really be hard for the volunteer musician that only plays at church once or twice a week justify spending $400 plus on in-ear monitors. However, for the career musician that is in and out of the clubs every day, it can be easy to justify the expense.
Do You Need Custom Molds Or General Fit?
When you are browsing for in-ear monitors, you will quickly discover that there are two basic options available. Yes, each different monitor will offer a number of sound technologies, but there are two basic models. These two basic models are the general fit and the custom mold.
The general fit options are just like a regular set of headphones. They designed with a general fit purpose, which means they will not mold to your ears. A custom mold is going to cost you more, but these models are specifically designed to fit your ear perfectly.
If you have a weird shaped ear or are worried about not finding a comfortable fit then it would be best to go ahead and spend a little more to get the custom mold design.
Custom fit monitors will probably also do a much better job of canceling out noise since they will fit perfectly in the ear canal. However, there are shell models available that will cover the entire ear.
The Drivers Make A Difference
When shopping for in-ear monitors most musicians don’t really get wrapped up in the number of drivers.
However, for some musicians, this can make all the difference in the world. If you are playing two different instruments it would be best to opt for a device that offers at least two to three drivers. Of course, this is going to raise the overall end price, but it is a feature that will make a major difference in the low end and mid end definition.
Invest In A Durable Cable
If you have used any type of headphone, you already know that the most common component to fail is the cable. This is where a system with a detachable cable will come in handy. Once again, this will cost more in the long run, but it might actually increase the lifeline of your system. 
The role of the Pubcookie login server is that of the trusted, central authentication service. It interacts directly with users. It verifies usernames and passwords with backend authentication services. It issues cookies to users to provide single sign-on functionality and to application servers to provide authentication information.
The role of the Pubcookie application server is that of authentication enforcer. It redirects users who haven’t been authenticated to the login server. It verifies authentication information returned from the login server. It issues cookies to users to maintain authenticated application sessions and provides user authentication information to applications.
The role of the external authentication service is to verify user authentication information sent to it from the login server.
The role of the User-Agent in all of this is simply to play along: to carry the user to the login server when redirected to do so, to assist the user by rendering the HTML-based user interface of the login server, and to accept all valid cookies set by the login and application servers.
