Setup configuration

Loading Services from a YAML file

This library provides a ConfigurationStep (from the library django-setup-configuration, see the documentation for more information on how to run setup_configuration) to configure any number of Services from a YAML file.

To make use of this, you must install the setup-configuration dependency group:

pip install zgw-consumers[setup-configuration]

To add this step to your configuration steps, add django_setup_configuration to INSTALLED_APPS and add the following setting:

SETUP_CONFIGURATION_STEPS = [
    ...
    "zgw_consumers.contrib.setup_configuration.steps.ServiceConfigurationStep"
    ...
]

The YAML file that is passed to setup_configuration must set the zgw_consumers_config_enable flag to true to enable the step and also provide services under the zgw_consumers namespace to configure Services.

You can use the following example YAML and adapt it to your needs:

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", "rc", "kic", "oc",
      # "ic", "pc", "ptc", "vrc", "tc", "bc", "cmc", "kc", "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", "oauth2_client_credentials"]
      # 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` or `oauth2_client_credentials`).
      # 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` or `oauth2_client_credentials`).
      # 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 by this 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

      # DESCRIPTION: How long a JWT is valid for, in seconds. This controls the 'exp'
      # claim (only used if auth type is `zgw`).
      # DEFAULT VALUE: 43200
      # REQUIRED: false
      jwt_valid_for: 43200

      # DESCRIPTION: OAuth2 token endpoint for client credentials flow. (Only needed if
      # auth type is OAuth2)
      # DEFAULT VALUE: ""
      # REQUIRED: false
      oauth2_token_url: example_string

      # DESCRIPTION: Optional OAuth2 scope (space-separated). Included in the token
      # request body if defined. (Only needed if auth type is OAuth2)
      # DEFAULT VALUE: ""
      # REQUIRED: false
      oauth2_scope: example_string