Open Notificaties Configuration (CLI)

Using the setup_configuration management command

You can use the included setup_configuration management command to configure your instance from a yaml file as follows:

python manage.py setup_configuration --yaml-file /path/to/config.yaml

You can also validate that the configuration source can be successfully loaded, without actually running the steps, by adding the validate-only flag:

python manage.py setup_configuration --yaml-file /path/to/config.yaml --validate-only

Both commands will either return 0 and a success message if the configuration file can be loaded without issues, otherwise it will return a non-zero exit code and print any validation errors.

Your YAML file should contain both a flag indicating whether the step is enabled or disabled, as well as an object containing the actual configuration values under the appropriate key.

Note

All steps are disabled by default. You only have to explicitly include the flag to enable a step, not to disable it, though you may do so if you wish to have an explicit record of what steps are disabled.

Further information can be found at the django-setup-configuration documentation.

This projects includes the following configuration steps (click on each step for a brief descripion and an example YAML you can include in your config file):

Configuration for admin login via OpenID Connect

class mozilla_django_oidc_db.setup_configuration.steps.AdminOIDCConfigurationStep

Configure the necessary settings to enable OpenID Connect authentication for admin users.

This allows admin users to log in with Single Sign On (SSO) to access the management interface.

oidc_db_config_enable: true
oidc_db_config_admin_auth:

  # REQUIRED: true
  items:
    -

      # DESCRIPTION: a unique identifier for this configuration
      # REQUIRED: true
      identifier: admin-oidc

      # DESCRIPTION: Indicates whether OpenID Connect for authentication/authorization
      # is enabled
      # DEFAULT VALUE: true
      # REQUIRED: false
      enabled: true

      # DESCRIPTION: Mapping from user-model fields to OIDC claims
      # DEFAULT VALUE: {"email": ["email"], "first_name": ["given_name"], "last_name": ["family_name"]}
      # REQUIRED: false
      claim_mapping:
        email:
          - email
        first_name:
          - given_name
        last_name:
          - family_name

      # DESCRIPTION: The name of the OIDC claim that is used as the username
      # DEFAULT VALUE: ["sub"]
      # REQUIRED: false
      username_claim:
        - nested
        - username
        - claim

      # DESCRIPTION: The name of the OIDC claim that holds the values to map to local
      # user groups.
      # DEFAULT VALUE: ["roles"]
      # REQUIRED: false
      groups_claim:
        - roles

      # DESCRIPTION: If any of these group names are present in the claims upon login,
      # the user will be marked as a superuser. If none of these groups are present the
      # user will lose superuser permissions.
      # DEFAULT VALUE: []
      # REQUIRED: false
      superuser_group_names:
        - superusers

      # DESCRIPTION: The default groups to which every user logging in with OIDC will be
      # assigned
      # DEFAULT VALUE: []
      # REQUIRED: false
      default_groups:
        - read-only-users

      # DESCRIPTION: OpenID Connect scopes that are requested during login
      # DEFAULT VALUE: ["openid", "email", "profile"]
      # REQUIRED: false
      oidc_rp_scopes_list:
        - openid
        - email
        - profile

      # REQUIRED: true
      # This field can have multiple different kinds of value. All the
      # alternatives are listed below and are divided by dashes. Only **one of
      # them** can be commented out.
      # -------------ALTERNATIVE 1-------------
      # endpoint_config:
      #   # DESCRIPTION: URL of your OpenID Connect provider discovery endpoint ending with
      #   # a slash (`.well-known/...` will be added automatically). If this is provided,
      #   # the remaining endpoints can be omitted, as they will be derived from this
      #   # endpoint.
      #   # DEFAULT VALUE: ""
      #   # REQUIRED: false
      #   oidc_op_discovery_endpoint: http://keycloak.local:8080/realms/test/
      # -------------ALTERNATIVE 2-------------
      endpoint_config:

        # DESCRIPTION: URL of your OpenID Connect provider authorization endpoint
        # REQUIRED: true
        oidc_op_authorization_endpoint: http://keycloak.local:8080/realms/test/openid-connect/auth

        # DESCRIPTION: URL of your OpenID Connect provider token endpoint
        # REQUIRED: true
        oidc_op_token_endpoint: http://keycloak.local:8080/realms/test/protocol/openid-connect/token

        # DESCRIPTION: URL of your OpenID Connect provider userinfo endpoint
        # REQUIRED: true
        oidc_op_user_endpoint: http://keycloak.local:8080/realms/test/protocol/openid-connect/userinfo

        # DESCRIPTION: URL of your OpenID Connect provider logout endpoint
        # DEFAULT VALUE: ""
        # REQUIRED: false
        oidc_op_logout_endpoint: http://keycloak.local:8080/realms/test/protocol/openid-connect/logout

        # DESCRIPTION: URL of your OpenID Connect provider JSON Web Key Set endpoint.
        # Required if `RS256` is used as signing algorithm.
        # DEFAULT VALUE: ""
        # REQUIRED: false
        oidc_op_jwks_endpoint: http://keycloak.local:8080/realms/test/protocol/openid-connect/certs

      # DESCRIPTION: OpenID Connect client ID provided by the OIDC Provider
      # REQUIRED: true
      oidc_rp_client_id: modify-this

      # DESCRIPTION: OpenID Connect secret provided by the OIDC Provider
      # REQUIRED: true
      oidc_rp_client_secret: modify-this

      # DESCRIPTION: If enabled, the client ID and secret are sent in the HTTP Basic
      # auth header when obtaining the access token. Otherwise, they are sent in the
      # request body.
      # DEFAULT VALUE: false
      # REQUIRED: false
      oidc_token_use_basic_auth: false

      # DESCRIPTION: Algorithm the Identity Provider uses to sign ID tokens
      # DEFAULT VALUE: "HS256"
      # REQUIRED: false
      oidc_rp_sign_algo: HS256

      # DESCRIPTION: Key the Identity Provider uses to sign ID tokens in the case of an
      # RSA sign algorithm. Should be the signing key in PEM or DER format.
      # DEFAULT VALUE: ""
      # REQUIRED: false
      oidc_rp_idp_sign_key: modify-this

      # DESCRIPTION: Controls whether the OpenID Connect client uses nonce verification
      # DEFAULT VALUE: true
      # REQUIRED: false
      oidc_use_nonce: true

      # DESCRIPTION: Sets the length of the random string used for OpenID Connect nonce
      # verification
      # DEFAULT VALUE: 32
      # REQUIRED: false
      oidc_nonce_size: 32

      # DESCRIPTION: Sets the length of the random string used for OpenID Connect state
      # verification
      # DEFAULT VALUE: 32
      # REQUIRED: false
      oidc_state_size: 32

      # DESCRIPTION: Specific for Keycloak: parameter that indicates which identity
      # provider should be used (therefore skipping the Keycloak login screen).
      # DEFAULT VALUE: ""
      # REQUIRED: false
      oidc_keycloak_idp_hint: some-identity-provider

      # DESCRIPTION: Indicates the source from which the user information claims should
      # be extracted.
      # POSSIBLE VALUES: ["userinfo_endpoint", "id_token"]
      # DEFAULT VALUE: "userinfo_endpoint"
      # REQUIRED: false
      userinfo_claims_source: userinfo_endpoint

      # DESCRIPTION: If checked, local user groups will be created for group names
      # present in the groups claim, if they do not exist yet locally.
      # DEFAULT VALUE: true
      # REQUIRED: false
      sync_groups: true

      # DESCRIPTION: The glob pattern that groups must match to be synchronized to the
      # local database.
      # DEFAULT VALUE: "*"
      # REQUIRED: false
      sync_groups_glob_pattern: '*'

      # DESCRIPTION: Users will be flagged as being a staff user automatically. This
      # allows users to login to the admin interface. By default they have no
      # permissions, even if they are staff.
      # DEFAULT VALUE: false
      # REQUIRED: false
      make_users_staff: false

Configuration to connect with external services

class zgw_consumers.contrib.setup_configuration.steps.ServiceConfigurationStep

Configure one or more Service instances with their connection parameters and authentication credentials, which will allow this application to integrate with third-party systems in a consistent manner.

zgw_consumers_config_enable: true
zgw_consumers:

  # REQUIRED: true
  services:
    -

      # DESCRIPTION: A unique, human-friendly slug to identify this service. Primarily
      # useful for cross-instance import/export.
      # REQUIRED: true
      identifier: service-identifier

      # REQUIRED: true
      label: Short and human-friendly description of this service

      # POSSIBLE VALUES: ["ac", "nrc", "zrc", "ztc", "drc", "brc", "cmc", "kc", "vrc",
      # "orc"]
      # REQUIRED: true
      api_type: ac

      # DESCRIPTION: The root URL of the service that will be used to construct the URLs
      # when making requests.
      # REQUIRED: true
      api_root: https://example.com/api/v1/

      # DESCRIPTION: A relative URL to perform a connection test. If left blank, the API
      # root itself is used. This connection check is only performed in the admin when
      # viewing the service configuration.
      # DEFAULT VALUE: ""
      # REQUIRED: false
      api_connection_check_path: /some/relative/path

      # DESCRIPTION: The type of authorization to use for this service.
      # POSSIBLE VALUES: ["no_auth", "api_key", "zgw"]
      # DEFAULT VALUE: "zgw"
      # REQUIRED: false
      auth_type: zgw

      # DESCRIPTION: The client ID used to construct the JSON Web Token to connect with
      # the service (only needed if auth type is `zgw`).
      # DEFAULT VALUE: ""
      # REQUIRED: false
      client_id: modify-this

      # DESCRIPTION: The secret used to construct the JSON Web Token to connect with the
      # service (only needed if auth type is `zgw`).
      # DEFAULT VALUE: ""
      # REQUIRED: false
      secret: modify-this

      # DESCRIPTION: The header key used to store the API key (only needed if auth type
      # is `api_key`).
      # DEFAULT VALUE: ""
      # REQUIRED: false
      header_key: Authorization

      # DESCRIPTION: The API key to connect with the service (only needed if auth type
      # is `api_key`).
      # DEFAULT VALUE: ""
      # REQUIRED: false
      header_value: Token <modify-this>

      # DESCRIPTION: NLX (outway) address.
      # DEFAULT VALUE: ""
      # REQUIRED: false
      nlx: http://some-outway-adress.local:8080/

      # DESCRIPTION: User ID to use for the audit trail. Although these external API
      # credentials are typically used bythis API itself instead of a user, the user ID
      # is required.
      # DEFAULT VALUE: ""
      # REQUIRED: false
      user_id: client-id

      # DESCRIPTION: Human readable representation of the user.
      # DEFAULT VALUE: ""
      # REQUIRED: false
      user_representation: Name of the user

      # DESCRIPTION: Timeout (in seconds) for HTTP calls.
      # DEFAULT VALUE: 10
      # REQUIRED: false
      timeout: 10

Configuration for Autorisaties API

class nrc.setup_configuration.authorization.AuthorizationStep

Open Notificaties uses Autorisaties API to check permissions of the clients that make requests to Open Notificaties.

This step configures Open Notificaties to use the specified Autorisaties API. It is dependent on zgw_consumers.contrib.setup_configuration.steps.ServiceConfigurationStep to load a Service for this Autorisaties API, which is referred to in this step by authorizations_api_service_identifier.

autorisaties_api_config_enable: true
autorisaties_api:

  # DESCRIPTION: The identifier of the Autorisaties API service (which could be
  # defined in the previous `ServiceConfigurationStep`)
  # DEFAULT VALUE: null
  # REQUIRED: false
  authorizations_api_service_identifier: autorisaties-api

Configuration to create credentials

class vng_api_common.contrib.setup_configuration.steps.JWTSecretsConfigurationStep

Configure credentials for Applications that need access

vng_api_common_credentials_config_enable: true
vng_api_common_credentials:

  # REQUIRED: true
  items:
    -

      # DESCRIPTION: Client ID to identify external API's and applications that access
      # this API.
      # REQUIRED: true
      identifier: open-notificaties-prod

      # DESCRIPTION: Secret belonging to the client ID.
      # REQUIRED: true
      secret: modify-this

Configuration for Notificaties API Kanalen

class nrc.setup_configuration.kanalen.KanaalConfigurationStep

Configure Kanalen for Notificaties API

If Open Notificaties is being configured together with Open Zaak, this step can be used as a replacement for the register_kanalen command in Open Zaak, because that command requires Open Zaak to be able to make requests to Open Notificaties, which can cause issues when deploying multiple application at once.

To use this step as a replacement for register_kanalen, make sure to configure the Kanalen defined in the Open Zaak repository.

notifications_kanalen_config_enable: true
notifications_kanalen_config:

  # REQUIRED: true
  items:
    -

      # DESCRIPTION: List of possible filter attributes for a KANAAL. These filter
      # attributes can be used when creating an ABONNEMENT
      # DEFAULT VALUE: []
      # REQUIRED: false
      filters:
        - bronorganisatie
        - zaaktype
        - vertrouwelijkheidaanduiding

      # DESCRIPTION: Name of the KANAAL (also called "Exchange") that represents the
      # source.
      # REQUIRED: true
      naam: zaken

      # DESCRIPTION: URL to documentation.
      # DEFAULT VALUE: ""
      # REQUIRED: false
      documentatie_link: https://openzaak.local/ref/kanalen/#zaken

Configuration for Notificaties API

class nrc.setup_configuration.steps.NotificationConfigurationStep
notifications_config_enable: true
notifications_config:

  # DEFAULT VALUE: null
  # REQUIRED: false
  notifications_api_service_identifier: notificaties-api

  # DESCRIPTION: The maximum number of automatic retries. After this amount of
  # retries, guaranteed delivery stops trying to deliver the message.
  # DEFAULT VALUE: 5
  # REQUIRED: false
  notification_delivery_max_retries: 5

  # DESCRIPTION: If specified, a factor applied to the exponential backoff. This
  # allows you to tune how quickly automatic retries are performed.
  # DEFAULT VALUE: 3
  # REQUIRED: false
  notification_delivery_retry_backoff: 3

  # DESCRIPTION: An upper limit in seconds to the exponential backoff time.
  # DEFAULT VALUE: 48
  # REQUIRED: false
  notification_delivery_retry_backoff_max: 48

Configuration for Notificaties API Subscriptions

class notifications_api_common.contrib.setup_configuration.steps.NotificationSubscriptionConfigurationStep

Configure settings for Notificaties API Subscriptions

notifications_subscriptions_config_enable: true
notifications_subscriptions_config:

  # REQUIRED: true
  items:
    -

      # DESCRIPTION: The UUID for this subscription. Must match the UUID of the
      # corresponding `Abonnement` in Open Notificaties.
      # REQUIRED: true
      uuid: 02907e89-1ba8-43e9-a86c-d0534d461316

      # DESCRIPTION: Comma-separated list of channels to subscribe to
      # REQUIRED: true
      channels:
        - example_string

      # DESCRIPTION: A human-friendly identifier to refer to this subscription.
      # REQUIRED: true
      identifier: open-zaak

      # DESCRIPTION: Where to send the notifications (webhook url)
      # REQUIRED: true
      callback_url: https://example.com/api/webhook/

      # DESCRIPTION: Client ID to construct the auth token
      # REQUIRED: true
      client_id: open-notificaties

      # DESCRIPTION: Secret to construct the auth token
      # REQUIRED: true
      secret: modify-this

Configuration for Notificaties API Abonnementen

class nrc.setup_configuration.abonnementen.AbonnementConfigurationStep

Configure Abonnementen for Notificaties API

Note

The configured data here must correspond with the configured data from the previous step NotificationSubscriptionConfigurationStep

notifications_abonnementen_config_enable: true
notifications_abonnementen_config:

  # REQUIRED: true
  items:
    -

      # DESCRIPTION: The UUID for this Abonnement.
      # REQUIRED: true
      uuid: 02907e89-1ba8-43e9-a86c-d0534d461316

      # DESCRIPTION: A list of channels which are subscribed to
      # REQUIRED: true
      kanalen:
        -

          # DESCRIPTION: Key value mapping based on which notifications will be filtered
          # DEFAULT VALUE: {}
          # REQUIRED: false
          filters:
            zaaktype: 
              https://openzaak.local/catalogi/api/v1/zaaktypen/d109cd8a-fe7b-4eb2-8cab-766712a4a267

          # DESCRIPTION: The name of the channel
          # REQUIRED: true
          naam: zaken

      # DESCRIPTION: The URL to which notifications should be sent. This URL should
      # point to an API that is suitable to receive notifications.
      # REQUIRED: true
      callback_url: https://example.com/api/webhook/

      # DESCRIPTION: Content of the Authorization header when sending notifications to
      # the "Callback URL", for example: Bearer a4daa31...
      # REQUIRED: true
      auth: Token po4T8YpTZmeKXVWJAQCZ

Sites configuration

class django_setup_configuration.contrib.sites.steps.SitesConfigurationStep

This step configures one or more django.contrib.sites.Site objects

sites_config_enable: true
sites_config:

  # REQUIRED: true
  items:
    -

      # REQUIRED: true
      domain: example_string

      # REQUIRED: true
      name: example_string