How to Restrict Web Access Based on the Campus Directory (LDAP)

Table of Contents

Introduction and Objectives
The Advantage of Using LDAP
How to Restrict Web Space to Students
How Does it Work?
Recipes for Restriction
Combining LDAP Attributes
More Information

Introduction and Objectives

This tutorial will guide you through all the steps necessary to set up LDAP-based access restrictions for campus web space. The learning objectives for this tutorial include:

  • Understanding the advantages of LDAP-based restrictions

  • Learning how to set up a simple restriction based on the student role

  • Learning how to grant access to people in more than one role

  • Look at some common LDAP-based restrictions for campus

  • Understand the concept of LDAP queries and how to find more information

  • Find out where to get more information about the campus LDAP directory

The tutorial assumes that the reader has a basic familiarity with LDAP concepts and how to manipulate files in campus web space. For background on these topics, please see:

The Advantage of Using LDAP

The usual approach to protecting campus web pages is to [ http://help.unc.edu/?id=1952 ] create a .htaccess file that lists all the people allowed to view the space by Onyen. While you can provide a list of Onyens in various ways, you are always limited because you must identify each individual person that needs access. In situations where you need to grant access to a whole department or school, the list of Onyens becomes very hard to gather and keep updated.

The most common use of the campus LDAP directory is as an [ http://help.unc.edu/?id=4244 ] integrated addressbook for email software. However LDAP holds much more information than just names and email addresses. It also including people's roles on campus and all department or school affiliations. With LDAP-based restrictions you can list the LDAP roles or affiliations required for web access without listing individual Onyens. By relying on LDAP roles and affiliations you can effectively grant access to a large number of people in the directory without maintaining a long list of Onyens.

How to Restrict Web Space to Students

This walk through for implementing LDAP restrictions is based on a simple restriction. While the example is simple, the installation process is the same for all LDAP restrictions.

  1. Create a new plain text file called htaccess.txt and save it somewhere convenient like the desktop. Open the file in a text editor and copy/paste in the text below. 

    AuthType Basic
AuthBasicProvider ldap
AuthzLDAPAuthoritative off
AuthName "UNC Chapel Hill Student Onyen Required"
AuthLDAPURL ldap://ldap.unc.edu/dc=unc,dc=edu?uid?one?objectClass=UNCPerson
Require ldap-attribute employeeType=STUDENT

    Save your edited file.

    Note

    Look at the text in the file. Notice that the AuthName line describes who is allowed to access the space. This is the message displayed when visitors are prompted to log in. It is a good practice to tell visitors who is authorized to access the web space.

  2. Make a new folder in your personal web space (under your public_html folder) and call it ldaptest.

  3. Create a simple index.html page in ldaptest. In the body of the document, include a test message as in this example: 

    <html>
<body>Welcome to LDAP protected web space!  You must have been authorized.</body>
</html>

  4. Upload the htaccess.txt file to your ldaptest folder and rename it to .htaccess

    Note

    The filename .htaccess starts with a period, which makes it a hidden file on most Unix systems. The web server looks for this particular file to determine the access setting for a web folder. Because it has a special name, this file will never be delivered to web site visitors.

  5. Open your web browser of choice and open the ldaptest location you just created. The location is probably something like this:

    http://www.unc.edu/~youronyen/ldaptest/

  6. Violà! You should only see the test page if you are indeed a student according to LDAP. If you are not a student, you should see a forbidden message from the web server.

How Does it Work?

So what just happened? The details of the process are all described in the [ http://help.unc.edu/?id= ] [ http://httpd.apache.org/docs/2.0/mod/mod_auth_ldap.html ] Apache web server documentation, but here is a brief summary. On getting your request for the web page, the server checked first for an .htaccess file in the folder. Having found the file you created, it looked inside for authentication and authorization information before serving the page. The first three lines of your file told the web server that it needs to use a certain kind of LDAP-based authentication. Then the AuthName line gives the server a message that it can use to prompt for username and password.

Authentication

After the user enters a username and password, the next thing that happens is authentication. This is the process of verifying that the username given exists in LDAP and that the right password was entered. The AuthLDAPURL line tells the web server how to lookup a record for the username. In general you should be able to use the line provided, but here is the syntax for those who are curious: 

AuthLDAPURL ldap://<host>/<basedn>?<username attribute>?<search depth>?<filter>

If LDAP send back a UNCPerson record, then the web server immediately attempts to bind to the LDAP server using the distinguished name (DN) of the UNCPerson record and the password that was entered. If the LDAP bind is successful, then the user had been authenticated and the server knows who they are.

Authorization

The Require line tells the server what credentials are required for access to the web space, based on LDAP information. 

Require ldap-attribute employeeType=STUDENT

The AuthLDAPURL line will only return UNCPerson objects. (LDAP directories can also contain other objects, such as departments.) The Require line specifies that there must be an employeeType attribute on the UNCPerson object with the value of "STUDENT".

Note

LDAP attributes names, such as employeeType, are often based on common standards which may seem more suitable to a business than the University. Despite the name, even students have an employeeType attribute. Other values for employeeType include STAFF and EPA FACULTY.

Recipes for Restriction

Here are some .htaccess examples that you can modify for your web space needs.

Restricting to a Department

AuthType Basic
AuthBasicProvider ldap
AuthzLDAPAuthoritative off
AuthName "UNC Chapel Hill Psychology Department Only"
AuthLDAPURL ldap://ldap.unc.edu/dc=unc,dc=edu?uid?one?objectClass=UNCPerson
Require ldap-attribute departmentNumber=3258

You can restrict access to a single department by specifying the department number as a required LDAP attribute. The valid department numbers for all departments and organizations on campus are listed in the [ http://www.unc.edu/inst_res/org_file/ ] University organizations file.

Restricting to Faculty

AuthType Basic
AuthBasicProvider ldap
AuthzLDAPAuthoritative off
AuthName "UNC Chapel Hill Faculty Only"
AuthLDAPURL ldap://ldap.unc.edu/dc=unc,dc=edu?uid?one?objectClass=UNCPerson
Require ldap-attribute employeeType="EPA FACULTY"

This is just a variation on the STUDENT example used earlier. However, the faculty employeeType value, "EPA FACULTY", has a space in it. You must place double quotes around attribute values that contain spaces.

Combining LDAP Attributes

LDAP attribute based restrictions are powerful, but there are currently some limitations. You cannot combine more than one attribute requirement with an AND expression. That is, you cannot require more than one attribute. You can combine attribute requirements with an OR expression simply by adding a space and then listing another name/value pair.

Here is an example of an LDAP restriction that combines two attributes: 

AuthType Basic
AuthBasicProvider ldap
AuthzLDAPAuthoritative off
AuthName "UNC Chapel Hill Faculty and Office of the Chancellor Only"
AuthLDAPURL ldap://ldap.unc.edu/dc=unc,dc=edu?uid?one?objectClass=UNCPerson
Require ldap-attribute employeeType="EPA FACULTY" departmentNumber=2201

This restriction will allow access to all faculty as well as anyone in department 2201, the Office of the Chancellor. Such restrictions are useful when sharing protected web space with more than one department.

More Information

The best place to find out more about restriction possibilities is the Apache web server documentation:

You can discover all the LDAP attributes in the campus directory by looking at different people's records. Simply [ http://help.unc.edu/?id=5805 ] log-in to the Isis Unix environment and type the following command:

$ ldapsearch -h ldap.unc.edu -b dc=unc,dc=edu uid=onyen

You will need to replace "onyen" above with the Onyen of the person you want to look at. Try looking at your own record to see what attributes are available. If you come up with a useful new recipe for an LDAP-based restriction, submit it as a comment on this document. We will include it in the next revision.

Copyright 2002-2007 The University of North Carolina at Chapel Hill.

Creative Commons License
This work is licensed under a Creative Commons Attribution 3.0 United States License.

Post a Comment

This form is for document feedback. If you need technical assistance, and are affiliated with UNC-Chapel Hill, please Submit a Help Request
Optional
Optional
So that we may contact you.
Do not fill out this form, this is a spam trap.
Top
University of North Carolina - Chapel Hill