Penn Computing
Computing Menu Computing A-Z
Computing Home Information Systems & Computing Penn
The following instructions apply to using Websec to restrict access to web pages. Websec will be retired in December 2009 and replaced by a new authentication system, Penn Weblogin. Penn Weblogin is now available. Please consider using Penn Weblogin to restrict access to your pages now and avoid having to transition later.

Enabling PennKey Authentication of Static Web Pages

Introduction

Web servers at Penn which are running Apache can install an Apache module which will allow then to secure static web pages using PennKey authentication via local directives in the Apache .htaccess files. The module you would install will depend on what version of Apache you are running.
Apache 1.x www_htpas_access
Apache 2.x mod_websec

Instead of users entering an Apache username/password to view restricted web pages, websites which take advantage of these Apache/Websec modules can have users authenticate themselves by using their PennKey and password. The main advantage of this is that the website maintainers do not have to create and maintain a separate list of usernames and passwords for each website they wish to protect. Server administrators who wish to install the Apache/Websec modules should view the server administrator guide.

For any web page requiring PennKey authentication, the web server will expect the appropriate validation credentials to be passed to it before authorization to the web page is granted. If the user has already authenticated him/herself, this information will automatically be passed to the web server when the request for the page is made. If the web server does not receive valid credentials, it will perform a redirect to ISC's secure web server so that the user may PennKey authenticate him/herself. Once this step has been completed, the user will be redirected back to the page that was originally requested. The web server takes all steps to validate that the user is properly authorized and appropriately allows or denies access to the page.

Protecting web pages

Use of the Apache/Websec modules requires that you register a separate websec application and set up custom login screens. See documentation on creating customized login pages for the Apache/Websec modules for more details.

.htaccess Directives

Following are the directives that you can add to the .htaccess that will work with the Websec server if your web server has been set up with the Apache/Websec modules. As with any .htaccess file, the directives will affect the directory where the .htaccess file is placed and any subdirectory in that directory.

Note: Providers who have pages on www.upenn.edu who are using the Apache/Websec module must turn off caching.

Directive Availability Description
AuthPennNet Apache1.x
Apache2.x
example:
AuthPennNet

This is the only requirement to enable PennKey authentication. This directive must appear in the .htaccess file.
AuthPennNetLoginPage Apache1.x example:
AuthPennNetLoginPage http://server.upenn.edu/login.html

When requesting a page that requires PennKey authentication, the login page has already been defined for this Websec application. If you wish to specify a different login page than the one defined for the web server, add the AuthPennNetLoginPage directive to your .htaccess file. This directive takes the URL of your login page as the argument.

Only supported for Apache 1.x in the www_htpas_access module. Deprecated with Apache 2.x. If used with Apache 2.x, it will fail and log an alert in error_log. Use WebsecApp for Apache 2.x.
WebsecApp Apache2.x example:
WebsecApp websec_application_name

When requesting a page that requires PennKey authentication, the login page has already been defined for this Websec application. If you wish to specify a different login page than the one defined for the web server, add the WebsecApp directive to your .htaccess file. This directive takes the application name of another Websec application and will use the login page for that app as the login page that will be presented to the user when authenticating and the failure page for that app as the failure page should the user fail to authenticat unless AuthZPennNetFailedPage is also specified.

Please note that if you set the WebsecApp directive to a different websec application, the application name associated with your websec token will also change and this may affect single sign-on with other pages.

Only supported for Apache 2.x in the mod_websec module. If used with Apache 1.x, it will fail and present a 500 error to the browser. Apache 1.x should use the AuthPennNetLoginPage directive.
AuthZPennNetUsersFile Apache1.x
Apache2.x
example:
AuthZPennNetUsersFile /HTML/path/to/authorization_file
AuthZPennNetUsersFile .auth_file

To require that the user also pass an authorization step, denote this on a separate line in the .htaccess file using the AuthZPennNetUsersFile directive. This argument can either be a full directory path or a relative directory path. If a relative path is used, it is relative to the location of the .htaccess file. The authorization file contains no more than one PennKey or 8-digit PennID number per line.

Sample of contents of an authorization file:
  username1
  username2         # With a comment
  12345678          # 8-digit PennID
AuthZPennNetFailedPage Apache1.x
Apache2.x
example:
AuthZPennNetFailedPage /HTML/path/to/failure_page

If you specify that authorization is required via AuthZPennNetUsersFile, you need to also specify a failed authorization HTML page for those situations where the user properly authenticated but is not in the AuthZPennNetUsersFile. Use the AuthZPennNetFailedPage directive to accomplish this.

Note that the argument to AuthZPennNetFailedPage is not a directory path, but a URI. The URI should not contain the web server hostname information, as the HTML page must be stored on the same machine as the requested page.
AuthPennNetDomainOverride Apache1.x
Apache2.x
example:
AuthPennNetDomainOverride www.upenn.edu
AuthPennNetDomainOverride .upenn.edu

If you would like to list a set of hostnames or domains for which you do not want the module to require authentication, this can be accomplished with the AuthPennNetDomainOverride directive.

Note: Providers who have pages on www.upenn.edu who are using the Apache/Websec module can not use AuthPennNetDomainOverride due to all requests originating from the proxy server and not the original host.
AuthPennNetIPOverride Apache1.x
Apache2.x
example:
AuthPennNetIPOverride 128.99.99.99
If you would like to list a set of IP addresses for which you do not want the module to require authentication, this can be accomplished with the AuthPennNetIPOverride directive.

Note: Providers who have pages on www.upenn.edu who are using the Apache/Websec module can not use AuthPennNetIPOverride due to all requests originating from the proxy server and not the original host.
AuthIPCkOff Apache1.x
Apache2.x
example:
AuthIPCkOff

By default the Websec module will check that the IP-address of the original authentication is the same IP-address of any subsequent requests. When securing static pages, if this IP-address check fails, users will not be able to view restricted pages. This may be a problem for some users who are using ISP's that are running a web proxy server or for whole webservers that are using a proxy service. Details on this problem are available.

You may opt to turn off IP-address checking for a group of pages where this added security is not necessary or cannot be used. While this does reduce the security of your pages, IP-address checking is a very questionable layer of security since IP addresses can be forged and you may have no alternative but to turn off IP-address checking. This can be accomplished with the AuthIPCkOff directive. To turn off IP-address checking, add the AuthIPCkOff directive to your .htaccess file.

Note: Providers who have pages on www.upenn.edu must use this directive when restricting access to their pages. With the introduction of the caching service, all pages on www.upenn.edu are now being served through a proxy server and IP-address checking cannot be used.


You can add any other Apache directives that are supported by the web server's .htaccess mechanism, if desired.

httpd.conf Directives

Directives for Apache 2.x that can be added to the httpd.conf
Directive Description
WebsecAppDefault example:
<IfModule websec_module>
WebsecAppDefault testserver_htpas_access
</IfModule>


The registered name of the default Websec application. If a .htaccess file does not specify an application with a WebsecApp directive, then this will be used instead. If WebsecAppDefault is not specified, then there MUST be a WebsecApp directive in the .htaccess file.
WebsecClient example:
<IfModule websec_module>
WebsecClient /usr/local/lib/websec/websec_client
</IfModule>


Path to the local installation of the websec client binary. The default is /usr/local/lib/websec/websec_client. You only need to add this directive if you have installed the websec_client in a different place.
WebsecServer example:
<IfModule websec_module>
WebsecServer rosetta.upenn.edu
</IfModule>


Hostname of the Websec server. The default is rosetta.upenn.edu. You only need to add this directive if you are using a different Websec server.
top

Information Systems and Computing
University of Pennsylvania
Comments & Questions


University of Pennsylvania Penn Computing University of Pennsylvania Information Systems & Computing (ISC)
Information Systems and Computing, University of Pennsylvania