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.

The AP-API is a service implemented by a university or optionally by SWITCH. 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. If a member links by email address the attribute aggregator is triggered immediately and an affiliation is created with no delay.

Basic concept

The API specifies the following methods. Depending on the linking method, either search or list has to be implemented. The get method is always required.

  1. search a member by her eMail address. Only required for linking by eMail address.
  2. list the identifiers of all current members. Only required in the case of organizational linking services.
  3. get all attributes for a specific member. This method is always required.

This API covers the following IdM processes: 

IdM Process

API Method

 

Onboard: An new affiliation is created for a member of the organization

search eMail address: status code 200
A new member identifier was returned, for which there is no affiliation yet.

list members
A new member identifier appears in the list of current members, for which there is no affiliation yet.

Update: One ore more attributes of an existing member have changed (e.g. name change, or role change)

get attributes: status code 200
Some of the attributes of a member have changed.

 

Offboard: A member is leaving the organization and the affiliation is removed.

get attributes: status code 410
The member is not found in 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 administration portal.

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.0.0/16 and 2001:620::/40) or the two hosts that will query the API (130.59.117.81/16, 130.59.197.57/16, 2001:0620:0000:1005:021a:4aff:fede:001f/128, 2001:0620:0000:3005:021a:4aff:fedf:0002/128).
  • Only HTTP GET is allowed (read-only access). This means that the API could also 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: Search a member

Search a member of the organization by her organizational eMail address. This method is required for linking by eMail address.

Query URL format: https://<host>/<prefix>/affiliations/?email=<email>

Example: https://www.university.ch/api/affiliations/?email=john.doe@university.ch

This query returns a list of swissEduPersonUniqueID identifiers values of the member's accounts having the given e-mail address. In most cases, a member has not more than just one swissEduPersonUniqueID identifier.

  • The response content type is "application/json; charset=utf-8"
  • The response is a JSON array with objects containing a found member's swissEduPersonUniqueID value in the swissEduPersonUniqueID property.
  • Optionally, the objects containing in the array can contain the member's swissEduID identifier in the swissEduID property, if available. (It's recommended to include this value if available do support detecting possible linking conflicts.)

The response format is:

200 OK
Content-Type: application/json; charset=utf-8

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

or in case no user was found for the given e-mail address:

200 OK
Content-Type: application/json; charset=utf-8

[]

Example request/response:

GET prefix/affiliations/?email=john.doe@university.ch
Accept: application/json; charset=utf-8
...
200 OK
Content-Type: application/json; charset=utf-8

[
{"swissEduPersonUniqueID":"23ds903r232du@university.ch"}
]

Method: List identifiers of all members

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: Get attributes of a member

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.
  • If an affiliaiton is to be deleted, answer with response code 410

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@university.ch",
  "swissEduID":"ed106e5a-aef5-4890-9c11-b0346381613c",
  "givenName":"John",
  "surname":"Doe",
"mail":["john.doe@university.ch"], "swissEduPersonDateOfBirth": "19801126", "swissEduPersonGender": 1, "swissEduPersonStaffCategory":[32434, 43345], "eduPersonAffiliation":["staff","member"],
"eduPersonScopedAffiliation":["staff@university.ch","member@university.ch"],
"swissEduPersonHomeOrganization":"university.ch",
"swissEduPersonHomeOrganizationType":"university", "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"] }

Note: in the example above the following attributes are optional: DateOfBirth, Gender, StaffCategory, postalAddress, Entitlement. All other attributes are mandatory core attributes.

Attribute Provider API Hosting

-> see AP-API Hosting