This integration guide is designed to help you, as a client receiving audit events from our service, set up and manage the integration. The standards used for delivering events are CloudEvents delivered through Webhooks over HTTPS.
When the user resets their BankID password, messages are sent in two rounds:
1. Introduction
1.1 Audit events in the future
2. Integration Steps
2.1. Send us required information
2.2. Validate subscription
2.3. Receive audit events
2.4 Example Cloudevents subscriber
3. Handling Cloudevents
3.1 Types
3.2 Data fields
3.3 Handle incorrect messages
4. Advanced Configuration
4.1. Webhook URL
4.2. Authentication
5. Troubleshooting
6. Further documentatin
From the Cloudevents documentation;
CloudEvents is a specification for describing event data in common formats to provide interoperability across services, platforms and systems.
By utilizing Cloudevents delivered to a Webhook over HTTPS, we adhere to standard protocols decoupled from specific libraries or SDKs. In this guide, we aim to provide you with the necessary information to set up a receiver capable of receiving audit events from our systems.
While the current integration only send audit events related to password reset, this will likely be expanded in the future with new messages. Some example use-cases for sending out audit events are;
The required information is the following:
For further information regarding authentication, see separate bulletpoint bellow.
Once we attempt to create the subscription, a subscription validation request will be sent to the provided URL by a HTTP Options call. A header, WebHook-Request-Origin, will be included in this request. It contains a DNS expression identifying the system sending the events. At the time of writing, this will be "eventgrid.azure.net"
To accept the subscription, reply with HTTP Status 200 and the following two headers:
There are more headers sent in the request, both standard http-headers and application-specific headers, but the headers mentioned here are the ones you have to strictly handle to validate the subscription
Events will be delivered in two rounds – one right before the reissue command is sent to FOI, and one right after indicating the status. These are sent asynchronously, meaning that the command might have been executed before you receive the events. If the delivery fails, a retry with exponential backoff will be retried on a best-effort basis. If the delivery still fails after 24 hours, the event is sent to our dead-letter storage for manual processing and debugging.
Response code for a successfull delivery must be one of 200, 201, 202, 203 or 204. A response code of 400, 401, 403, 404 and 413 will stop retries and put the event in our dead-letter event storage. Other failure codes will be retried as described above. If repeated failures occurs during a short time, all deliveries to the endpoint may be suspended for up to several hours.
An example implementation of a Cloudevents subscriber can be found here; https://github.com/BankIDNorge/example-cloudevent-subscriber
It is written in Typescript for Azure Functions.
A reworked example request from the Cloudevents documentation can be seen here:
POST /your-subscription HTTP/1.1
Host: webhook.example.com
Content-Type: application/cloudevents+json; charset=utf-8
Content-Length: nnnn
Authorization: a-token
{
"specversion" : "1.0",
"type" : "com.example.someevent",
... further attributes omitted ...
"data" : {
... application data ...
}
}
Two main things to note about the payload are the type and data fields.
Type will have one of two values:
no.bankid.bass.audit.reissue.init.v1 Used for events sent right before the reissue command is sent. This signals the intent that the user will now perform a password reset, and the user can no longer abort.
no.bankid.bass.audit.reissue.completed.v1 Used for events sent right after the reissue command is sent. This signals that the command has been sent, and will specify if the command was successful or failed.
Data will be a json with the following specification;
Parameter | Type | Possible values | Sample data | Description | Required |
---|---|---|---|---|---|
sessionid | String | 7468bdd3-274b-4e2f-b7bb-65dad59ce8a9 | SessionID of the transaction. Is only valid for a single password reset. | Yes | |
authentication | String | BIM | BIM | Authentication method used to identify the user | Yes |
action | String | REISSUE | REISSUE | Actual operation | Yes |
orderid | String | 1012-1667319077298 | OrderID of the BankID | Yes | |
time | String | 2022-10-26T14:15:51.978Z | Execution timestamp(ISO8601) of the reissue command. Not set for events with status=BEGIN | No | |
status | String | BEGIN, SUCCESS, FAILURE | SUCCESS | Status of the transaction. | Yes |
additionalInfo | String | Details information if applicable to action, like error message in case of failure | No |
While the messages are defined, typos and errors may occur on either end. As such, you need to have proper handling of errors related to the messages - such as, but not limited to, unknown type, unknown data fields, missing data fields, unknown data values etc.
If you discover incorrect messages, contact us for troubleshooting. Please include the full message and time of delivery.
The following requirements for the webhook URL are absolute:
To prevent anyone from calling your subscription webhooks, there needs to be a layer of authentication. We support the following three options:
For the static options, we need to agree on a routine for rolling the secret. You will also need to accept both the old and the new token, at least for a short periode of time, while we update our system with the new token. The format will be authorization: api-key <static-token>
.
For Azure AD App, you need to perform the following steps:
Link to source for these steps: Secure WebHook delivery with Azure AD Application in Azure Event Grid
Note that the link also contains a Powershell script which can perform the setup. For step 4, and the eventSubscriptionWriterAppId
variable, you'll need the relevant applicationID from us, which will be provided on request.
We have one app for test and one for production, so some or all of the steps will have to be duplicated depending on your setup. If you decide on creating one Azure AD App for the webhook in each environment, all but the second step will have to be duplicated. If you go for just one Azure AD App, only step 4 and 5 will have to be duplicated. appId for the two apps will be provided to you on request.
Once you have finished setting up the service principals, roles and Azure AD Apps, send us the following info: