SP Notification

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.

Typical applications

  • 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)

Current limitations

  • 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.

Data protection

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 eduid@switch.ch 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:

  1. The edu-ID service detects the change of an attribute for which an SP has a notification subscription.
  2. 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.
  3. The SP receives the message and acknowledges.
  4. 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.

Example:

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"
}

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 not ok, the SP responds with:

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

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