Enterprise Directory Service Person Data Access Mechanisms

After registering for access, and obtaining your access credentials, your application may request/consume Enterprise Directory Service (EDS) data in one of two manners:

1. REST/DSML

There are two separate RESTful web interfaces to EDS person data.

The EDS Lookup service  allows EDS person record lookups by specific attribute, supports searching with basic UA identifiers, and will return resutls in JSON, JSON-P or XML (see documentation for more information.) Although this is more flexible than the other RESTful interface, described below, it is not currently operating in a high-availability configuration (i.e., it is not running on multiple servers across multiple data centers). If you are consuming EDS data in support of mission-critical applications/services, we recommend that you use the existing DSML-only "EDS RESTful Person Service".

The EDS RESTful Person service provides a RESTful web interface to person data, which is returned in an XML format (specifically, DSMLv1). This service is a High Availablity service. This interface takes a simple HTTP GET request as input, using a unique identifier to locate the person for which to retrieve and provision attribute values. The identifier supplied in the request can be any of the following (the RESTful interface will automatically deduce the identifier type from the format):

  • UA_ID
  • Student ID (SID)
  • Employee ID (EID)
  • NetID

As this is a RESTful interface, each person is treated as a discrete resource with a globally unique URI endpoint. An example request, for the fictitious UA_ID "111222333444", would look like this:

https://eds.arizona.edu/people/111222333444

Access to this interface requires authentication, using the application username and password provided during the registration process. The username and password are transmitted to the REST service via standard HTTP Basic authentication and are encrypted via HTTPS.

Assuming that the resource (person) in the above example exists, the service will return a DSMLv1-formatted document:

<?xml version="1.0" encoding="UTF-8"?>

 

<dsml:dsml xmlns:dsml="http://www.dsml.org/DSML">

<dsml:directory-entries>

<dsml:entry dn="uaid=111222333444,ou=People,dc=eds,dc=arizona,dc=edu">

<dsml:attr name="studentId">

<dsml:value>S9999999</dsml:value>

</dsml:attr>

<dsml:attr name="studentAcademicProgram">

<dsml:value>084:BS:AL:MICR:</dsml:value>

</dsml:attr>

<dsml:attr name="uaId">

<dsml:value>111222333444</dsml:value>

</dsml:attr>

<dsml:objectclass>

<dsml:oc-value>arizonaEduStudent</dsml:oc-value>

<dsml:oc-value>top</dsml:oc-value>

<dsml:oc-value>person</dsml:oc-value>

<dsml:oc-value>eduPerson</dsml:oc-value>

<dsml:oc-value>inetOrgPerson</dsml:oc-value>

<dsml:oc-value>arizonaEduPerson</dsml:oc-value>

<dsml:oc-value>organizationalPerson</dsml:oc-value>

</dsml:objectclass>

<dsml:attr name="uid">

<dsml:value>johndoe</dsml:value>

</dsml:attr>

<dsml:attr name="studentTermStatus">

<dsml:value>084:U:FR:F:RM</dsml:value>

</dsml:attr>

<dsml:attr name="eduPersonPrimaryAffiliation">

<dsml:value>student</dsml:value>

</dsml:attr>

<dsml:attr name="mail">

<dsml:value>johndoe@email.arizona.edu</dsml:value>

</dsml:attr>

<dsml:attr name="sn">

<dsml:value>Doe</dsml:value>

</dsml:attr>

<dsml:attr name="studentAPDesc">

<dsml:value>Freshman - Bachelor of Science - Microbiology - 2008 Fall</dsml:value>

</dsml:attr>

<dsml:attr name="studentEmail">

<dsml:value>johndoe@email.arizona.edu</dsml:value>

</dsml:attr>

<dsml:attr name="cn">

<dsml:value>John X Doe</dsml:value>

</dsml:attr>

<dsml:attr name="studentInfoReleaseCode">

<dsml:value>M</dsml:value>

</dsml:attr>

<dsml:attr name="givenName">

<dsml:value>John X</dsml:value>

</dsml:attr>

<dsml:attr name="eduPersonAffiliation">

<dsml:value>member</dsml:value>

<dsml:value>student</dsml:value>

</dsml:attr>

</dsml:entry>

</dsml:directory-entries>

</dsml:dsml>

This example does not represent the entire set of EDS attributes that may be returned in a DSML response.  For details, definitions and semantics concerning the EDS schema, please refer to the EDS Attributes documentation.

For comparison purposes, the DSMLv1 response to a request for a non-existent (invalid) UA_ID would be as follows:

<?xml version="1.0" encoding="UTF-8"?>

 

<dsml:dsml xmlns:dsml="http://www.dsml.org/DSML">

<dsml:directory-entries/>

</dsml:dsml>

Retrieving, Parsing and Consuming the DSMLv1 response

As the DSMLv1 response is an XML document, you can parse it and consume it using your favorite XML parser or XPath library. Below is an example, using the PHP5 SimpleXML extension with an XPath query to retrieve and display the values of the eduPersonAffiliation attribute:

<?php

 

/*

* for our example, the username/password used to access

* the REST service is "user:password"

*/

$username = 'user';

$password = 'password';

$url = 'https://eds.arizona.edu/people/111222333444';

$cred = sprintf('Authorization: Basic %s', base64_encode($username.':'.$password));

$opts = array( 'http' => array ('method'=>'GET', 'header'=>$cred));

$ctx = stream_context_create($opts);

 

// send our request and retrieve the DSML response

$dsml = file_get_contents($url,false,$ctx);

 

// create SimpleXMLElement from response

$xml = new SimpleXMLElement($dsml);

 

// set namespace context for XPath query

$xml->registerXPathNamespace('dsml', 'http://www.dsml.org/DSML');

 

// retrieve all values for 'eduPersonAffiliation' attribute

$query = "//dsml:entry/dsml:attr[@name='eduPersonAffiliation']/dsml:value";

$vals = $xml->xpath($query);

 

// examine values

foreach($vals as $node) {

echo 'eduPersonAffiliation: ',$node,"\n";

}

?>

 


2. LDAP

The Enterprise Directory Service is based on an LDAPv3-compliant directory server and, as such, can be accessed via the LDAP protocol.  Access to the directory server is provided via the registration process, and uses the same access credentials (username/password) used to access the REST interface.  The attributes provided via the LDAP interface are identical to those provided via the REST interface; for details, definitions and semantics concerning the EDS schema, please refer to the EDS Attributes documentation.

The relevant information needed for accessing the EDS via LDAP is below:

  • Hostname: eds.arizona.edu
  • Port #: 636 (Note: directory may only be accessed via the LDAPS protocol; TLS is not supported)
  • Application authentication DN base: ou=App Users,dc=eds,dc=arizona,dc=edu
  • Authentication attribute: uid (the DN used to authenticate will be of the form uid=<appuser>,ou=App Users,dc=eds,dc=arizona,dc=edu)
  • Search base: ou=People,dc=eds,dc=arizona,dc=edu

Searching the Directory and Retrieving Entries

One major difference between the RESTful interface and LDAP is that REST is oriented around resources (i.e. retrieving attributes for a single person) whereas LDAP is oriented around generalized queries (search filters). Following is an example of performing a search and retrieving attributes using the PHP5 LDAP extension

<?php

 

// setup LDAP parameters

$ldapUrl = "ldaps://eds.arizona.edu";

$bindDn = "uid=user,ou=App Users,dc=eds,dc=arizona,dc=edu";

$bindPw = "password";

$searchBase = "ou=People,dc=eds,dc=arizona,dc=edu";

$searchFilter = "(uaid=111222333444)";

 

// establish LDAP connection

$ldap = ldap_connect($ldapUrl);

if (! $ldap) {

error_log("Could not connect to LDAP server");

}

 

// bind as app user

if (! ldap_bind($ldap, $bindDn, $bindPw)) {

error_log(ldap_error($ldap));

}

 

// perform search

if (($sr = ldap_search($ldap, $searchBase, $searchFilter)) == FALSE) {

error_log(ldap_error($ldap));

}

 

// retrieve entry

$entry = ldap_first_entry($ldap, $sr);

if ($entry) {

$vals = ldap_get_values($ldap, $entry, "eduPersonAffiliation");

 

// examine values

foreach($vals as $v) {

echo 'eduPersonAffiliation: ',$v,"\n";

}

}

 

ldap_close($ldap);

?>


Additional Information

The SSL certificate utilized by both the REST and LDAP services is signed by DigiCert's Root CA.  If your LDAP or HTTP client library complains about not being able to validate the SSL certificate presented by EDS, you may need to download and install this root certificate in the appropriate area on your client.