Service Notifications

Services get up to date attribute information whenever a user logs in. If a service stores attributes, they may become outdated over time, especially if a user has not logged in for a longer period. The purpose of the SP notification API is to give SPs the possibility to subscribe to a set of attributes, and then getting a message if at least one of the monitored attribute values has changed for a user.

Typical applications

• Inform services of changes in current affiliations (i.e. when a student has left the university)
• Allow services to get up to date contact information (i.e. eMail address, postal address)

Current limitations

• Currently, notifications are not triggered if a user revokes consent to send attributes to the SP.
• Notifications are issued with a delay of up to 6min after the modification of an identity or an affiliation

Data protection

The edu-ID notification service only sends notifications under the following conditions:

• The service is only notified on attribute changes for attributes that the service can at maxmium receive for a user user (i.e. attributes that the service has declared as required or desired).
• As part of the notification request no personal data is sent but only the identifier (swissEduPersonUniqueID) of the user whose data changed. It is then the duty of the SP to query the current user data via a SAML attribute query (recommended for Shibboleth Service Providers only) or via the edu-ID Affiliation API or edu-ID User API.

Attribute update procedure

As a prerequisite the SP implements the RESTful SP Notification API via the https protocol, where it listens for notification messages issued by edu-ID.

The procedure to get attribute update for a user is as follows:

1. The edu-ID service detects the change of an attribute in the user's private identity or an affiliation of the user.
2. The edu-ID service then checks if there exists an SP that the user has accessed and that wants to be notified for one of the changed attributes.
3. The edu-ID service sends a notification message to the respective SP via the SP Notification API. The message contains the swissEduPersonUniqueID of the user account whose attribute has changed.
4. The SP receives the message and acknowledges.
5. The SP requests - if needed - the set of current attribute values of the user by issuing a SAML attribute request. (see documentation)

If the SP Notification API can't be reached, or if the SP does not acknowledge the reception of the message, the edu-ID service retries to send the notification message every hour for max. 48 hours.

SP Notification API

The SP Notification API is a webhook implemented by the SP. The edu-ID service sends notification messages to that API. The message only contains the swissEduPersonUniqueID of the person whose attribute has changed.

The SP Notification API is a drastically limited subset of the SCIM specification.

Example:

• Notification end point: https://example.com/api
• edu-ID unique ID of the user: 709429474319@eduid.ch

Request edu-ID → SP

edu-ID sends the swissEduPersonUniqueID (709429474319@eduid.ch) to the SP

PUT /Users/709429474319@eduid.ch
Host: cloud.switch.com
Accept: application/scim+json
Content-Type: application/scim+json

{
 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
 "id":"709429474319@eduid.ch"
}

A request like this can be sent for example with the following curl command:

Response SP → edu-ID

On success, the service responds with the same ID of the updated user:

HTTP/1.1 200 OK
Content-Type: application/scim+json
Location:
 "https://example.com/api/Users/709429474319@eduid.ch"

{
 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
 "id":"709429474319@eduid.ch"
}

If something is not ok, the SP should respond with:

• 404 Not Found (no user found with that unique-ID)
• 400 Bad Request (any other error)

Request Access to the SP Notification API

The following information has to be sent to eduid@switch.ch to register an SP for notifications:

• SAML/OIDC entity-ID of the requesting SP (e.g. https://service.example.org/shibboleth)
• API endpoint URL (e.g. https://service.example.org/service-notication.php).
  Please note that the swissEduPersonUniqueID of the user to notify changes for is appended to this URL when a notification takes place. The example URL to be notified will thus be: https://service.example.org/service-notication.php/709429474319@eduid.ch
• API HTTP basic authentication credentials (e.g. username: eduid, password: 238cowh3hr4h34)
• List of attributes for which the SP wants to recieve notification messages (check in AAI Resource Registry, which attribute your service requests)

Subscription Examples

To get notified on changes of one of the email addresses: Subscribe to changes for the attribute "Additional E-mail Address".

To get notified on changes (add/modify/remove) of one of the affiliations: Subscribe to changes for the attribute "Affiliations".

To get notified on account merges: subscribe to changes for the attribute "E-mail Address". The SP gets a notification for the maintained edu-ID account. To distinguish this notification from a simple change of email addresses the SP should check the merge history using the edu-ID Tools API.