ED-Auth exists to provide an easy means for applications to do simple PID/password authentication and role based authorization (student, faculty, staff, etc.). The ability to support LDAPv3 over SSL/TLS (ldaps or ldap with startTLS) is the only thing required for connecting to ED-Auth.
Authentication and Authorization
ED-Auth offers simple PID/password authentication plus the ability to authorize on a user’s eduPersonAffiliation with Virginia Tech.
Typical Authentication with ED-Auth
The basic steps to authenticate against ED-Auth are:
Bind anonymously and search for the uupid (PID) (search base: ou=People,dc=vt,dc=edu)
Retrieve the DN from the entry returned by the search
Perform a simple bind with the DN and credential
Typical Authorization with ED-Auth
The basic steps to authorize against ED-Auth are:
Bind as above
Peform an LDAP compare operation for the DN against the eduPersonAffiliation attribute, or search for the person using a filter that specifies the affiliation (e.g. (eduPersonAffiliation=VT-ACTIVE-MEMBER)), or search for the person and cycle through the eduPersonAffiliations, looking for a match. (compare is recommended)
ED-Auth vs. ED-ID
Middleware provides two directories for authentication and authorization purposes. Before you begin the process of interfacing your system with ED-Auth or ED-ID (or both!), you must first consider which system better suits your needs. Both ED-Auth and ED-ID support authentication and provide authorization data, however, ED-ID provides much more authorization data. Below are some criteria to help you decide which system will work best for you. Please note you may have to ask the vendor of your product whether it has some of the functionality listed below.
Use ED-Auth if:
Your application can support LDAP over SSL, or startTLS (an LDAP version 3 function) AND
Your application requires extremely fast authentication responses OR
Your application only requires knowledge of a person’s basic affiliation (faculty, staff, student, etc.) for authorization decisions
Use ED-ID if:
Your application can support SSL or TLS with client certificates AND
Your application requires more information about a person than simply their affiliation OR
Your application requires that the directory keep an explicit list of people who are authorized to use your service
Some applications may even be able to support the usage of both directories. If this is the case, it is strongly recommended that you use ED-Auth for authentication and use ED-ID for the lookup of data pertaining to a person. This guarantees fast response times on authentication requests and allows access to all the information about a person that has been collected for placement in the directory.
Primary Affiliations vs. Standard Affiliations
The eduPersonPrimaryAffiliation attribute is an attribute used to communicate, to other institutions, the most basic affiliation a person has with Virginia Tech. This attribute is used in conjunction with systems like Shibboleth* to allow other universities to make authorization decisions about this person. This attribute should NEVER be used by internal Virginia Tech systems for purposes of authorization, it is strictly meant as an external, to VT, facing attribute.
The eduPersonAffiliation attribute gives all the affiliations a person associated with Virginia Tech has with the university. This attribute is meant to be used by internal applications, and will often be used in authorization logic. It is vitally important to realize that this attribute can, and almost always will, have more than one value, which is a change from the current affiliation tracking systems.
SSL Prerequisites for Java Applications
Required JDK Configuration
The following steps are required for all Java applications that talk to ED-Auth. Only JDK versions 1.5 and greater are supported.
Unzip the archive and copy US_export_policy.jar and local_policy.jar to $JAVA_HOME/jre/lib/security
Optional JDK Configuration
The following steps are optional, but may provide additional functionality or better performance in some cases.
Installing the Bouncy Castle Provider
The BC cryptographic provider has a number of additional ciphers compared to the default JSSE provider. For example the AES cipher is provided in 3 flavors (AESEngine, AESFastEngine, AESLightEngine) to allow optimization for performance versus resource consumption, so the use of these features of BC can improve application performance accordingly. Additionally, the implementation of the common ciphers is arguably better.
As an alternative to explicitly managing TLS, for ED-Auth it is sufficient to specify “ssl” for the Context.SECURITY_PROTOCOL initial environment parameter to establish a TLS connection. Since ED-Auth is intended for the authentication/authorization use case where all operations need to be performed over a secure channel, an implicit TLS connection may be preferable.
A C/C++ LDAP library supporting LDAP with the startTLS extension is required in order to connect to ED-Auth. These instructions use the OpenLDAP C LDAP library. You must make sure this library is in your applications library path. Please see Appendix: OpenLDAP and Certificates for information on how to set up your environment for SSL/TLS.
Lines 102-107 determine if the person has the given affiliation
Lines 109-110 clean up
.NET Framework Applications (Windows)
The System.DirectoryServices.Protocols assembly available in .NET Framework 2.0 and later provides a convenient integration option for Windows applications based on the .NET Framework. A simple command-line authenticator is show below in C#.
The EdCertificateVerifier is available in a standalone library assembly, EdCommon, to facilitate use in real applications. A complete Visual Studio solution file containing the source for EdCommon and all .NET ED samples is available in the Middleware git repository.
This document uses the NET::LDAP LDAP module, which in turn requires the IO::Socket::SSL module. If you choose to use a different LDAP module it must be able to support either LDAP over SSL (LDAPS) or LDAP with the startTLS extension.
Lines 6-12 declare and initialize variables for use
Lines 14 setup connection to LDAP server
Lines 16-19 make connection use TLS
Lines 21-22 search for the user s DN
Lines 24-28 get person s DN from search result
Lines 30-31 authenticate user
Lines 33-36 search for the person s affiliation information
Lines 38-44 get affiliation information out of search result
Lines 49 close LDAP connection
This example uses python-ldap to communicate with ED-Auth. Since python-ldap is a wrapper around the OpenLDAP libraries, OpenLDAP and OpenSSL are required for this example to work. Certificates can be set up according to Appendix: OpenLDAP and Certificates. See Appendix: Compiling OpenLDAP Libraries for help with compiling the OpenLDAP library. See the INSTALL document bundled with python-ldap for installation instructions (hint: modify setup.cfg to give OpenLDAP and OpenSSL include and library paths).
If your website runs on Hosting, you can only test authentication using the https://secure.hosting.vt.edu URL associated with your website.
A note about the magic_quotes_gpc option and web forms
If you have magic_quotes_gpc set to On in your php.ini, people with certain special characters (‘,”,\, for example) in their passwords will be unable to authenticate, as the characters will be escaped. Either set magic_quotes_gpc to Off or use stripslashes() to ensure that these people can authenticate. Note that Hosting currently has this option On.
Here is a simplistic example that shows how to bind with PEAR Net_LDAP:
Please note you must accept PID/password credentials securely.
Since these credentials are given to the Apache server using HTTP Basic Auth, this means that all your restricted resources must be served over an SSL (HTTPS) encrypted connection. Failure to do so is a violation of the ED Usage Requirements.
These instructions require the OpenSSL, mod_ssl, OpenLDAP, and auth_ldap libraries. Links to these are provided in the resource appendix. You must have these libraries available to Apache for this to work (See Appendix: Compiling OpenLDAP Libraries for help). These instructions do not describe how to compile Apache, OpenSSL, or mod_ssl. Please refer to the documentation included with those individual programs for compilation instructions.
Compile Apache with SSL support. Be sure to enable loadable module support.
Configure Apache with support for LDAP authentication, here is the configuration we use:
Compile and install Apache with make and make install.
Add the following configuration to your httpd.conf file:
Falling Through to file-based Authentication
Sometimes it is desirable to use both ED-Auth and some form of local authentication together. The following is an example of how to use Apache’s password files.
The AuthBasicProvider directive sets the order of auth modules to attempt to use. In this case it uses file-based auth with apache.passwd if the user is not found in the LDAP.
Note: If you reverse the order of the modules in AuthBasicProvider, you will be able to override users that exist in the LDAP in the password file. This is probably not desirable, and you should ensure that the Apache password file is properly protected.
Tomcat Servlet Container Authentication to ED-Auth
The Tomcat Servlet container can be configured to use the EdAuthRealm provided by the Middleware EDLdap Library to provide container-based authentication and authorization.
Copy the edldap.jar file to a directory on the container classpath ($TOMCAT_HOME/server/lib for Tomcat 5.x, $TOMCAT_HOME/lib for Tomcat 6.x)
Configure the $TOMCAT_HOME/conf/server.xml file similar to the sample below.
Create the file $TOMCAT_HOME/conf/edauth-users.xml that is formatted similarly to tomcat-users.xml; the password attribute for each user is not needed.
Template server.xml file for configuring an ED-Auth container authentication realm.
EdAuthRealm also supports container-based authorization. Simply specify an in the section of the application web.xml to authorize users based on their membership in a given ED group. The following example requires the authenticated user to be a member of the //middleware.staff// ED group to access protected resources.
PAM LDAP gives Unix and Linux machines the ability to authenticate against an LDAP server such as ED-Auth. PAM is highly tunable and powerful, and allows administrators to determine how services (login, xdm, ssh, etc.) authenticate users. These instructions assume you are compiling from source, but you are free to use your favorite distribution’s package at your own risk.
In your /etc/ldap.conf (Note that this is a pam_ldap specific file, and it not used by OpenLDAP.), add the following:
Add the following to nslcd.conf:
Have something similiar in your nsswitch.conf:
Download vt-cachain.pem and put the file in the location you specified in step 4.
man pam and read up about the pam.conf configuration file, pam.d, and services.
Modify your service rules in /etc/pam.d accordingly, making sure the rules do what you think they do (!!!). (hint: the pam.d directory that comes with the pam_ldap distribution is a good place to look at rules. The login rules file works well.)
pGina Windows Authentication
pGina is a replacement for the authentication portion of Windows 2000/XP, and allows Windows users to authenticate against ED-Auth. This is especially useful in a lab or similar enviromment where PID/pass authentication is desired.
Import the VTCA chain into the Windows keystore. This is available at the VT Root CA site, or, alternatively, click on “immediate installation” and run the .exe at the VT Root CA site. This will automatically install the VTCA chain for you.
Start up the pGina Configuration Tool, click on the Plugin tab, and put the path to the LDAPAuth Plugin for the Plugin Path.
Click on Configure and fill in the following:
Appendix: OpenLDAP and Certificates
If the application you are using to connect to ED-ID or ED-Auth uses the OpenLDAP libraries, it may be necessary to set up the certificates for your client. This is done with the following directives: TLS_CACERT, TLS_CERT, and TLS_KEY. TLS_CACERT refers to the certificate chain used to verify the server. TLS_CERT and TLS_KEY refer to the client certificate and private key, respectively, that are used for TLS client authentication (only used for ED-ID). These directives can be set up in the following ways:
Add the following to the OpenLDAP library’s ldap.conf. This must be the ldap.conf that corresponds to the OpenLDAP library you are using for your application. (Note that there may be multiple ldap.conf files on your system, but only one will actually be used by a particular OpenLDAP library).
This sets up certificates system-wide for the OpenLDAP library.
Put the above directives in a file called ldaprc in the user’s $HOME directory that is using the application. This will override the system-wide settings for the user.
Put the above directives in a file called .ldaprc in the user’s $HOME directory that is using the application. This will override the system-wide settings for the user.
Put the above directives in a file called ldaprc in the user’s current working directory ($PWD) that is using the application. This will override the system-wide settings for the user.
Set the following environment variables:
These directives are searched for in this order. The last directives set override any previous directives. For more information on this, see the ldap.conf manpage for OpenLDAP.
Appendix: Testing and Debugging with OpenLDAP
The //ldapsearch// program distributed with OpenLDAP is a useful tool for testing and debugging your custom application, particularly if it uses the OpenLDAP libraries at some level. Below are examples for how to connect to ED-Auth. Please refer to Appendix: OpenLDAP and Certificates for information on how to set up certificates.
NOTE: Your OpenLDAP libraries must be compiled with SSL support to do this.
To search for a person:
To bind as a person:
-H – specifies the LDAP URL
-x – specifies that we want to a simple bind (anonymous in this case)
-Z – specifies that we want to do Start TLS request
-b – specifies the search base for the search
-D – the DN of the user you want to bind as
-W – prompts the user for the bind password
Appendix: PHP, SSL, and Windows
To use LDAPS functionality in PHP on Windows you must create the following file:
Many of the examples contained in this document depend on the OpenLDAP LDAP Libraries for their functionality. This includes the C, Net::LDAP, Python, PHP, Ruby, and Apache examples as well as the standard LDAP utilities such as ldapsearch. This appendix exists to help you compile the libraries needed for your application to interface with ED-Auth.