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:
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):
- Student ID (SID)
- Employee ID (EID)
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:
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:
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:
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:
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:
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
The SSL certificate utilized by both the REST and LDAP services is signed by the InCommon Federation's Certificate Authority, which is itself signed by Comodo'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 one, or both, of these certificates in the appropriate area on your client.