Attribute Provider API (Pull Method)

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 e-mail 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: 

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

• 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).
  
• 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 in the attribute specification) MUST be used as attributes names.
• 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 or if the e-mail address is missing or contains an invalid value in the search-a-member query.
  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 e-mail 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.

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",
  "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.

Implementation hints:

• The response must include all core attributes, except for the Targeted ID.
• The response does not need to deliver interfederation core attributes. These attributes are derived from the core attributes by the AP-API service.
• The response must include all optional other attributes that are supported by the organizational IdP according to its configuration in the Resource Registry.

Attribute Provider API Hosting

Organisations that do not want to operate an instance of the Attribute Provider API can also use the Switch Attribute Provider API Hosting. This service requires that Switch gets read-only access to an LDAP server, a relational data base server or the Microsoft Graph API of the organisation.