Django Setup configuration
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 to connect with external services
- class zgw_consumers.contrib.setup_configuration.steps.ServiceConfigurationStep
Configure Services to connect with external APIs
zgw_consumers_config_enable: true
zgw_consumers:
# DEFAULT VALUE: []
# REQUIRED: false
services:
-
# DESCRIPTION: A unique, human-friendly slug to identify this service. Primarily
# useful for cross-instance import/export.
# REQUIRED: true
identifier: example_string
# REQUIRED: true
label: example_string
# POSSIBLE VALUES: ["ac", "nrc", "zrc", "ztc", "drc", "brc", "cmc", "kc", "vrc",
# "orc"]
# REQUIRED: true
api_type: ac
# REQUIRED: true
api_root: example_string
# 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: example_string
# POSSIBLE VALUES: ["no_auth", "api_key", "zgw"]
# DEFAULT VALUE: "zgw"
# REQUIRED: false
auth_type: zgw
# DEFAULT VALUE: ""
# REQUIRED: false
client_id: example_string
# DEFAULT VALUE: ""
# REQUIRED: false
secret: example_string
# DEFAULT VALUE: ""
# REQUIRED: false
header_key: example_string
# DEFAULT VALUE: ""
# REQUIRED: false
header_value: example_string
# DESCRIPTION: NLX (outway) address
# DEFAULT VALUE: ""
# REQUIRED: false
nlx: example_string
# 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: example_string
# DESCRIPTION: Human readable representation of the user.
# DEFAULT VALUE: ""
# REQUIRED: false
user_representation: example_string
# DESCRIPTION: Timeout (in seconds) for HTTP calls.
# DEFAULT VALUE: 10
# REQUIRED: false
timeout: 10
API Configuration
- class openarchiefbeheer.config.setup_configuration.steps.APIConfigConfigurationStep
Configure API settings
api_configuration_enabled: true
api_configuration:
# DESCRIPTION: Which service to use to query the Selectielijst API.
# DEFAULT VALUE: null
# REQUIRED: false
selectielijst_service_identifier: example_string
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