Page History

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

General

When resetting the password, messages are sent in two rounds:1.

1. One is sent before we send a command to the RA, signaling the intent to perform a password change. At this point, the user can not abort.

...

1. One is sent after we have sent the command to the RA and received a response, with OK or Failed status.

Description of content can be found further down.

Delivery of these messages is done using Azure Event Grid, with Event Grid’s format for the delivered messages.
For you as the recipient, this means that we want access to an HTTPS endpoint for message delivery, where there will be a POST call with the audit message in the data field in the body. Delivery will be attempted up to 10 times within a 24 hour window, where a 200 OK response is the only one that will be interpreted as successful delivery. Messages are delivered at-least once, so there may be duplicate delivery of a single message.

Azure Event Grid has, by default, backoff on delivery and delayed delivery on multiple failed messages. Backoff means that the time between each retry attempt for the same message is increased with each failed delivery. Delayed delivery means that it will pause delivery entirely if multiple messages fail to deliver. These measures are to prevent further strain on a possibly strained system. 

Messages that we cannot deliver will be sent to storage for manual handling.

Authentication

Authentication methods supported for webhook delivery are one of these:

Table of Contents

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

1. Introduction

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.

1.1 Audit events in the future

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;

• App activation as OTP
• Automatic block of BankID certificate based on anti-fraud signals
• Biometric activation

2. Integration Steps

2.1. Send us required information

The required information is the following:

• Webhook url: This is the full URL you will receive events on. It has to be publicly accessible from the internet, in all environments.
• Authentication: One of
  • Static token: A static token sent in the Authorization header
  • AppId and TenantId: Application ID for our application registration in your Azure AD tenant and Tenant ID for your Azure tenant.

For further information regarding authentication, see separate bulletpoint bellow.

2.2. Validate subscription

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:

• WebHook-Allowed-Origin: One of two possible values; the same value as was sent in the WebHook-Request-Origin header or an asterix(“*”)
• WebHook-Allowed-Rate: An asterix(“*”) to indiciate no rate limitation, or a positive integer number to indicate requests per minute.

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

2.3. Receive audit events

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.

2.4. Example Cloudevents subscriber

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.

3. Handling Cloudevents

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.

3.1 Types

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.

3.2 Data fields

Data will be a json with the following specification;

3.3 Handle incorrect messages

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.

4. Security

4.1. Webhook URL

The following requirements for the webhook URL are absolute:

• It must be publicly accessible
• It must be available via HTTPS with a valid certificate
• It must accept Options and Post calls

4.2. Authentication

To prevent anyone from calling your subscription webhooks, there needs to be a layer of authentication. We support the following three options:

1. Client secret as query parameter
2. Static token in the authorization header
3. Azure AD App

Authorization header

For the static options 1 and 2, we must have an agreement on the 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>.

Azure AD App

For Azure AD AppFor option 3, you need to perform the following steps:

1. Create an Azure ADA pp AD app for your Webhook.
2. Create a service principal for for Microsoft.EventGrid if  if it doesn't already exist.
3. Create a role named AzureEventGridSecureWebhookSubscriber in the named AzureEventGridSecureWebhookSubscriber in the Azure AD app for your Webhook.
4. Create a service principal for the our event subscription writer app if  if it doesn't already exist.
5. Add service principal of event subscription writer Azure AD app to the AzureEventGridSecureWebhookSubscriber role
6. Add service principal of Microsoft.EventGrid to the AzureEventGridSecureWebhookSubscriber role as well

Link to source for these steps: https://learn.microsoft.com/en-us/azure/event-grid/scripts/powershell-webhook-secure-delivery-azure-ad-app 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: your

• Your Azure tenant ID

...

• appId of the Azure AD Apps that was created

...

Setup of delivery

Shortly after we have set up a sending of messages from our Event Grid to your endpoint, Azure Event Grid’s validation protocol will start. This validation can take place one of two ways:

1. Automatic, where your endpoint extracts the validationCode from the request body and respond with 200 OK, with a body containing the validationCode.
2. Manually, where you send a GET request to the URL located in the validationUrl field in the body of the request. Typically, you will then have to find the message in your system, and extract the URL from there.
   The URL can be opened in a browser, called with curl or any other option you prefer - the most important thing is that it is called with GET, and that it happens within the validity period of 5 (five) minutes.

Data content

The schema for the event is described on this page: [https://learn.microsoft.com/en-us/azure/event-grid/event-schema] (link to documentation at Azure). The audit message itself will then be in the data field, and has the following fields:

...

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

5. Troubleshooting

Validation of subscription fails

• Check that firewalls are open according to 4.1.
• Check that you accept the correct Content-Type("application/cloudevents+json; charset=utf-8")

6 Further documentation

...

time

...

String

...

2022-10-26T14:15:51.978Z

...

Execution timestamp(ISO8601)

...

Yes

...

status

...

String

...

BEGIN, SUCCESS, FAIL

...

SUCCESS

...

Status of the transaction.

...

Yes

...

statusInfo

...

String

...

...

...

Details information in case of failure

...

No

...

additionalInfo

...

String

...

...

...

Details information if applicable to action. Currently always empty

...

No

Documentation links

• Azure Event Grid: https://learn.microsoft.com/en-us/azure/event-grid/
• Endpoint validation with Azure Event Grid: https://learn.microsoft.com/en-us/azure/event-grid/webhook-event-delivery
• Event Grid CloudEvents Schema: https://learn.microsoft.com/en-us/azure/event-grid/cloud-event-schema
• Webhook delivery with Azure AD: https://learn.microsoft.com/en-us/azure/event-grid/secure-webhook-delivery