General
When resetting the password, messages are sent in two rounds:
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.
2. 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 two:
1. Client secret as query parameter
2. Static token in the authorization header
3. Azure AD
For options 1 and 2, we must have an agreement on the routine for rolling the secret.
For option 3, you need to perform the following steps:
- Create an Azure ADA pp for your Webhook.
- Create a service principal for Microsoft.EventGrid if it doesn't already exist.
- Create a role named AzureEventGridSecureWebhookSubscriber in the Azure AD app for your Webhook.
- Create a service principal for the event subscription writer app if it doesn't already exist.
- Add service principal of event subscription writer Azure AD app to the AzureEventGridSecureWebhookSubscriber role
- 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
Note that the link also contains a Powershell script which can perform the setup.
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 Azure tenant ID, the appId of the Azure AD Apps that was created, and the endpoint URL that should receive the message.
Tenant-id and appId are needed to set up which user our webhook will authenticate as in your AD.
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 | |
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 Schema: https://learn.microsoft.com/en-us/azure/event-grid/event-schema
- Webhook delivery with Azure AD: https://learn.microsoft.com/en-us/azure/event-grid/secure-webhook-delivery