Dataset Access Service

API Docs

REST API microservice enabling HTTP clients to view and manage user access to study datasets.

Table of Contents

• Main Concepts for Study/Dataset Access
• Deployment
  • Required Configuration
  • Optional Configuration
  • Template .env File

Main Concepts for Study/Dataset Access

These concepts apply to curated studies, but might eventually apply also to individual and community studies uploaded directly by endusers.

Studies may be: pubic, prerelease, private, controlled, and protected. Some require that the user sends a request for access (they will be prompted when attempting the action):

No request access needed or offered:

1. public: access to all functionality by default

2. prerelease: no request access mechanism offered. you see the study page

Request access needed:

1. private: request access to explore the data, analyze it and download (by default you only can see the study page)

2. controlled or protected: request access to download.

In controlled studies the user will be allowed to access the data automatically upon request submission, while in protected and private studies there will be human intervention in the decision.

There are 3 tables in accountDB (shared by prod and qa sites) for 3 types of users:

1. a staff member will have access to all studies, and if "owner" (bad name) they can access the dashboard and update the database with many possible actions affecting any of the 3 tables.

2. an end user : they ask for permission to access a study (that is how they become a row in the table), and we (staff owner or provider) approve or deny access.

3. a provider is a user who owns the data for a given study, there could be several providers, and if "is_manager", then this provider can add/remove other providers.

Deployment

Required Configuration

Authentication Salt

Used to authenticate user WDK session token values.

Value must be the MD5 hash of the entire salt file used by WDK sites.

Provided using

CLI	--auth-secret=<string>
ENV	AUTH_SECRET_KEY=<string>

LDAP Server

Defines the LDAP server(s) that are used to look up Oracle connection details.

Individual values must be formatted as <host.addr>:<port>, for example ldap.mysite.org:123.

Multiple servers may be specified using a comma to separate them: ldap1.mysite.org:123,ldap2.mysite.org:123

Provided using

CLI	--ldap-server=<string>
ENV	LDAP_SERVER=<string>

Oracle Base Distinguished Name

The base context in which Oracle database TNS Names will be resolved.

Required if the web service connects to Oracle database(s) using a TNS Name rather than individual connection details.

Example DN

cn=OracleContext,cn=MyTnsName,dc=Some,dc=Domain,dc=Component

Provided using

CLI	--oracle-base-dn=<string>
ENV	ORACLE_BASE_DN=<string>

Application DB TNS Name

Sets the TNS Name to use when connecting to an Oracle application DB instance.

Provided using

CLI	--app-db-ora=<string>
ENV	APP_DB_TNS_NAME=<string>

Application DB Username

Sets the connection username for the application DB that this web service will connect to.

Provided using

CLI	--app-db-user=<string>
ENV	APP_DB_USER=<string>

Application DB Password

Sets the connection password for the application DB that this web service will connect to.

Provided using

ENV	APP_DB_PASS=<string>

Account DB TNS Name

Sets the TNS Name to use when connecting to an Oracle account DB instance.

Provided using

CLI	--acct-db-ora=<string>
ENV	ACCT_DB_TNS_NAME=<string>

Account DB Username

Sets the connection username for the account DB that this web service will connect to.

Provided using

CLI	--acct-db-user=<string>
ENV	ACCT_DB_USER=<string>

Account DB Password

Sets the connection password for the account DB that this web service will connect to.

Provided using

ENV	ACCT_DB_PASS=<string>

SMTP Host

Used for sending emails this service will generate.

Provided using

CLI	--smtp-host=<string>
ENV	SMTP_HOST=<string>

Support Email

Used to set the ReplyTo value on emails sent from this service.

Provided using

CLI	--support-email=<string>
ENV	SUPPORT_EMAIL=<string>

Site URL

The base URL for the site to which this service is paired.

Provided using

CLI	--site-url=<string>
ENV	SITE_URL=<string>

Example

SITE_URL=https://clinepidb.org/ce

Optional Configuration

Server Port

Used to configure the port the web server to listens to.

Defaults to port 80 if unset.

Provided using

CLI	--server-port=<int16>
ENV	SERVER_PORT=<int16>

Application DB Connection Pool Size

Sets the connection pool size for the application DB that this web service will connect to.

Defaults to 20

Provided using

CLI	--app-db-pool-size=<int32>
ENV	APP_DB_POOL_SIZE=<int32>

Account DB Connection Pool Size

Sets the connection pool size for the account DB that this web service will connect to.

Defaults to 20

Provided using

CLI	--acct-db-pool-size=<int32>
ENV	ACCT_DB_POOL_SIZE=<int32>

Enable Email Debug

Sets the javax.mail.Session property mail.debug.

Defaults to false.

Provided using

CLI	--mail-debug=true|false
ENV	EMAIL_DEBUG=true|false

Registration Path

Path to the registration client component relative to the site URL.

Defaults to /app/user/registration.

Provided using

CLI	--registration-path=<string>
ENV	REGISTRATION_PATH=<string>

Application Path

Path to the dataset access management client component relative to the site URL.

Defaults to /app/study-access.

Provided using

CLI	--application-path=<string>
ENV	APPLICATION_PATH=<string>

Template .env File

# Required #############################

AUTH_SECRET_KEY=
LDAP_SERVER=
ORACLE_BASE_DN=

APP_DB_TNS_NAME=
APP_DB_USER=
APP_DB_PASS=

ACCT_DB_TNS_NAME=
ACCT_DB_USER=
ACCT_DB_PASS=

SMTP_HOST=
SUPPORT_EMAIL=

SITE_URL=

# Optional #############################

#SERVER_PORT=80
#APP_DB_POOL_SIZE=20
#ACCT_DB_POOL_SIZE=20
#EMAIL_DEBUG=false
#REGISTRATION_PATH=/app/user/registration
#APPLICATION_PATH=/app/study-access