Services (SP) 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.
- allow services to get up to date contact information (i.e. eMail address, postal address)
- inform services of changes in current affiliations (i.e. when a student has left the university)
- currently, notifications are not triggered
- if a user revokes consent to send attributes to the SP.
- notifications may be issued with a delay of up to 6h after the modification of an identity.
The edu-ID notification service only sends notifications under the following conditions:
- The service is only notified on attribute changes for attributes the user has released in the user consent dialogue (Exception: identifier attributes are not shown in the user constent).
Attribute update procedure
As a prerequisite the SP implements the RESTful SP Notification API with https protocol, where it listens for notification messages issued by edu-ID. The following information has to be sent to firstname.lastname@example.org to register an SP for notifications:
- the API endpoint
- the API basic authentication credentials
- the list of attributes for which the SP wants to recieve notification messages
- the entity-ID of the requesting SP
The procedure to get attribute update for a user is as follows:
- The edu-ID service detects the change of an attribute for which an SP has a notification subscription.
- The edu-ID service sends a notification message to the respective SP through the SP Notification API. The message contains the swissEduPersonUniqueID of the person whose attribute has changed.
- The SP receives the message and acknowledges.
- The SP requests 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.
SP Notification API
The SP Notification API is 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.
Notification end point: https://example.com/api
edu-ID unique ID of the user: email@example.com
Request edu-ID → SP
edu-ID sends the swissEduPersonUniqueID (firstname.lastname@example.org) to the SP
Response SP → edu-ID
On success, the service responds with the same ID of the updated user:
HTTP/1.1 200 OK
if not ok, the SP responds with:
- 404 Not Found (no user found with that unique-ID)
- 400 Bad Request (any other error)
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 account merges: subscribe to changes for the attribute "Additional 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 tools API.