This document lists all Middleware Web service operations and describes how to perform them in terms of required and optional inputs and expected outputs. All operations follow a few simple rules:

  1. Most requests require client authentication (HTTP Bearer, client TLS, or HTTP Basic)
  2. The content type of all responses is application/json
  3. Use the appropriate content type for requests that contain entity bodies
    • Content-Type: application/x-www-form-urlencoded for POST
    • Content-Type: application/json for PATCH
  4. Query result sort order varies by operation but strives for “natural sort order”
  5. 20x status on success
  6. 40x status on client errors (aka “Your Bad”)
    • 400 on bad input
    • 401 on missing authentication credentials
    • 403 on invalid authentication credentials
    • 404 on resource not found
  7. 50x status on server errors (aka “Our Bad”)

In the case of an error response, an error document is provided in the response body that provides details on the error(s) that caused the operation to fail. A sample error document for a single error scenario follows.

{
  "code": 400,
  "type": "PidStateException",
  "message": "PID must be in the 'To Be Released' state before it can be removed"
}

A sample error document for a multi-error scenario follows;

{
  "code": 400,
  "type": "MultiErrorException",
  "message": "BannerPIDM(12345)::Incomplete person update due to errors.",
  "details": [
    {
      "label": "Address(BannerAddressType(PR):BannerPhoneType(PR))",
      "message": "Invalid syntax for phone number: 95551939440.  Phone numbers must contain only digits and be exactly 10 digits long.",
      "type": "AddressInputException"
    },
    {
      "label": "Address(BannerAddressType(MA))",
      "message": "Invalid syntax for mailStop: abcd.  Mail stops must contain only digits and be exactly 4 digits long.",
      "type": "AddressInputException"
    }
  ]
}

The label entry is included only if a value is present.. The items in the details collection may be objects or strings.

Person Operations

The usual CRUD operations are supported for ED person resources.

Fetch Person

GET /v1/persons/[uid] Gets a single person resource by unique ID (uid).

Query for People

GET /v1/persons?[querystring] Get a list of person resources that satisfy one or more criteria. The following person-specific query parameters are supported:

  1. uupid: person’s PID account identifier
  2. mail: email address (includes accounts, aliases, and forwards)
  3. vtid: Virginia Tech ID (aka Hokie Passport number starting with 9)
  4. first: first name
  5. last: last name
  6. dept: department name (employees only)
  7. deptno: department number (employees only)

Results are sorted in alphabetical order by last name, then by first name, then by middle initial.

Account Operations

Shelve Account

Place an active account into shelved state, which begins the account deprovisioning process. Two forms are supported:

  1. Scheduling the account to be shelved at a future date by normal batch processes.
  2. Immediately shelving the account for a provided reason.

Examples of each version follow.

# Schedule shelving in the future
curl $BASE_URL/v1/accounts/nobody/shelve \
  -XPOST \
  -H"Authorization: Bearer $TOKEN" \
  -d date=1492450778


# Immediately shelve for administrative reason
# Use account transition codes for reason
curl $BASE_URL/v1/accounts/nobody/shelve \
  -XPOST \
  -H"Authorization: Bearer $TOKEN" \
  -d reason=FEE

Mailbox Operations

The usual CRUD operations are supported for ED mailbox resources.

Fetch Mailbox

Get a single mailbox resource by mailbox unique ID, i.e. the email account primary address.

curl $BASE_URL/v1/mailboxes/hammy@vt.edu \
  -XGET \
  -H"Authorization: Bearer $TOKEN"

The mailbox information included in the response is determined by optional with parameter(s), supporting any of:

  • addresses
  • state
  • all

Query for Mailboxes

Get a list of mailbox resources that satisfy one or more criteria.

curl $BASE_URL/v1/mailboxes?pid=hammy&type=gae \
  -XGET \
  -H"Authorization: Bearer $TOKEN"

will retrieve all Virginia Tech Auxiliary email accounts belonging to the person with the specified PID.

The following query parameters are supported:

  1. uid: Mailboxes belonging to the given person as identified by person unique ID, i.e. the person uid
  2. pid: Mailboxes belonging to the given person as identified by the person PID
  3. type: Mailboxes with the given email account type, any of [ge, gae, ce, cae, fe]
  4. state: Mailboxes with the given mail account state, any of [ACT, LKD, EXP, SLD, TBR]
  5. address: Mailboxes with the given mailbox unique ID, i.e the email account primary address
  6. alias: Mailboxes with the given mail account alias address
  7. forward: Mailboxes with the given email account forward address
  8. any: Mailboxes with the given email account address of any type (primary, alias or forward)
  9. exbefore: Mailboxes expiring prior the given date
  10. exafter: Mailboxes expiring after the given date

Any parameter that is an email address MUST be a fully-qualified address. Wildcards are supported for any of [pid, address, alias, forward, any].

OR semantics are used for a given parameter when it is repeated in the query. AND semantics are used to combine different parameters. Pagination is supported. Results are sorted in alphabetical order by email account mailbox name plus email account type.

Create Mailbox

Create a new mailbox resource in the Enterprise Directory.

curl $BASE_URL/v1/mailboxes \
  -XPOST \
  -H"Authorization: Bearer $TOKEN" \
  -d uid=123456789&address=hammygae@vt.edu&type=gae&password=cleartextpassword
  1. uid: Unique ID (uid) of owner person
  2. address: Email account primary address, a fully-qualified email address
  3. type: Email account type, any of [ge, gae, ce, cae, fe]
  4. password: Email account password

password MUST be included for email account types that require a password (all but fe) and MUST NOT be included otherwise.

Update Mailbox

Update a mailbox resource given an array of RFC 6902 JSON Patch documents that indicate the fields to update. Some updates require data for a single field

curl $BASE_URL/v1/mailboxes/hammy@vt.edu \
  -XPATCH \
  -H"Authorization: Bearer $TOKEN" \
  -H"Content-Type: application-json" \
  -d @- <<POSTDATA
[
  { "op": "replace", "path": "/preferredAddress", "value": "hammy.alias1@vt.edu" }
]
POSTDATA

while others require data for two fields.

curl $BASE_URL/v1/mailboxes/hammy@vt.edu \
  -XPATCH \
  -H"Authorization: Bearer $TOKEN" \
  -H"Content-Type: application-json" \
  -d @- <<POSTDATA
[
  { "op": "replace", "path": "/accountState", "value": { "state": "EXP", "reason": "EDA" } }
]
POSTDATA

The following mailbox resource fields are updatable via the replace operation with a single value:

  1. preferredAddress: Email account preferred address, which MUST be the fully-qualified address of an existing primary or alias email address
  2. routeType: Email route type
  3. setPassword: New password for the email account

The following mailbox resource fields are updatable via the replace operation with two values:

  1. accountState
    • state: Email account state
    • reason: Email account state transition reason
  2. changePassword
    • current: Current password of the email account
    • newpass: New password for the email account

Add Mailbox Alias

Add an alias to a mailbox resource.

curl $BASE_URL/v1/mailboxes/hammy@vt.edu/aliases \
  -XPOST \
  -H"Authorization: Bearer $TOKEN" \
  -d alias=hammy.alias1@vt.edu
  1. address: Mailbox unique ID of an existing mailbox resource, i.e. the email account primary address
  2. alias: New email account alias, a fully-qualified email address

Remove Mailbox Alias

Remove an alias from a mailbox resource.

curl $BASE_URL/v1/mailboxes/hammy@vt.edu/aliases/hammy.alias1@vt.edu \
  -XDELETE \
  -H"Authorization: Bearer $TOKEN"
  1. address: Mailbox unique ID of an existing mailbox resource, i.e. the email account primary address
  2. alias: Existing email account alias, a fully-qualified email address

Add Mailbox Forward

Add a forward to mailbox resource.

curl $BASE_URL/v1/mailboxes/hammy@vt.edu/forwards \
  -XPOST \
  -H"Authorization: Bearer $TOKEN" \
  -d forward=hammy@yahoo.com
  1. address: Mailbox unique ID of an existing mailbox resource, i.e. the email account primary address
  2. forward: New email account forward, a fully-qualified email address

Remove Mailbox Forward

Remove a forward from a mailbox resource.

curl $BASE_URL/v1/mailboxes/hammy@vt.edu/forwards/hammy@yahoo.com \
  -XDELETE \
  -H"Authorization: Bearer $TOKEN"
  1. address: Mailbox unique ID of an existing mailbox resource, i.e. the email account primary address
  2. forward: Existing email account forward, a fully-qualified email address

Group Operations

The usual CRUD operations are supported for ED group resources.

Fetch Group

Gets a single group resource by group unique ID, i.e. the dotted group name.

curl $BASE_URL/v1/groups/nobody.* \
  -XGET \
  -H"Authorization: Bearer $TOKEN"

Query for Groups

Get a list of group resources that satisfy one or more criteria.

curl $BASE_URL/v1/groups?uugid=nobody.* \
  -XGET \
  -H"Authorization: Bearer $TOKEN"

The following query parameters are supported:

  1. uugid: Group unique identifier, i.e. dotted group name
  2. crbefore: Groups created prior to the given date
  3. crafter: Groups created after the given date
  4. exbefore: Groups expiring prior to the given date
  5. exafter: Groups expiring after the given date
  6. administrator: Groups that contain given administrator (uupid/uusid)
  7. contact: Groups that contain given contact (uupid)
  8. manager: Groups that contain given manager (uupid/uusid)
  9. member: Groups that contain given member (uupid/uugid)
  10. viewer: Groups that contain given viewer (uusid)

The parameters that query groups by role (administrator, contact, member, etc) have OR semantics to support queries of the form “managed by X or administered by Y,” which are anticipated to be commonplace. Results are sorted in alphabetical order by group unique ID.

Create Group

Creates a new group in the Enterprise Directory with the given required parameters:

curl $BASE_URL/v1/groups \
  -XPOST \
  -H"Authorization: Bearer $TOKEN" \
  -d uugid=nobody.test-group&contact=pid1&administrator=pid2

The contact and administrator POST parameters are required but MAY appear multiple times. Note that group creation policy requires two distinct persons to fulfill the contact and administrator roles; while a single user can have both roles, at least two people need to be on record. Thus there cannot be a single administrator who is also a contact.

Update Group

Update a group resource given an array of RFC 6902 JSON Patch documents that indicate the fields to update.

curl $BASE_URL/v1/groups/nobody.test-group \
  -XPATCH \
  -H"Authorization: Bearer $TOKEN" \
  -H"Content-Type: application-json" \
  -d @- <<POSTDATA
[
  { "op": "replace", "path": "/displayName", "value": "Display Name" }
]
POSTDATA

The following group resource fields are updatable via the replace operation:

  1. activeDirectoryGroup
  2. displayName
  3. emailAddress
  4. expirationDate
  5. googleGroup
  6. suppressDisplay
  7. suppressMembers

The following group resource fields may be deleted via the remove operation:

  1. displayName
  2. emailAddress

Add Group Role

Add a person, service, or group to one of the defined roles in a group, e.g. members.

curl $BASE_URL/v1/groups/nobody.test-group/members
  -XPOST \
  -H"Authorization: Bearer $TOKEN" \
  -d kind=person&id=somepid&expiration=1487105175

The last path element must be one of the defined roles on a group:

  • administrators
  • contacts
  • managers
  • members
  • viewers

The following table describes the type of unique ID required for each supported kind of group role member:

Kind Unique ID Type
person pid
group uugid
service uusid

The expiration POST parameter is optional. If it is not specified, the role member has no expiration date.

Update Group Role

Update the expiration date of a group role member given an array of JSON patches. While an array of patches is supported, only one element should be provided.

curl $BASE_URL/v1/groups/nobody.test-group/members/somepid \
  -XPATCH \
  -H"Authorization: Bearer $TOKEN" \
  -H"Content-Type: application-json" \
  -d @- <<POSTDATA
[
  { "op": "replace", "path": "/expirationDate", "value": 1487105175 }
]
POSTDATA

Remove Group Role

Removes a person, service, or group from a group role, e.g. members.

curl  $BASE_URL/v1/groups/nobody.test-group/members/somepid \
  -XDELETE \
  -H"Authorization: Bearer $TOKEN"

Delete Group

Deletes a group from the Enterprise Directory.

curl  $BASE_URL/v1/groups/nobody.test-group \
  -XDELETE \
  -H"Authorization: Bearer $TOKEN"

Password Operations

Password compliance can be checked against enterprise rules for the following account types:

  • PID
  • AD (Active Directory)
  • Oracle
  • Banner

This service does not require client authentication.

Validate Password

POST /v1/password/validate Returns whether a password is valid with the following parameters:

  1. userid: identifier of the account to which the password would be assigned
  2. password: to validate
  3. type: any of [pid, ad, oracle, banner]
  4. with: any of [messages, details]

The response from this service always returns an array of results for each requested account type. If the type parameter is not supplied, all account types will be returned. If messages are requested you will receive a list of human readable sentences explaining what the password requires to successfully validate. Messages will be an empty list if the password is valid. If details are requested you will receive a list of error codes and parameters that provide information specific to each rule failure. Details will be an empty list if the password is valid.

Token Operations

Creation and deletion operations are supported for user JSON web token resources.

Create Token

Creates a new JWT which contains a password claim that can be used to authenticate against login.directory.vt.edu.

curl $BASE_URL/v1/tokens -XPOST -u $PID

Creation of a token requires HTTP Basic Authentication containing the user’s PID and password. The password used in this header conforms to the same standard used by login.directory.vt.edu as this authentication mechanism will invoke the user’s 2factor account.

This endpoint does not support GET, the new token is returned in the POST response. It is incumbent on the user to secure these tokens as they are a valid credential for the Enterprise Directory.

Sample payload for a token:

{
  "sub":"uid=123456,ou=People,dc=vt,dc=edu",
  "password":"TGfaFfpGx2PI0gPBCzzVr7Ef",
  "iss":"uusid=middleware,ou=Services,dc=vt,dc=edu",
  "exp":1500145052,
  "iat":1500058652
}

This token was issued for UID: 123456 at Jul 14 14:57:32 EDT 2017, expiring on Jul 15 14:57:32 EDT 2017. During the validity period the password claim can be used against login.directory.vt.edu without requiring 2factor authentication.

Delete Token

Deletes an existing JWT.

curl $BASE_URL/v1/tokens -XDELETE -H"Authorization: Bearer $TOKEN"

The token that is deleted is the token sent in the authorization header.

Service Operations

Whoami

GET /v1/whoami Returns the service that made the request. Includes:

  • uusid
  • accountState
  • certificates
  • expirationDate
  • creationDate
  • modificationDate
  • serviceDns
  • viewablePersonAttributes
  • webServiceAuthorizations

The with parameter can be used with any of:

  • contacts
  • administrators

This endpoint is useful for services to determine which attributes they can view, what certicates are associated with it, and what web service endpoints can be accessed.