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
andoauth2
. 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
andldap.password
. It will then determine the LDAPuserPrincipalName
for a given email address by searching for matchingmail
oruserPrincipalName
attributes. When found, it will rebind to the LDAP server using theuserPrincipalName
and the original supplied password. After that it will query for group membership using thememberOf
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 suppliedoauth2.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 toldap
.
-
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 exampleldap.domain
would bemydomain.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
andpassword
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.
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.
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.
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.
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 toJWT
. Not used whenjwt.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.