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: 

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.* and 2001:620:0:*
• 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

SWITCH offers Attribute Provider API hosting as add-on service for edu-ID. SWITCH implements and operates the AP-API for a client organization. The hosted AP-API responds to requests from the Attribute Aggregator. The user data is fetched directly from the directory of the organization.

SWITCH supports the following types of directories:

• LDAP based directory (e.g. Active Directory, OpenLDAP, etc).
• SQL based database (e.g. PostgreSQL, MySQL/MariaDB, MS SQL Server, etc.)
• Microsoft Azure AD via Graph API

Recommendations and requirements

Generally, access to the directory should be limited to the following IP addresses:

• 130.59.197.57
• 130.59.117.81
• 2001:620:0:3005:21a:4aff:fedf:2
• 2001:620:0:1005:21a:4aff:fede:1f

LDAP based directory:

• The LDAP directory needs to support encrypted LDAP connections via TLS/STARTTLS
• A dedicated service account is required for the AP-API
• The service account needs read-only access to all attributes that are required for the edu-ID affiliation.
• Access to other attributes, especially confidential attributes like password-hashes or other credentials, should be forbidden if possible.
• The AP-API will do all queries to the LDAP directory using the service account. (No BIND operations take place for regular users.)
• The LDAP directory needs to provide all information required to generate all edu-ID affiliation attributes supported by the client organization.
• The directory needs to provide an identifier that corresponds to the "swissEduPersonUniqueID" attribute (e.g. mS-DS-ConsistencyGuid).

SQL based database:

• The database needs to support encrypted connections via TLS/STARTTLS
• A dedicated database user is required for the AP-API
• This database user needs read-only access to all data/tables/views that are required for the edu-ID affiliation.
• The AP-API will do all queries to the database using this database user.
• It's recommended to provide a dedicated view for the AP-API to access the required data. This simplifies the SQL queries and limiting accessible data.
• The database needs to provide all information required to generate all edu-ID affiliation attributes supported by the client organization.
• The database needs to provide an identifier that corresponds to the "swissEduPersonUniqueID" attribute.

AAD via Graph API:

• To configure the attribute provider API via the Graph API the following data is needed:
  • Tenant Id
  • Client Id
  • Client Key/Secret
• A list of those attributes that should be used in affiliations.
• A dedicated AAD user is required for the AP-API with read-only permissions to the required attributes.
• A description on how certain attributes like the eduPersonAffiliation attribute can be derived/calculated on information retrieved via the Graph API (e.g. if Graph API user has value x in attribute y, then assign 'student' and 'member' as eduPersonAffiliation value)

Attribute Mapping:

• An important task of the hosted AP-API is mapping the attributes in the directory to SWITCHaai compliant attributes. This mapping has to be developed by SWITCH together with the identity management staff at the university.
• In many cases the minimal set of personal attributes is sufficient. According to the core attribute specification these are: First name, last name, organizational email address, role (student|staff|faculty|alum|affiliate) and an identifier.
• The organization has to set an identifier that will never change for a member, and that will never be reused for another member of the organization. Existing affiliations will be queried by this identifier.