> For the complete documentation index, see [llms.txt](https://icij.gitbook.io/datashare/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://icij.gitbook.io/datashare/server-mode/user-management.md).

# 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](/datashare/server-mode/user-management/oauth2.md)                               | External identity provider | Managed by IdP       | Organizations that already run an IdP (KeyCloak, Okta, GitHub, etc.) |
| [HTML form](/datashare/server-mode/user-management/form-auth.md)                         | PostgreSQL or Redis        | Yes                  | Self-managed deployments (**recommended** default)                   |
| [Basic with a database](/datashare/server-mode/user-management/basic-with-a-database.md) | PostgreSQL                 | No (browser-managed) | Legacy deployments already using it                                  |
| [Basic with Redis](/datashare/server-mode/user-management/basic-with-redis.md)           | Redis                      | No (browser-managed) | Legacy deployments already using it                                  |
| [Dummy](/datashare/server-mode/user-management/dummy.md)                                 | 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](/datashare/server-mode/user-management/form-auth.md) filter. If you already run an IdP, use [OAuth2](/datashare/server-mode/user-management/oauth2.md).

{% hint style="warning" %}
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.
{% endhint %}

## How it's configured

Two CLI flags select the authentication backend:

* `--authFilter`: the filter class that handles incoming requests (decides whether a request is authenticated, returns the challenge, and validates the session cookie).
* `--authUsersProvider`: the class that looks users up (by login or login+password). Only applies to filters that check credentials against a local store (form auth, basic auth). OAuth2 doesn't use it.

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

```
--authFilter org.icij.datashare.session.FormAuthFilter \
--authUsersProvider org.icij.datashare.session.UsersInDb
```

## Provisioning users

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:

  ```json
  {
    "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', 'foo@bar.com', '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](https://stackoverflow.com/questions/2987433/how-to-import-csv-file-data-into-a-postgresql-table).

#### 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"]}}'
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://icij.gitbook.io/datashare/server-mode/user-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.