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, we need you to create a service principal for each of our two Azure AD Applications in your Azure AD tenant, one for test and one for production. These must be created with the appId for our azure applications, and appIds will be provided on request.
Furthermore, these service principals must get the necessary access to your endpoint, e.g. by granting the necessary Azure RBAC role to the service principal.
Once the service principals are created, 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:
Documentation links
- Endpoint validation with Azure Event Grid: [https://learn.microsoft.com/en-us/azure/event-grid/webhook-event-delivery](link)
- Event Grid Schema: [https://learn.microsoft.com/en-us/azure/event-grid/event-schema](link)
- Webhook delivery with Azure AD: [https://learn.microsoft.com/en-us/azure/event-grid/secure-webhook-delivery](link)