Configure username/password authentication
This guide shows you how to configure username/password authentication for Deephaven.
Username/password is a common authentication method in which each user of an application has their own username and a secret password. The username says who the user is, and the password proves it.
Warning
The example configuration given in this guide is not recommended for use in a production environment. It is only meant to show a basic implementation that can be used as a template. Every user who logs in gets the same SuperUser context. A SuperUser context allows everything the Deephaven APIs allow, so the example handler doesn't limit what any user can do.
Overview
Username/password authentication needs some extra configuration on top of a Docker deployment of Deephaven. A PostgreSQL database that runs in Docker alongside Deephaven stores usernames and passwords. The database stores each password as a bcrypt hash. Bcrypt is a one-way hashing algorithm.
This guide covers the server setup and logging in from the JS API. For a basic setup, there are three required files:
- A SQL file to create a schema and a table of usernames and bcrypt-hashed passwords.
- A Dockerfile that builds the Deephaven image and adds the authentication JAR (a Java archive) to the Deephaven classpath, which is the list of libraries that the server loads at startup.
- A Docker Compose file that defines the PostgreSQL and Deephaven services.
Set up username/password authentication
SQL
Save the following as init-users.sql in the same directory as your Dockerfile and docker-compose.yml. It creates a schema, deephaven_username_password_auth, with a single table (users). The table has a single entry for a user named admin with the password p@ssw0rd.
The rounds column records the bcrypt cost factor of each hash. The cost factor is the exponent of a power of two that sets how many hashing rounds bcrypt runs. For example, a cost of 10 means 2^10 rounds. This example uses 10, which the $2a$10$ prefix of the hash records. The handler doesn't check rounds against the hash, so keep the two equal. See Add more users after startup for the value to use with a new hash.
Dockerfile
The Dockerfile adds the JAR file from the Overview to the Deephaven classpath. The Python example uses the server image, which starts a Python console.
Note
Make sure that the version in the FROM image tag matches the version of the authentication-provider JAR in the ADD URL. Both use version 42.7 in this example.
docker-compose.yml
Create docker-compose.yml in the same directory as the Dockerfile. The build: . line builds the Deephaven image from that Dockerfile. The file defines two services: postgres and deephaven.
The deephaven service's host port is configurable. The ports bullet below the Compose file explains how to change it.
Warning
The file below turns fsync off, which is not recommended. It also sets the postgres service's admin password to password in plaintext. See How to use secrets in Docker Compose to learn more about security best practices with Docker.
The START_OPTS value sets these Java options:
-Xmx4g: The maximum Java Virtual Machine (JVM) heap size.-DAuthHandlers: The authentication handler to use. Here, it is the SQL handler.-Dauthentication.basic.sql.jdbc.connection: The JDBC (Java Database Connectivity) URL of the user database. The handler can't log in without it.-Dauthentication.basic.sql.jdbc.userand-Dauthentication.basic.sql.jdbc.password: The database login that the handler uses to read theuserstable.
The JDBC URL uses postgres, the Compose service name, because containers reach each other by service name, not localhost.
The deephaven service also defines these settings:
ports: Maps the host port to port 10000 in the container. The host port comes from theDEEPHAVEN_PORTenvironment variable, which defaults to 10000. To change it, setDEEPHAVEN_PORTin your shell, or in a.envfile next todocker-compose.yml, before you rundocker compose up.volumes: Mounts./dataon the host to/datain the container.
The postgres service keeps its data across restarts. See Add more users after startup before you reset it.
Start Deephaven
Start Deephaven with docker compose up --build. Then open http://localhost:10000/jsapi/authentication/basic.html. The sample page fills in the admin username and the p@ssw0rd password from the SQL file. Click Go to log in. If you set DEEPHAVEN_PORT, replace 10000 in the URL with that host port.
Log in from the JS API
Applications that use the Deephaven JS API log in with a username and password from the users table, such as the admin login from Start Deephaven. Call login with type: dh.CoreClient.LOGIN_TYPE_PASSWORD, the username, and the password in token. The code below shows the call. Use the JS API shows how to load the API into a web page.
Replace http://localhost:10000 with the address of your server, in both the import and the client.
Add more users after startup
Each row in the users table stores a username, a bcrypt hash of the password, and the rounds value. Set rounds to the value in the hash's $2a$...$ prefix, as described in the SQL step. The examples in this guide use 10.
This step needs git and a Java Development Kit (JDK) on your machine, not only Docker.
To generate a hash, clone the Deephaven source repository, open a shell at its root, and run the generatePassword Gradle task. Replace newPasswordGoesHere with the password you want to hash:
Keep both layers of quotes. The outer single quotes stop the shell from expanding a $ in the password. The inner double quotes keep a password that contains spaces together as one argument when Gradle parses --args. Without the inner double quotes, Gradle splits a password that contains spaces into several arguments, so the hash doesn't match the password you intended.
By default, the generatePassword task prints a hash that starts with $2a$10$.
The postgres service doesn't mount a volume at its data directory, so Docker stores its data in an anonymous volume that a new container doesn't reattach. docker compose down removes the container, so the next docker compose up starts an empty database and runs init-users.sql again. To keep your users across restarts, use docker compose stop and docker compose start instead.
PostgreSQL runs init-users.sql only when the container starts with an empty data directory, which happens on its first start. To add users, insert new rows into the running database instead of editing the file.
Open a PostgreSQL command-line shell (psql) by running docker compose exec postgres psql -U postgres. Then run an INSERT statement with the hash that the generatePassword task printed and the matching rounds value:
After docker compose down, add any users you inserted earlier again.