Maintainer Toolkit

Access Control

This documentation will help you get started at controlling who is allowed to access your website.

Table of Contents:

What Are Access Rules?

Access rules are used by web site administrators to control who has access to files and directories within a website.

What is an Access Control/.htaccess File?

Access control, also refered to as .htaccess, files are simple, plain text files containing a list of access control rules which are applied to either a directory (and those directories and files contained within) or to individual files.

Where Do I Place the .htaccess File?

The .htaccess file should be placed in the directory to control access, or in the directory containing the individual files you wish to control. Any access restrictions within a given directory will also affect all directories contrained within.

As example, if you have a directory named /private you wish to control access, you would create the access control file:

  • /private/.htaccess

Anatomy of an Access Control File

Let's take a look at what an access control file looks like and what the contents of the file do.

What All Access Control Files Must Have

All access control files must start with the following four lines:

  • AuthType CAS
  • SSLOptions +StrictRequire
  • SSLRequireSSL
  • ErrorDocument 403 /cgi-bin/to_ssl.pl

The first line AuthType CAS tells the web server that we will be using the campus Single Signon (CAS) to authenticate users to this area. In almost all cases, this is what you will want to use, however we will discuss a different AuthType later.

The next three lines are very important as they tell the web server to require that the user's browser be using an encrypted (also known as SSL or HTTPS) connection to talk to the server. By requiring that this connection be encrypted, we ensure that the user's password is secure from prying eyes.

Control Access to Everyone with a Case Network Id

If you want to allow access to your site to anyone with a Case Network Id, you would include the line

  • require valid-user

Note that there are in excess of one hundered Thousand active Case Network Ids, spread over numerous groups, including alumni and University affiliates and therefore you are allowing access to more than just active faculty, staff and students. See below for how to tighten this access up.

Control Access to Individual Case Network Ids

If you want to allow access to your site to a specific individual Case Netword Id, you would include the line:

  • require user xxx12

Be sure to replace xxx12 with the actual network id of the individual.

This line can be repeated multiple times to allow access to a group of Case Network Ids:

  • require user xxx12
  • require user abc11
  • require user xyz
  • require user pdq5

Control Access to Pre-Defined Campus Groups

As mentioned previously, require valid-user my not restrict your site as tightly as you wish. To help with this, the campus directory service (also refered to as LDAP) defines a number of group attributes for each user. You can use these attributes to control access to your site. For example:

  • require ldap-attribute eduPersonScopedAffiliation=faculty@case.edu

would restrict access to only active members of the University Faculty.

Here is a list of the most useful LDAP attributes:

LDAP Group Description
member@case.edu All members of the Case Campus Community. This is a bit more restrictive than require valid-user
faculty@case.edu Active Case faculty
staff@case.edu Active Case staff
student@case.edu Active Case students
alum@case.edu All Case alumni

These groups (member, faculty, staff and student) are also defined for the individual colleges. To utilize these groups, replace @case.edu with one of the following:

Subgroup Description
@med.case.edu School of Medicine
@management.case.edu Weatherhead School of Management
@law.case.edu School of Law
@artsci.case.edu College of Arts & Sciences
@nursing.case.edu School of Nursing
@sass.case.edu Mandel School of Applied Social Sciences
@dental.case.edu School of Dentistry
@cim.case.edu Cleveland Institute of Music

For example, to restrict access to students at the Cleveland Institute of Music you would use:

  • require ldap-attribute eduPersonScopedAffiliation=student@cim.case.edu

Examples, Part I

Here are some access control file examples:

Allow All Members of the Case Campus Community

  • AuthType CAS
  • SSLOptions +StrictRequire
  • SSLRequireSSL
  • ErrorDocument 403 /cgi-bin/to_ssl.pl
  •  
  • require ldap-attribute eduPersonScopedAffiliation=member@case.edu

Allow Only Active University Faculty, Staff and Students

  • AuthType CAS
  • SSLOptions +StrictRequire
  • SSLRequireSSL
  • ErrorDocument 403 /cgi-bin/to_ssl.pl
  •  
  • require ldap-attribute eduPersonScopedAffiliation=faculty@case.edu
  • require ldap-attribute eduPersonScopedAffiliation=staff@case.edu
  • require ldap-attribute eduPersonScopedAffiliation=student@case.edu

Allow a List of Indivdual Case Network Ids

  • AuthType CAS
  • SSLOptions +StrictRequire
  • SSLRequireSSL
  • ErrorDocument 403 /cgi-bin/to_ssl.pl
  •  
  • require user xxx12
  • require user abc
  • require user xyz987

Allow All Active University Students, Plus additional Case Network Ids

  • AuthType CAS
  • SSLOptions +StrictRequire
  • SSLRequireSSL
  • ErrorDocument 403 /cgi-bin/to_ssl.pl
  •  
  • require ldap-attribute eduPersonScopedAffiliation=student@case.edu
  • require user xxx12
  • require user abc
  • require user xyz987

Allow Active Staff Members from the Schools of Law, Medicine and Nursing

  • AuthType CAS
  • SSLOptions +StrictRequire
  • SSLRequireSSL
  • ErrorDocument 403 /cgi-bin/to_ssl.pl
  •  
  • require ldap-attribute eduPersonScopedAffiliation=staff@law.case.edu
  • require ldap-attribute eduPersonScopedAffiliation=staff@medicine.case.edu
  • require ldap-attribute eduPersonScopedAffiliation=staff@nursing.case.edu

Advanced Access Control

Now that you know the basics of access control, its time to look at some of the more advanced abilities of the web server's authentication environment.

Controlling Access to a Single File

Let's say that you have a single file on your site (we'll call it super_secret_info.html) whose access you need to restrict, but it is stored in a directory with other files whose access does not need to be controlled. To do this, you will need to add a <Files> section to your access control file which looks like:

  • <Files super_secret_info.html>
  •    require valid-user
  • </Files>

You can also list more than one file:

  • <Files super_secret_info.html another_secret_file.html>
  •    require valid-user
  • </Files>

Basic Authentication / AuthType Basic

Up to this point, everything we have shown has utilized the campus Single Signon environment (CAS) to ask the user for their network Id and password and for most situations this is the best solution. If we want to control access based on something other than the Campus Network Id, we cannot use CAS and must utilize the web browser's built-in ability to prompt the user for their credentials. This is called Basic Authentication.

To enable your site to use Basic Authentication, you will replace the AuthType line we saw before with a new version, AuthType Basic. The four lines all access control files must have now look like:

  • AuthType Basic
  • SSLOptions +StrictRequire
  • SSLRequireSSL
  • ErrorDocument 403 /cgi-bin/to_ssl.pl

Notice that we do not remove the four encryption-related lines. They are still very important.

Local User Accounts

Let's say that you need to grant access to an individual not associated with the University (and therefore does not have a Campus Network Id). Local User Accounts are the answer. Local User Accounts are id and password combiniations that exist only within your website and are completely under your control.

Local User Accounts are stored in a file named .htpasswd. To help you manage your Local User Accounts, we provide a Local Accounts tool. Unlike the .htaccess file, the .htpasswd file should not be editted by hand.

Once you have created your local user accounts, you will need to modify your Access Control File to utilize them by adding the AuthUserFile directive.

As an example, let's say the root of your website is located at /foo/bar. Your AuthUserFile directive would look like:

  • AuthUserFile /usr/local/web/webdocs/foo/bar/.htpasswd

The initial portion of the AuthUserFile path (/usr/local/web/webdocs) is the root of the entire web server and is required so that the server finds the correct Local User Account file. Note that the .htpasswd file is always located in the root of your website.

Please be sure to replace /foo/bar with the root of your website.

Granting access to your Local User Accounts uses the same syntax as access control based on individual netword ids. For example, using the tool you created a local account called my_local_user, you would add the line:

  • require user my_local_user

to your access control file.

Local Groups

There will be instances where you will want to utilize the same list of individuals (either Case Network Ids or Local User Accounts) in multiple access control files. n these situations, you could put the full list in each seperate access control file, but making changes to that list would mean editting each file which is both time consuming and prone to errors.

This problem is solved using a Local Groups file, called .htgroup. Like the Local User Accounts file, the Local Groups file allows you to create groupings of users which can then be used in your Access Control files.

The .htgtoup files is a standard text file and can be created and editted using any text editor (e.g. Notepad) and should be placed at the root of your website. Groups are defined in the form:

  • group_name: user_1 user_2 user_3 ... user_n

The users in the list can be either Campus Netword Ids or local users created with the Local Accounts tool.

Once you have created your Local Groups file, you will need to tell your .htaccess file where to find it by adding an AuthGroupFile directive, which looks like:

  • AuthGroupFile /usr/local/web/webdocs/foo/bar/.htgroup

As we saw with the Local User Account file, the full system path to the Local Group file is required.

We can now add an access restriction based on our new Local Group. In this example, our .htgroup file contains a single local group defined as:

  • testgroup1: abc12 xyz pdq

To utilize this group, we will use the allow group directive, as follows:

  • allow group testgroup1

Mixing Local and Pre-Defined Campus Groups

This is where things get a little sticky. When the server sees the AuthGroupFile directive, it will attempt to check whether the user is a member of one of the groups defined in our Local Groups file. The problem is that when the user is not in this file, the server will not check any further and will not allow the user access to your site, even if there is an an additional Pre-Defined Campus Group listed in the Access Control file.

Since we are now trying to mix both group types, so we will need to tell the web server to continue checking the Pre-Defined Campus Groups. We do this by adding a line to the Access Control file, which looks like:

  • AuthzGroupFileAuthoritative off

Please note that this line should only be used in this situation as it has one unintended condequence.

When this line is present and under some circumstances, a user who is denied access to your website will receive a Server Error as opposed to an Access Denied error.

Let's say we want to allow users from our group testgroup1 (as we defined previously) and active University students. We would create an Access Control file that contains the following:

  • AuthzGroupFileAuthoritative off
  • AuthGroupFile /usr/local/web/webdocs/foo/bar/.htgroup
  • require group testgroup1
  • require ldap-attribute eduPersonScopedAffiliation=student@case.edu

Examples, Part II - Advanced Access Control

Here are some more examples, this time utilizing the more advanced access control topics

Restrict access to a single file (secret1.html) to all members of the Case Campus Community

  • AuthType CAS
  • SSLOptions +StrictRequire
  • SSLRequireSSL
  • ErrorDocument 403 /cgi-bin/to_ssl.pl
  •  
  • <Files secret1.html>
  •    require ldap-attribute eduPersonScopedAffiliation=member@case.edu
  • </Files>

Allow all members of the Case Campus Community to see any file in this directory, but only allow Active Case Students to see a single file

  • AuthType CAS
  • SSLOptions +StrictRequire
  • SSLRequireSSL
  • ErrorDocument 403 /cgi-bin/to_ssl.pl
  •  
  • require ldap-attribute eduPersonScopedAffiliation=member@case.edu
  •  
  • <Files students-only.html>
  •    require ldap-attribute eduPersonScopedAffiliation=student@case.edu
  • </Files>

Allow all members of the Case Campus Community to see any file in this directory, but restrict two files, one to faculty only and one to students only

  • AuthType CAS
  • SSLOptions +StrictRequire
  • SSLRequireSSL
  • ErrorDocument 403 /cgi-bin/to_ssl.pl
  •  
  • require ldap-attribute eduPersonScopedAffiliation=member@case.edu
  •  
  • <Files students-only.html>
  •    require ldap-attribute eduPersonScopedAffiliation=student@case.edu
  • </Files>
  •  
  • <Files faculy-only.html>
  •    require ldap-attribute eduPersonScopedAffiliation=faculty@case.edu
  • </Files>

Allow Access from two Local User Accounts (created with the Local Accounts tool)

  • AuthType Basic
  • SSLOptions +StrictRequire
  • SSLRequireSSL
  • ErrorDocument 403 /cgi-bin/to_ssl.pl
  •  
  • AuthUserFile /usr/local/web/webdocs/foo/bar/.htpasswd
  •  
  • require user local_user_1
  • require user local_user_2

Allow Access from a Local Group

.htgroup file

  • my_local_group: abc12 xyz pdq zzz99

.htaccess file

  • AuthType Basic
  • SSLOptions +StrictRequire
  • SSLRequireSSL
  • ErrorDocument 403 /cgi-bin/to_ssl.pl
  •  
  • AuthGroupFile /usr/local/web/webdocs/foo/bar/.htgroup
  •  
  • allow group my_local_group

Allow Access from a Local Group, plus two local users

.htgroup file

  • my_local_group: abc12 xyz pdq zzz99

.htaccess file

  • AuthType Basic
  • SSLOptions +StrictRequire
  • SSLRequireSSL
  • ErrorDocument 403 /cgi-bin/to_ssl.pl
  •  
  • AuthUserFile /usr/local/web/webdocs/foo/bar/.htpasswd
  • AuthGroupFile /usr/local/web/webdocs/foo/bar/.htgroup
  •  
  • require group my_local_group
  • require user local_user_1
  • require user local_user_2

Allow Access from a Local Group, plus all Active University Faculy, Staff and Students

.htgroup file

  • my_local_group: abc12 xyz pdq zzz99

.htaccess file

  • AuthType Basic
  • SSLOptions +StrictRequire
  • SSLRequireSSL
  • ErrorDocument 403 /cgi-bin/to_ssl.pl
  •  
  • AuthzGroupFileAuthoritative off
  • AuthGroupFile /usr/local/web/webdocs/foo/bar/.htgroup
  •  
  • require group my_local_group
  • require ldap-attribute eduPersonScopedAffiliation=faculty@case.edu
  • require ldap-attribute eduPersonScopedAffiliation=staff@case.edu
  • require ldap-attribute eduPersonScopedAffiliation=student@case.edu
© 2013 Case Western Reserve University
Cleveland, OH 44106
216.368.2000
 
Information Technology Services
(legal notice)
 
Contact website owner
 
Contact our service desk
CWRU ITS Social Networks
Translate this page

Share |