Update Notifications API
The goal of this document is to describe the update notification feature of the BankID project. It provides guidance on how to understand and use the notification API.
How to read the guideline
The CAPITALIZED words throughout these guidelines have a special meaning as defined in RFC2119: the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.
- IDP - Identity Provider - A component on the side of the Bank which handles authorization and consent and issues tokens.
- OIDC - OpenID Connect - An authentication framework, it is a superset of the OAuth2 authorization framework.
- RP - Relying Party - RP is a party using the provider's identity services. From the bank's point of view, the Relying Party is BankID, and for BankID, it is the Service Provider.
- SeP - Service Provider - A third party which is registered in the BankID system and intends to consume Bank APIs.
- KYC - Know Your Customer - A Bank API which allows SePs to gather information about End-Users.
- JWT - JSON Web Token - A Base64 encoded, signed and possibly encrypted JSON document.
- JWK - JSON Web Key - A JSON describing keys for JWT encryption, description, signing and verification.
- The SeP wishes to be notified when the End-User makes changes to their information, for example when they update their email or change their name.
BankID has a universal system for back-channel update notifications. Currently, only the "claims changed" notifications are supported, but the system is built to be extensible enough to support other kinds of notifications as well. Notifications are delivered in the form of webhooks. Notifications are secured and verified using signed and encrypted JWTs. Notifications can be delivered en-masse through the use of event batching. Notification webhook endpoint MUST be registered using the dynamic registration API. Specific notifications (like the aforementioned "claims changed" notification) MUST be requested during the authorization call and MAY be presented to the user on the consent screen.
If the RP wishes to receive notifications, they MUST:
- expose the notification endpoint. This endpoint is very similar to the back-channel logout endpoint, so much so that the back-channel endpoint MAY be reused for notifications. This endpoint is described in the OpenAPI specification in this document for Service Providers and this document for Banks..
- register the notification endpoint to receive notifications. This is done using the notification_uri parameter defined for banks here. The Service Provider can set up this URI through the application configuration in the developer portal.
Notification format and security
- Notifications are delivered in the Notification Token defined in this document for Service Providers and this document for Banks.
- The Notification Token contains a list of Notification Events; these events are discriminated using the type property. Currently, only the claims_updated type is supported.
- The purpose of this complexity is to allow for batching and delayed notification delivery, while at the same time preventing unauthorized use and confidential information leakage.
Some notifications MAY require activation. The claims_updated notification requires a confirmation from the End-User on the consent screen. For this purpose, the scope notification.claims_updated MUST be requested during the Authorization Request. IDP MAY decide to show additional information or confirmation to the End-User on the consent screen.
Delayed notifications and batching
The IDP MAY delay notification delivery because of its internal processes and do it in a batch at a later point in time (for example at the end of day). This workflow is facilitated by the events property in the Notification Token, this property being an array and thus allowing batching. Delayed notifications are further supported by the optional original_event_at property of the Notification Event.
This notification will be generated when the IDP has received an update of a specific claim of the End-User, e.g. when the End-User has updated their email address. When the RP receives this notification, it MAY decide to update its now outdated information and re-request the UserInfo or Profile. If the RP wishes to be notified of this event, the RP MUST request this notification by requesting notification.claims_updated during the authorization flow.
IdP should follow these guidelines for publishing new events:
- If claim is one of AML attributes, IdP SHOULD send notification only in case when such claim is verified in Basic Registers.
If this change cannot be verified IdP SHOULD withhold notification for this claim until verification can be done. Other claims can be notified. If change of claim is obtained from Basic Registers, verification is not required.
- If claim is not one of AML attributes and therefore cannot be verified in Basic Register (i.e.: phone number or e-mail), IdP SHOULD send notification for this claim.
- IdP SHOULD prefer nightly batch processing of these notifications even in case it's consuming notifications from Basic Registers intraday.
This is recommended since BankID is expecting to have the majority of its traffic between 6 AM to 11 PM and will have more available processing capacity.
- Be sure to properly filter which notifications are sent. It is important to only notify about those End-User changes which the SeP does have a consent with appropriate scopes.
- Especially for the claims_updated event, the IDP MUST verify that for given SeP appropriate consent was obtained (with the notification.claims_updated scope) for this specific End-User.
Corresponding token does not necessary needs to be valid, this MAY be caused by fact that End-User gave consent for sending of notifications but did not give consent for issuing refresh token. SeP then needs to authenticate End-User once more at IdP to obtain changed data.
- IdP SHOULD allow End-Users to revoke consent for notification for given event type and SeP