User management

Choosing how users sign in is the most important decision when deploying Datashare in server mode. It controls who can reach your documents, and changing it later usually means re-provisioning users.

Choosing a provider

Provider	User store	Sign-out	Best for
OAuth2	External identity provider	Managed by IdP	Organizations that already run an IdP (KeyCloak, Okta, GitHub, etc.)
HTML form	PostgreSQL or Redis	Yes	Self-managed deployments (recommended default)
Basic with a database	PostgreSQL	No (browser-managed)	Legacy deployments already using it
Basic with Redis	Redis	No (browser-managed)	Legacy deployments already using it
Dummy	None, accepts anything	No	Local development only (never expose to the network)

If you're starting from scratch and you don't have an identity provider, use the HTML form filter. If you already run an IdP, use OAuth2.

All providers except OAuth2 send credentials to Datashare directly. Always run Datashare behind TLS (a reverse proxy terminating HTTPS, for example) so credentials and session cookies aren't exposed on the network.

How it's configured

Two CLI flags select the authentication backend:

• --auth: the authentication method that handles incoming requests (decides whether a request is authenticated, returns the challenge, and validates the session cookie). Accepted values: oauth, form, basic, yesCookie, yesBasic (default: form).

• --authUsersProvider: where users are looked up (by login or login+password). Accepted values: database (default), redis, or a fully-qualified class name. Only applies to methods that check credentials against a local store (form auth, basic auth). OAuth2 doesn't use it.

For example, to use the HTML form method backed by a PostgreSQL user inventory:

--auth form \
--authUsersProvider database

Since these are the default values, an explicit --auth form --authUsersProvider database is equivalent to passing nothing at all.

The legacy --authFilter flag, which took a fully-qualified filter class name (e.g. org.icij.datashare.session.FormAuthFilter), is deprecated. Use --auth instead.

Provisioning users

The easiest way to create users is the datashare user create subcommand:

datashare user create alice --email [e-mail] --password $PW --groups project1,project2

You can also provision users manually, as described below. Form auth and both basic auth providers share the same user record format. Only the storage location differs (PostgreSQL table vs. Redis key).

Hash the password

Passwords are stored as sha256 hex digests. With bash:

$ echo -n bar | sha256sum
fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9  -

User record fields

Each user is a JSON object with at least:

• password: the sha256 hex digest computed above.

• groups_by_applications: a map of application name to the list of indices (projects) the user can access. The datashare key is required, and local-datashare should usually stay in the list. Add any extra indices the user should see:

  {
    "password": "fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9",
    "groups_by_applications": {
      "datashare": ["local-datashare", "myindex"]
    }
  }

Store the user

In PostgreSQL

Insert the user into the user_inventory table:

$ psql datashare
datashare=> insert into user_inventory (id, email, name, provider, details) values ('fbar', '[e-mail]', 'Foo Bar', 'my_company', '{"password": "fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9", "groups_by_applications":{"datashare":["local-datashare"]}}');

To create many users at once, use PostgreSQL's COPY statement to import a CSV.

In Redis

Store the user JSON under the login as key:

$ redis-cli -h my.redis-server.org
redis-server.org:6379> set foo '{"uid":"foo", "password":"fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9", "groups_by_applications":{"datashare":["local-datashare"]}}'