Open Zaak configuration (admin)

Before you can work with Open Zaak after installation, a few settings need to be configured first.

Note

This document describes the manual configuration via the admin. You can perform most of this configuration via the command line, which is both faster and less error prone.

Setting the domain

In the admin, under Configuratie > Websites, make sure to change the existing Site to the domain under which Open Zaak will be deployed (see the manual for more information).

Note

Due to a cache-bug in the underlying framework, you need to restart all replicas for this change to take effect everywhere.

Note

The deprecation process for this domain configuration has started in favour of the OPENZAAK_DOMAIN setting. Some libraries still rely on this though, so it still needs to be provided.

Configure Notificaties API

Next, the notifications for Open Zaak must be configured. We assume you’re also using Open Notificaties to make a complete setup.

There are 2 things to keep in mind:

Open Zaak offers an Autorisaties API and thus the Open Zaak Autorisaties API must be consulted by the Notificaties API to check for autorisations.
Each component handles authentication themselves and thus we need to store the Client IDs and secrets in each component that wants to communicate with eachother.

Open Zaak

The configuration steps below need to be performed in Open Zaak itself.

Open Zaak consuming the Notificaties API

Configure the credentials for the Notificaties API (so Open Zaak can access the Notificaties API):
1. Navigate to API Autorisaties > Services
2. Select Click Service toevoegen (or select the notifications service if it already exists).
3. Fill out the form:
  - Label: For example: Open Notificaties
  - Type: Select the option: NRC (Notifications)
  - API root url: the full URL to the Notificaties API root, e.g. https://notificaties.gemeente.local/api/v1/
  - Client ID: An existing Client ID for the notifications service, or create one and configure the same value in Open Notificaties - For example: open-zaak
  - Secret: Some random string. You will need this later on!
  - Authorization type: Select the option: ZGW client_id + secret
  - OAS url: URL that points to the OpenAPI specification. This is typically $api_root + schema/openapi.yaml, for example: https://notificaties.gemeente.local/api/v1/schema/openapi.yaml
  - User ID: Same as the Client ID
  - User representation: For example: Open Zaak
4. Click Opslaan.
Next, configure Open Zaak to use this service for the Notificaties API:
1. Navigate to Configuratie > Notificatiescomponentconfiguratie
2. Select the service from the previous step in the Notifications api service dropdown.
3. Sending notifications support autoretry mechanism, which can be also configured here. Fill out the following properties:
  - Notification delivery max retries: the maximum number of retries the task queue will do if sending a notification failed. Default is 5.
  - Notification delivery retry backoff: a boolean or a number. If this option is set to True, autoretries will be delayed following the rules of exponential backoff. If this option is set to a number, it is used as a delay factor. Default is 3.
  - Notification delivery retry backoff max: an integer, specifying number of seconds. If Notification delivery retry backoff is enabled, this option will set a maximum delay in seconds between task autoretries. Default is 48 seconds.
4. Click Opslaan.

The Notificaties API consumes Open Zaak’s Autorisaties API

Open Notificaties checks the authorizations of its consumers by querying an Autorisaties API, which Open Zaak provides. Open Notificaties therefor is also a client of Open Zaak.

When Open Zaak publishes a notification, the Notifications API checks that Open Zaak is allowed to do this, via the Autorisaties API. Open Zaak must exist as an application in this API with the correct permissions.

Configure the Notificaties API access to the Autorisaties API:
1. Navigate to API Autorisaties > Applicaties
2. Click Applicatie toevoegen.
3. Fill out the form:
  - Label: For example: Open Notificaties
  - Client ID: For example: open-notificaties
  - Secret: Some random string. You will need this later on!
4. Click Opslaan en opnieuw bewerken.
5. Click Beheer autorisaties.
6. Select first Component Autorisaties API and scope autorisaties.lezen.
7. Select second Component Notificaties API and scopes notificaties.consumeren and notificaties.publiceren.
8. Click Opslaan
Finally, create an application with the correct permissions for Open Zaak itself:
1. Navigate to API Autorisaties > Applicaties
2. Click Applicatie toevoegen.
3. Fill out the form:
  - Label: For example: Open Zaak
  - Client ID: The same Client ID as given in Open Zaak consuming the Notificaties API, step 1c
  - Secret: The same Secret as given in Open Zaak consuming the Notificaties API, step 1c
4. Click Opslaan en opnieuw bewerken.
5. Click Beheer autorisaties.
6. Select Component Notificaties API and scopes notificaties.consumeren and notificaties.publiceren.
7. Click Opslaan

Currently, Open Zaak does not require any webhook subscriptions. It will however send notifications on various API actions.

We’re not there yet! We need to configure Open Notificaties too.

Open Notificaties

Configure the Open Zaak Autorisaties API endpoint (so Open Notificaties knows where to check for the proper autorisations):
1. Navigate to Configuratie > Autorisatiecomponentconfiguratie
2. Fill out the form:
  - API root: The URL to the Autorisaties API. For example: https://open-zaak.gemeente.local/autorisaties/api/v1/.
  - Component: Notificatierouteringscomponent
3. Click Opslaan.
Configure the Open Notificaties Notificatiescomponent API endpoint (so Open Notificaties receives changes made in the autorisation component of Open Zaak ):
1. Navigate to Configuratie > Notificatiescomponentconfiguratie
2. Fill out the form:
  - API root: The URL to the Notificaties API. For example: https://open-notificaties.gemeente.local/api/v1/.
3. Click Opslaan.
4. Webhook subscription toevoegen:
  - Callback Url: The Callback URL to the Notificaties Callback API. For example: https://open-notificaties.gemeente.local/api/v1/callbacks.
  - Client ID: The same Client ID as given in Open Zaak step 3c
  - Client Secret: The same Secret as given in Open Zaak step 3c
  - Channels: autorisaties
Configure the credentials for the Open Zaak Autorisaties API (so Open Notificaties can access the Autorisaties API):
1. Navigate to API Autorisaties > Externe API credentials
2. Click Externe API credential toevoegen.
3. Fill out the form:
  - API root: Same URL as used in step 1b.
  - Label: For example: Open Zaak
  - Client ID: The same Client ID as given in Open Zaak step 3c
  - Secret: The same Secret as given in Open Zaak step 3c
  - User ID: Same as the Client ID
  - User representation: For example: Open Notificaties
4. Click Opslaan.
Configure the credentials for the Open Notificaties API (so Open Notificaties can access itself):
1. Navigate to API Autorisaties > Externe API credentials
2. Click Externe API credential toevoegen.
3. Fill out the form:
  - API root: The URL to the Notificaties API. For example: https://open-notificaties.gemeente.local/api/v1/.
  - Label: For example: Eigen API
  - Client ID: The same Client ID as given in Open Zaak step 3c
  - Secret: The same Secret as given in Open Zaak step 3c
  - User ID: Same as the Client ID
  - User representation: For example: Open Notificaties
4. Click Opslaan.
We need to allow Open Zaak to access Open Notificaties (for authentication purposes, so we can then check its authorisations):
1. Navigate to API Autorisaties > Client credentials
2. Click Client credential toevoegen.
3. Fill out the form:
  - Client ID: The same Client ID as given in Open Zaak step 2c
  - Secret: The same Secret as given in Open Zaak step 2c
4. Click Opslaan.
Finally, we need to allow Open Notificaties to access Open Notificaties (for notifications purposes, so we can receive notificaties):
1. Navigate to API Autorisaties > Client credentials
2. Click Client credential toevoegen.
3. Fill out the form:
  - Client ID: The same Client ID as given in Open Zaak step 3c
  - Secret: The same Secret as given in Open Zaak step 3c
4. Click Opslaan.

All done!

Register notification channels

Before notifications can be sent to kanalen in Open Notificaties, these kanalen must first be registered via Open Zaak.

Register the required channels:

python src/manage.py register_kanalen

Create an API token

By creating an API token, we can perform an API test call to verify the succesful installation.

Navigate to API Autorisaties > Applicaties and click on Applicatie toevoegen in the top right.

Give the application a label, such as test or demo, and fill out a demo client ID and secret. Next, click on Opslaan en opnieuw bewerken in the bottom right. The application will be saved and you will see the same page again. Now, click on Beheer autorisaties in the bottom right, which brings you to the authorization management for this application.

Select Catalogi API for the Component field
Check the catalogi.lezen checkbox
Click Opslaan in the bottom right

On the application detail page, you can now select and copy the JSON Web Token (JWT) shown under Client credentials, which is required to make an API call.

Warning

The JWT displayed here expires after a short time (1 hour by default) and should not be used in real applications. Applictions should use the client ID and secret pair to generate JWT’s on the fly.

Making an API call

We can now make an HTTP request to one of the APIs of Open Zaak. For this example, we have used Postman to make the request.

Make sure to set the value of the Authorization header to the JWT that was copied in the previous step.

Then perform a GET request to the list display of ZaakTypen (Catalogi API) - this endpoint is accessible at {{base_url}}/catalogi/api/v1/zaaktypen (where {{base_url}} is set to the domain configured in Setting the domain).

GET request to Catalogi API — A GET request to the Catalogi API using Postman