6. Configuration

6.1. Introduction

DSB is configured using a configuration file that contains multiple sections, with each section holding multiple configuration variables. Section headings are enclosed in brackets. Configuration statements are of the form

variable = configuration

Where variable may be a string containing dots and configuration can be a unquoted string, a python array or a python dictionary.

Most configuration items are defined at install time and need not be changed after that. Some settings are specific to an installation and as such should be seen as user configurable.

6.2. User configuration settings

auth.method

What method to use to authenticate users. Supported methods are local, ldap and oauth2. Local indicates that DSB will have a local registration of known Principals together with their email address and passwords. Ldap indicates that only a relative distinguished name will be stored per Principal. OAuth2 indicates that only a username is stored locally per Principal.

The ldap authentication will bind using service credentials ldap.user and ldap.password . It will then determine the LDAP userPrincipalName for a given email address by searching for matching mail or userPrincipalName attributes. When found, it will rebind to the LDAP server using the userPrincipalName and the original supplied password. After that it will query for group membership using the memberOf attribute. This will fail with wrong credentials.

The oauth2 authentication will forward an authorization request to oauth2.authorize_url. Note that we expect this server to be a gitlab host, that knows both the user and projects that the user is associated with. The server that serves this url should perform login, and determine if we are authorised (check the supplied oauth2.client_id, ask the user if we are allowed to perform api interactions on his behalf), and return an authorization response. The gitlab api is then used to determine username and project group membership. After that the user will be provisioned using the group credentials if necessary.

ldap.server

The ldapserver to contact when auth.method is set to ldap.

ldap.domain

In binding to the ldap.server the supplied user login is understood as a username relative to a domain. The username together with the configured domain is put to the server for authentication. This allows users to provide only their username without having to remember the configured authentication domain. An example ldap.domain would be mydomain.com.

If the user supplies a domain, the user supplied domain is used for authentication.

ldap.base_dn

At authentication a test search is done to ensure that we have a valid user account. The test search will look for active groups defined for the authenticating user given the base_dn.

ldap.user

ldap.password

user and password to use when authenticating against the ldap server.

ldap.userdomain

The domain value that should be used when converting a known email address into a MS domain user id.

oauth2.authorize_url

The url that should be contacted by the browser of the client to start an oauth2 authorization session.

Note that this should be an https url.

oauth2.client_id

oauth2.client_secret

OAuth2 configuration secrets that need to be registered both here and at the OAuth2 server in order for us to be able to pose queries.

oauth2.name

OAuth2 configuration item that is presented to the user when we request authorization. Must typically also be registered together with oauth2.client_id`.

oauth2.callback_url

Similar to oauth2.name a configuration item that must be registered with the OAuth2 server. This also defines where the remote server can direct an authorization response. Typically <remote ip as seen from the oauth server>/oauth/callback

Note that this should be an https url.

oauth2.base_url

The base url where the gitlab api will be present.

Based upon the base_url is also the access token url. After authorization is received, OAuth2 requires retrieval of a limited time access token. This defines the url that the server needs to use to retrieve that token.

Note that where oauth2.authorize_url needs to be viewed and configured from the perspective of the client, this needs to be configured from the perspective of the server.

Note that this should be an https url.

oauth2.auth_timeout

The initial authorization request that we generate is valid for a limited amount of time set by this configuration item.

ui.oauth.button

Configure the frontend to show a button to login with the oauth2 server.

security.local_secret

Sensitive configuration items (like sftp connection credentials) will be stored in encrypted form for protection when data is at rest. This installation specific key is required for encrypting and decrypting those configuration items.

Note that this key cannot be changed after installation. If it is changed all stored encrypted configuration items will be lost.

Note that the application will not start without a key of sufficient length in the configuration file.

authcookie.timeout

Time to live in seconds for an inactive session to the application. After this much time of inactivity the session expires and the user is requested to login again. Default is 20 minutes.

authcookie.reissue_time

Time in seconds between session renewals. Typically 10% of the authcookie.timeout.

6.3. Backend API authentication settings

management.secret

The authentication secret used for calls to the backend APIs. The backend APIs are protected using JSON web tokens (JWT). Note: the default algorithm used is HS512, so make sure that your secret is at least 512 bits long (see RFC 2104 - HMAC).

jwt.private_key

Key used to hash or sign tokens.

jwt.public_key

Key used to verify token signatures. Only used for asymmetric algorithms.

jwt.algorithm

Hash or encryption algorithm. Defaults to HS512.

jwt.expiration

Number of seconds before a token expires.

jwt.leeway

Number of seconds a token is allowed to be expired before it is rejected.

jwt.http_header

HTTP Header used for tokens. Default is Authorization.

jwt.auth_type

Authentication type used in the Authorization header. Defaults to JWT. Not used when jwt.http_header is set to an other HTTP header.

6.4. Deidentification server settings

xapdeid.uri

URI that defines the location of the Aridhia Deidentification Server.

xapdeid.user xapdeid.password

Credentials for the Deidentification server that have administrator rights, i.e. the ability to create new projects.

xapdeid.timeout

The amount of time in seconds a single call to the Deidentification Server is allowed to take.

xapdeid.provision

Switch that determines if a project that is provisioned using the Provisioning API should be in turn be provisioned at the Deidentification Server.

xapdeid.verbose

Allow verbose logging of deidentification calls. Note that identifiers are not present as they are masked in the log output.

6.5. Export method settings

Depending on the configured export settings the user will get different methods to transfer data upstream, or be able to download a dataset.

export.fdw.enabled

Boolean switch that controls foreign data wrapper export. This facilitates a periodic update to an upstream datawarehouse.

export.fdw.workspace_server

DSN pointing to the upstream workspace server.

export.tablecopy.enabled

Boolean switch that controls table copy export. This facilitates a periodic table copy to an upstream database.

export.sftp.enabled

Boolean switch that controls sftp upload to a remote sftp server at any time. This requires a project that is provisioned with sftp server parameters.

export.sftp.hostkey

An array of ssh host keys in OpenSSH format that can be used to enumerate known target hosts.

export.sftp.timeout

The amount of time in seconds that will be waited for a remote host to respond to our actions.

export.xapsftp.enabled = true

Boolean switch that controls upload to a remote sftp server, with an dataset authorisation service interaction. The provisioned dataset owner must allow transfer of the current configured dataset before the actual export can be triggered.

export.csv.enabled

Boolean switch that controls the download of a dataset direct from the web ui.

6.6. Overriding nginx settings

DSB makes use of the nginx proxy. If the default values are not sufficient for an installation, the configuration files must be changed. This can be accomplished by e.g.:

• Creating a volume mount of /etc/nginx/conf.d/app.conf. If a modified version of this file is present on the host, the container will use that one instead of the one present in the container.

• Creating a Docker image based on the DSB image and use a COPY statement to insert a modified version of the /etc/nginx/conf.d/app.conf file.

In both cases, care must be taken to preserve the original behaviour of the supplied configuration file.