Attribute Provider API

The edu-ID Attribute Provider API (AP-API) is the implementation of the organization pull interface. It is a simple and light-weight API that allows the edu-ID components (Attribute Aggregator) to make many fast, stateless queries to an API endpoint, which is operated by a university with edu-ID integration. To pull attributes, SWITCH does not need direct access to internal databases but just to the API. Also, the internal database structure does not have to be taken into account for each organisation by the edu-ID attribute aggregator.

The AP-API is a service implemented by a university. The only client accessing the AP-API is the Attribute Aggregator operated by SWITCH.

Typically, the attribute aggregator reads the list of organisational members once per day and updates the edu-ID affiliation database. The update cycle can be configured per organization.

Basic concept

The API implements two methods. It returns

  1. a list of identifiers of all current members
  2. all attributes for a specific member

This API covers the following IdM processes: 

IdM Process

API Method

A new member (e.g. a student) has been accepted at the organization

A new member appears in the list of current members, and all attributes of that member can be requested.

An attribute of an existing member changes (e.g. name change, or role change)

Some of the attributes of a member have changed.

A member is leaving the organization

A previously listed member disappears for the list of current members.

Temporary blocking and unblocking of the affiliation of a member is currently not supported by the API. If required it has to be done manually in the organisational administration interface.

General API characteristics

Easy to implement with no special libraries needed in most programming languages.
  • REST/JSON API via HTTPS
  • Authentication and Authorisation via HTTP Basic Auth. Optionally the server-side API should do an IP restriction to SWITCH network 130.59.* and 2001:620:0:*
  • Only HTTP GET is allowed (read-only access). This means that the API may be implemented in the form of static web pages!
  • Response content is UTF-8-encoded
  • Official LDAP names (as described on https://www.switch.ch/aai/support/documents/attributes/?view=ldap#coreattributes ) MUST be used as attributes names.
  • Two types of queries MUST be implemented:
    1. Query member-list: To request a list of (swissEduPersonUniqueID, swissEduID) tuples of all active users
    2. Query member-detail: To request attributes of a particular user with a given swissEduPersonUniqueID value
      • response code 200: an affiliation is created or updated
      • response code 410: an affiliaiton is deleted
  • The following HTTP Status codes MUST be returned:
     
    Status code Action
    200 Ok If operation was successful. The specified affiliation is created or updated.
    410 Gone If a user is not found for query member-detail. The specified affiliation is immediately removed. A former affiliation is added to the respective edu-ID account.
    404 Not Found If a user is not found for query member-detail. The specified affiliation will be removed after three consecutive 404 responses on three consecutive days.
    400 Bad Request If the input swissEduPersonUniqueID is missing in query member-detail
    401 Unauthorized If access was unauthenticated or unauthorized
    403 Forbidden If IP authorization is implemented and a request is from an unauthorized network address

Method 1: Query member-list

Get a list of all current organization members (swissEduPersonUniqueID, swissEduID) tuples

Query URL format: https://<host>/<prefix>/affiliations

Example: https://www.university.ch/api/affiliations 

This query returns a list of (swissEduPersonUniqueID, swissEduID) tuples of all current/active members of the university

  • The response content type is "application/json; charset=utf-8"
  • The response is a JSON object consisting of a regular array with all (swissEduPersonUniqueID, swissEduID) tuples as elements. The array values (tuples) are a hash map with the swissEduPesonUniqueID value stored in the key "swissEduPesonUniqueID" and the swissEduID value stored under the key "swissEduID"

The response format is:

[
  {"swissEduPersonUniqueID":"#uniqueid 1#", "swissEduID":"#swisseduid 1#"},
  {"swissEduPersonUniqueID":"#uniqueid 2#", "swissEduID":"#swisseduid 2#"},
  {"swissEduPersonUniqueID":"#uniqueid 3#", "swissEduID":"#swisseduid 3#"},
  ...
  {"swissEduPersonUniqueID":"#uniqueid n#", "swissEduID":"#swisseduid 4#"}
]

Example request/response:

GET prefix/affiliations
Accept: application/json; charset=utf-8
...
200 OK
Content-Type: application/json; charset=utf-8

[
  {"swissEduPersonUniqueID":"23ds903r232du@university.ch", "swissEduID":"1718D937-DE7B-481A-952F-D42DE3F94238"},
  {"swissEduPersonUniqueID":"sd8903riodsi8@university.ch", "swissEduID":"8152F1BA-B841-4164-A2B9-DEFC5792F0CD"},
  {"swissEduPersonUniqueID":"32r89cw89h3r@university.ch", "swissEduID":"CF3015A0-811D-41FE-BAAD-CC147E8F0624"},
  {"swissEduPersonUniqueID":"sc8ehiowehjsd@university.ch", "swissEduID":"E7326669-861D-44C6-9D5B-6F93E4A2652D"} 
]

Note: Tuple elements with null values are ignored, as if the tuple hasn't been listed at all.

Method 2: Query member-details

Get current attributes for an organization member identified by swissEduPersonUniqueID value

Query URL format: https://<host>/<prefix>/affiliations/<swissEduPersonUniqueID>

Example: https://www.university.ch/api/affiliations/23ds903r232du@university.ch

This query returns the attributes of a current member of the university identified by the input argument <swissEduPersonUniqueID>:

  • The Response content type is "application/json; charset=utf-8"
  • The response is a JSON object consisting of an associative array where the keys correspond to the official SWITCH LDAP attributes names.
  • Single valued attributes are treated as such in JSON
  • Values are either strings, numbers or arrays of strings/numbers.

The response format is:

  {
    "#key#":"#string value#",
    "#key#":#numeric value#,
    "#key#":["#string value 1#", "#string value 2#",...,, "#string value N#"], 
    "#key#":["#numeric value 1#", "#numeric value 2#",...,, "#numeric value N#"], 
    ...  
  }

Example request/response:

GET /api/affiliations/12345678@switch.ch
Accept: application/json; charset=utf-8
...
200 OK
Content-Type: application/json; charset=utf-8
...
{
  "swissEduPersonUniqueID":"12345678@switch.ch",
  "swissEduID":"ed106e5a-aef5-4890-9c11-b0346381613c",
  "givenName":"John",
  "surname":"Doe",
  "swissEduPersonDateOfBirth": "19801126",
  "swissEduPersonGender": 1,
  "swissEduPersonStaffCategory":[32434, 43345],
  "eduPersonAffiliation":["staff","member"],
  "postalAddress":["ETH Zentrum\n8092 Zürich\nSwitzerland","SWITCH\nWerdstrasse 2\n8021 Zurich\nSwitzerland"]
  "eduPersonEntitlement":["https://test.example.com/containing;escaped-semicolon","https://test.example.com/?containing=a$dollar-char","https://test.example.com/?containing=a\"quote"]
}