Texas A&M University - Infrastructure Services

Enterprise Directory Search Web Service: Technical Requirements and Information

Overview

The enterprise directory search web service allows registered applications to query for information about a person in the People branch of the Enterprise Directory (ldap.tamu.edu).

Directory Service Payload

The default payload for the directory search web service is:

  • Directory Entry Distinguished Name (dn)
  • Common Name (cn)
  • First Name (gn)
  • Last Name (sn)
  • Email Address (mail)
  • Employee Public Office Telephone Number (telephoneNumber)
  • Employee/Affiliate Primary Department (tamuEduPersonDepartmentName)

The payload returned by the directory search web service can be customized to include additional data. To receive additional data, access to the data must be approved. The Access Request page provides details about this process.

Signing Messages

All messages sent to the directory search web service should include a RSA signature of the "data" portion of the message. The message is signed using the private key associated with the public key provided when registering the application. Both the signature and the data must be base64-encoded after signing, to prevent transcoding errors. Likewise, messages from the directory search web service will be signed using the service's private key and and then base64-encoded before being sent to the client application.

Protocol

To obtain data, a registered client application will do the following:

  • submit a request
  • wait a short period of time and then attempt to retrieve the response

Submitting a Request

The client application will POST the following to https://mqs.tamu.edu/queue/yourApplicationURN/directory/services/search/:

  • data: base64 encoded JSON representation of an object with one or more of the following members:
    • tamuEduPersonUIN (string): UIN
    • tamuEduPersonNetID (string): NetID
    • cn (string): Common Name (wildcard searches may be available by special request)
    • smb (string): any identifier (NetID and email aliases) used by account owner
  • signature: base64 encoded signature of the data JSON string.
    Note: data should be signed before it is encoded in base64.

Possible Results

201 - Resource created. A URL has been created where the response can be retrieved. The URL is listed in the Location header of the result message. The content of the result message is a JSON string with the following (provided mainly for debugging):

  • urn (string): URN of the calling service
  • result (int): Result forwarded from queueing service
  • transaction_id: Transaction ID that can be used to trace a particular request

403 - Not Authorized. The URN/Service IP Address/Resource combination was not found, or an element of that combination has been revoked.

405 - A method other than POST was used on the URL.

Retrieving a Response

Client will GET the address returned in the 201 result above.

Possible Results

204 - URL is valid, but there is no message available to return.

200 - URL is valid, and there is a message. The following is returned in a JSON encoded object in the content of the response:

  • data (string): base64 encoded response from the directory service. The data content depends on whether the request was successful or not:
    • If the request was successful, a JSON representation of an array with the attributes the client application is eligible to receive.
    • If the request was not successful, a JSON representation of an object with the following:
      • error (string): Description of the error that occurred
      • validation_errors (object, optional): Errors that occurred during validation (if the validation step was reached)
  • signature (string): base64 encoded signature for the data provided.
    Note: signature is of the decoded data.
  • transaction_id (string): transaction ID provided in the response above, used for auditing and debugging
  • urn (string): URN of the calling service

403 - The URN/IP Address provided by the client application is not authorized to retrieve the requested message.

404 - The queue that the URL requested does not exist.

405 - A method other than GET was used on the URL.

Client Application Code

Client application code is available on the Sample Code page.

Registering Your Application

Applications must be registered before they can connect to the directory search web service. To register your application, send an email with the following information to helpdesk@tamu.edu:

  • IP address(es) for your application
  • a public key for your application
    The directory search web service requires all messages to be signed.
  • Technical Contact name and email address

CIS supports several web services so please state that you are wanting to register an application with the directory search web service in your email.

After your application is registered, you will be given:

  • a URN for your application
  • the public key for the directory search web service