Standard for receiving audit-messages from BankID self-service (BASS)

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.

1. Introduction

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. This guide provides the necessary information to set up a receiver capable of receiving audit events from our systems.

1.1 Audit Events Overview

Current audit events include:

BankID app added as OTP
Password reset
Terms and conditions accepted

Future events may include:

Automatic block of BankID certificate based on anti-fraud signals
Biometric activation

Your integration should be designed to receive any event type and handle each appropriately.

2. Integration Steps

2.1 Send us required information

To establish the connection, provide:

Webhook URL: The fully qualified URL where you'll receive events. Must be publicly accessible in all environments.
Authentication method (choose one):
- Static token: A token sent in the Authorization header
- Azure AD: Application ID and Tenant ID for your Azure AD tenant

See Section 4.2 for detailed authentication requirements.

2.2 Validate subscription

When creating your subscription, a validation request will be sent to your URL via HTTP OPTIONS. This request includes a WebHook-Request-Origin header identifying our system (currently "eventgrid.azure.net").

To accept the subscription, respond with:

HTTP Status: 200
Headers:
- WebHook-Allowed-Origin: Either the exact value from WebHook-Request-Origin or "*"
- WebHook-Allowed-Rate: Either "*" (no rate limit) or a positive integer (requests per minute)

Important: The request will include more headers, but these specific headers must be handled to validate the subscription.

2.3 Example Implementation

Reference implementation: BankIDNorge/example-cloudevent-subscriber

This TypeScript implementation for Azure Functions demonstrates handling CloudEvents according to our specifications.

3. Handling CloudEvents

3.1 CloudEvents Format

A typical CloudEvent request looks like:

POST /your-subscription HTTP/1.1
Host: webhook.example.com
Content-Type: application/cloudevents+json; charset=utf-8
Content-Length: nnn
Authorization: <token>

{
    "specversion" : "1.0",
    "type" : "com.example.someevent",
    ... further attributes omitted ...
    "data" : {
        ... application data ...
    }
}

Key elements:

type: Identifies the event category and specific action
data: Event-specific payload containing the audit information

3.2 Event Types and Payloads

Currently supported event types include:

Additional event types will be documented as they become available.

3.3 Response Codes and Error Handling

When receiving events, your endpoint should respond with appropriate HTTP status codes:

Scenario	Response Code	Outcome

Scenario	Response Code	Outcome
Successful processing	200-204	Event marked as successfully delivered
Missing required fields	400	Event sent to dead-letter storage (no retry)
Authentication failure	401/403	Event sent to dead-letter storage (no retry)
Endpoint not found	404	Event sent to dead-letter storage (no retry)
Payload too large	413	Event sent to dead-letter storage (no retry)
Service temporarily unavailable	500-599	Event retried with exponential backoff for up to 24 hours

Error Handling Guidelines

Non-recoverable errors (400-series): Use for issues that won't be resolved by retrying (invalid format, missing fields)
Recoverable errors (500-series): Use for temporary issues where retrying might succeed (service unavailable, database timeout)
Persistent failures may result in temporary suspension of deliveries to your endpoint after 24 hours of retry attempts

3.4 Implementation Requirements

Schema Handling

Missing Required Fields: Reject the event with a 400 error to help identify issues in our event generation system
Schema Extensions: Your implementation must tolerate non-breaking additions to the event schema (new optional fields)
Change Management: We recommend implementing internal notifications when new fields are detected in events
Unmatched Events: Do not reject events that cannot be matched to your internal data sources; if the format is valid, accept the event

Troubleshooting Support

If you receive incorrect messages, get in touch and we will help you identify the issue. Please include the entire event and timestamp.

4. Security

4.1. Webhook URL Requirements

Your webhook endpoint must:

Be publicly accessible
Support HTTPS with a valid certificate
Accept both OPTIONS and POST HTTP methods
Implement proper authentication validation

4.2. Authentication

Choose one of the following authentication methods:

4.2.1 Static Token Authentication

A pre-shared token sent in the Authorization: Bearer <token> header.

Implementation considerations:

Implement a token rotation policy
During rotation, accept both old and new tokens temporarily
Store tokens securely, never in source code

4.2.2 Azure AD Application

Steps to configure:

Create an Azure AD app for your webhook
Create a service principal for Microsoft.EventGrid if it doesn't exist
Create a role named AzureEventGridSecureWebhookSubscriber in your webhook's Azure AD app
Create a service principal for our event subscription writer app
Add the service principal from step 4 to the AzureEventGridSecureWebhookSubscriber role
Add the service principal of Microsoft.EventGrid to the same role

Reference: Secure WebHook delivery with Azure AD Application

After configuration, provide us with:

Your Azure tenant ID
Application ID of the Azure AD App you created

4.2.3 Entra ID JWT

This method uses short-lived JWTs for improved security:

Token Validation Steps:
- Establish trust with Azure Entra ID v2. Documentation for setting up trust can be found here.
- Validate the token signature
- Verify token claims:
  - Application ID: Verify that the token was issued to the specific application dedicated to sending events.
  - Audience: Ensure the token is intended for your system.
  - Expiration: Confirm that the token is still valid and has not expired.
Implementation Requirements:
- Extract the JWT from the Authorization header
- Use standard JWT validation libraries
- Verify all required claims match expected values

Reference implementation available in the example-cloudevent-subscriber repository.

5. Troubleshooting

5.1 Subscription Validation Issues

If subscription validation fails:

Verify firewall rules allow access to your endpoint
Ensure your endpoint accepts `application/cloudevents+json; charset=utf-8` content type
Check that OPTIONS requests are properly handled
Verify that the required response headers are correctly set

5.2 Event Delivery Problems

If events are not being delivered:

Check authentication configuration
Verify your endpoint returns appropriate HTTP status codes
Inspect logs for any errors during event processing
Ensure your certificate is valid and trusted

5.3 Getting Support

If you encounter persistent issues:

Check our documentation for updates
Contact BankID support with specific event IDs and timestamps
Include detailed error logs and endpoint configuration

6. Further Documentation

Azure Event Grid Documentation: 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
Secure Webhook Delivery with Azure AD: https://learn.microsoft.com/en-us/azure/event-grid/secure-webhook-delivery
CloudEvents Specification: https://github.com/cloudevents/spec

BankID Norway Developer Portal