Enterprise Directory LDAP

The Enterprise Directory provides a high-performance read-only interface via the LDAPv3 protocol intended for authentication, authorization, and directory queries. Three views of the directory schema are provided for these use cases:

View Security Context Description
ED-Lite Anonymous Public directory or whitepages lookups
ED-Auth Person Person authentication and authorization
ED-ID Service Fine-grained access to privileged data elements

The view of the directory is a function of the security context in which directory operations are performed. In other words, the way you bind determines what view you see. All views share a common directory schema that consists of the following object classes:

  1. People
  2. Addresses
  3. Services
  4. Groups
  5. Entitlements
  6. Organizations

While all branches are available in all directory views, not all directory entries are available; similarly all attributes of visible entries may not be available. For example, since entitlements are only visible to principals that have defined roles on the entitlement (viewer, manager), no entitlements are visible in ED-Lite since the security context is anonymous.

ED-Lite

Binding to ED-LDAP anonymously results in the view we refer to as ED-Lite.

ED-Lite contains public directory information that is world readable. It is the source for all the information contained in People Search:

ED-Lite is available at:

Example

$ ldapsearch -h directory.vt.edu -Z -x -b ou=People,dc=vt,dc=edu uupid=dhawes
# extended LDIF
#
# LDAPv3
# base <ou=People,dc=vt,dc=edu> with scope subtree
# filter: uupid=dhawes
# requesting: ALL
#

# 1152120, People, vt.edu
dn: uid=1152120,ou=People,dc=vt,dc=edu
objectClass: virginiaTechPerson
uupid: dhawes
uid: 1152120
cn: David H Hawes
sn: Hawes
givenName: David
middleName: H
displayName: David H Hawes
departmentNumber: 066103
authId: dhawes
mailStop: 0479
postalAddress: SETI-Middleware$1700 Pratt Dr.$Blacksburg, VA 24061
title: Application Developer
instantMessagingID: Google:dhawes@vt.edu
instantMessagingID: Virginia Tech:dhawes@im.vt.edu
suppressDisplay: FALSE
telephoneNumber: 5402313862
passwordState: ACTIVE
labeledURI: Homepage:https://www.middleware.vt.edu/doku.php?id=middleware:dhaw
 es
mail: dhawes@vt.edu
suppressedAttribute: localPostalAddress
department: Middleware & Identity Apps

# search result
search: 3
result: 0 Success

# numResponses: 2
# numEntries: 1

Suppression Rules

Some data can be suppressed in ED-Lite depending on a user’s affiliations and preferences. The rules are listed below.

Affiliations

The following affiliations roll up to the VT-ACTIVE-MEMBER affiliation, which overall suppression is based on:

The following affiliations do not roll up to the VT-ACTIVE-MEMBER affiliation:

Rules

The following rules for displaying information in ED-Lite should be treated individually. That is, if rule 1 is met, the information is displayed for that individual and rule checking stops. In other words, you only go to rule 2 if rule 1 doesn’t apply.

  1. If any of the affiliations present is VT-EMPLOYEE-STATE, then display the Employee attributes taking into account the suppressedAttribute attribute for addresses and phones.
  2. If at this point, any affiliation present is VT-EMPLOYEE-PREHIRE, then do not display any information about this person.
  3. If at this point, any affiliation present is VT-STUDENT-ENROLLED or VT-STUDENT-FUTURE and the Confidential flag is NO, then display the Student-Not Confidential attributes taking into account the suppressedAttribute attribute for addresses and phones.
  4. If at this point, any affiliation present is VT-STUDENT-ENROLLED or VT-STUDENT-FUTURE and the Confidential flag is YES, then do not display any information about this person.
  5. If at this point, any affiliation present is VT-EMPLOYEE-WAGE or VT-EMPLOYEE-NON-STATE, then display the Others attributes.
  6. If at this point, any affiliation present is VT-STUDENT-RECENT and the Confidential flag is NO, then display the Student-Not Confidential attributes taking into account the suppressedAttribute attribute for addresses and phones.
  7. If at this point, any affiliation present is VT-STUDENT-RECENT and the Confidential flag is YES, then do not display any information about this person.
  8. If at this point, any affiliation present is VT-EMPLOYEE-EMERITUS and the Confidential flag is NO, then display the Employee attributes.
  9. At this point, display the Others attributes.

Suppression Matrix

Attribute Employee Student (Not Confidential) Others
Common Name OK OK OK
Home department for an employee OK X OK
Display Name OK OK OK
First Name OK OK OK
Instant messaging Ids * * *
Webpage(s) associated with person * * *
Local phone (MA or DM in Banner) OK OK X
Local postal address (MA or DM in Banner) OK OK X
Preferred email address OK OK OK
Mail code for employees OK X OK
Major X OK X
Middle name OK OK OK
Last name OK OK OK
Postal Address (OF in Banner) OK X OK
Office phone number (OF in Banner) OK X OK
Working title OK X OK
UID OK OK OK
PID OK OK OK

* Indicates the individual users should indicate this in My Profile as to whether or not they desire to make this information available via ED-Lite

ED-Auth

Binding to ED-LDAP with a simple bind using TLS is commonly referred to as ED-Auth.

ED-Auth is used primarily to authenticate users by PID and password. It can also be used for authorization using VT affiliations and ED group membership.

Binding to ED-Auth is typically done by searching for the PID, called uupid in ED-LDAP, and then binding with the returned DN and user supplied password.

As a bound user, applications can check affiliations or group membership for authorization.

ED-Auth is available at:

Example

$ ldapsearch -h authn.directory.vt.edu -Z -x -b ou=People,dc=vt,dc=edu uupid=dhawes 1.1
# extended LDIF
#
# LDAPv3
# base <ou=People,dc=vt,dc=edu> with scope subtree
# filter: uupid=dhawes
# requesting: 1.1 
#

# 1152120, People, vt.edu
dn: uid=1152120,ou=People,dc=vt,dc=edu

# search result
search: 3
result: 0 Success

# numResponses: 2
# numEntries: 1

$ ldapsearch -h authn.directory.vt.edu -Z -x -b ou=People,dc=vt,dc=edu -D uid=1152120,ou=People,dc=vt,dc=edu -W uupid=dhawes 1.1
# extended LDIF
#
# LDAPv3
# base <ou=People,dc=vt,dc=edu> with scope subtree
# filter: uupid=dhawes
# requesting: 1.1 
#

# 1152120, People, vt.edu
dn: uid=1152120,ou=People,dc=vt,dc=edu

# search result
search: 3
result: 0 Success

# numResponses: 2
# numEntries: 1

$ ldapcompare -h authn.directory.vt.edu -Z -x -D uid=1152120,ou=People,dc=vt,dc=edu -W uid=1152120,ou=People,dc=vt,dc=edu virginiaTechAffiliation:VT-ACTIVE-MEMBER
Enter LDAP Password: 
TRUE

Confidentiality Required

You must use TLS when using ED-Auth. Failure to do so will result in LDAP error 13, confidentiality required.

Always use TLS.

ED-Auth IP Restrictions

ED-Auth will only authenticate users for clients from specific IP addresses or authorized ED services. ITSO manages the list of allowed IP addresses and ED services.

Client Errors

Clients that aren’t in the allowed IP ranges or perform TLS client auth with an active ED Service (Guests only) will see LDAP error 49, invalid credentials. If you encounter this error and the user can login to valid VT services (e.g. https://auth.vt.edu), you should check that your client IP is in the allowed range (or your ED-ID services is active and you are doing TLS client auth).

UUPID Suppression

Users are able to suppress their uupid attribute in ED-Auth, which can cause issues if an application expects the attribute to always be available.

To allow the lookup of a single uupid but prevent the enumeration of them all, exact searches will always return the uupid. Wildcard searches will never return the uupid.

Suppose you are looking for pid1234. The filter:

uupid=pid1234

will return the entry with the uupid attribute since it is an exact search.

If you use the filter with a wildcard:

uupid=pid1234*

the entry will be returned, but will not contain the uupid attribute.

ED-ID

Binding to the directory with a service credential, typically a certificate via the SASL EXTERNAL authentication mechanism, provides access to the ED-ID view of the directory. ED-ID is used to look up information about users that is typically not public. This information can be used by applications for:

  1. Making business decisions
  2. Showing additional data about people
  3. Authorizing users

Access to ED-ID requires an ED Service, which is issued an X.509 certificate by the VT Middleware CA. The service certificate is used to perform TLS client authentication to the directory, which then allows us to bind using SASL EXTERNAL.

Entries in ED-ID include:

  1. People
  2. Addresses
  3. Groups
  4. Entitlements
  5. Organizations

The attributes available for view by ED services must be approved during the registration process. In this way, specialized views can be created for each ED service. Request an ED service.

Example

# search by uupid
ldapsearch -h id.directory.vt.edu -Z -Y EXTERNAL -b ou=People,dc=vt,dc=edu uupid=vtpid
# view your ED service
ldapsearch -h id.directory.vt.edu -Z -Y EXTERNAL -b ou=Services,dc=vt,dc=edu uusid=*

Schema

The Enterprise Directory Schema consists of the following object classes:

ED Usage Requirements

Examples

Hosts

Production

Pre-production

Development