BRP Kennisgevingen API

This is an API to subscribe to notification on changes to persons. Should be used in combination with the Haal Centraal Proxy API.

Reason

This API has been developed to replace functionality of MakelaarsSuite (MKS). It allows users to follow updates on the BRP.

Installation

Requirements:

• Python >= 3.13
• Recommended: Docker/Docker Compose (or pyenv for local installs)

Using Docker Compose

Run docker compose:

docker compose up

Navigate to localhost:8096.

Using Local Python

Create a virtualenv:

python3 -m venv venv
source venv/bin/activate

Install all packages in it:

pip install -U wheel pip
cd src/
make install  # installs src/requirements_dev.txt

Start the Django application:

export PUB_JWKS="$(cat jwks_test.json)"
export DJANGO_DEBUG=true

./manage.py runserver localhost:8000

Environment Settings

The following environment variables are useful for configuring a local development environment:

• DJANGO_DEBUG to enable debugging (true/false).
• LOG_LEVEL log level for application code (default is DEBUG for debug, INFO otherwise).
• AUDIT_LOG_LEVEL log level for audit messages (default is INFO).
• DJANGO_LOG_LEVEL log level for Django internals (default is INFO).
• PUB_JWKS allows to give publically readable JSON Web Key Sets in JSON format (good default: jq -c < src/jwks_test.json).

Deployment:

• ALLOWED_HOSTS will limit which domain names can connect.
• AZURE_APPI_CONNECTION_STRING Azure Insights configuration.
• AZURE_APPI_AUDIT_CONNECTION_STRING Same, for a special audit logging.
• CLOUD_ENV=azure will enable Azure-specific telemetry.
• STATIC_URL defines the base URL for static files (e.g. to point to a CDN).
• OAUTH_JWKS_URL point to a public JSON Web Key Set, e.g. https://login.microsoftonline.com/{tenant_uuid or 'common'}/discovery/v2.0/keys.
• OAUTH_CHECK_CLAIMS audience en issues checks for OAUTH

Hardening deployment:

• SESSION_COOKIE_SECURE is already true in production.
• CSRF_COOKIE_SECURE is already true in production.
• SECRET_KEY is used for various encryption code.
• CORS_ALLOW_ALL_ORIGINS can be true/false to allow all websites to connect.
• CORS_ALLOWED_ORIGINS allows a list of origin URLs to use.
• CORS_ALLOWED_ORIGIN_REGEXES supports a list of regex patterns fow allowed origins.

Developer Notes

Run make in the src folder to have a help-overview of all common developer tasks.

Package Management

The packages are managed with pip-compile.

To add a package, update the requirements.in file and run make requirements. This will update the "lockfile" aka requirements.txt that's used for pip installs.

To upgrade all packages, run make upgrade, followed by make install and make test. Or at once if you feel lucky: make upgrade install test.

Environment Settings

Consider using direnv for automatic activation of environment variables. It automatically sources an .envrc file when you enter the directory. This file should contain all lines in the export VAR=value format.

In a similar way, pyenv helps to install the exact Python version, and will automatically activate the virtualenv when a .python-version file is found:

pyenv install 3.13.1
pyenv virtualenv 3.13.1 brp-kennisgevingen-api
echo brp-kennisgevingen-api > .python-version

Test the application with mock data

To be able to test the functionality of the API we've included some initial mock data to test some scenarios. First load the fixtures using:

cd src
make load_fixtures

It is important to set environment variables for the OAUTH check claims to match the values in get_token.py:

export OAUTH_CHECK_CLAIMS="aud=0e1a03f2-4526-4159-a6dd-54236ad2006c,iss=https://issuer.test"

Retrieve a token using:

./get_token.py benk-brp-volgindicaties-api

And use this token in your API calls:

curl --request GET \
  --url http://localhost:8096/kennisgevingen/v1/volgindicaties \
  --header 'Authorization: Bearer ${token}'