Authentication keys

Deephaven supports key-based (challenge-response) authentication as an alternative to passwords. This method is recommended for:

Batch queries and automated processes — No interactive password entry required.
Service accounts — Secure, auditable access for system processes.
Enhanced security — Keys can be longer and more complex than passwords.

To authenticate using keys, the user must have a private key file, and the authentication server must have the corresponding public key registered.

Generating key pairs

Using Deephaven's key generator

Generate a Deephaven-format key pair:

/usr/illumon/latest/bin/generate-iris-keys username

This creates two files in the current directory:

pub-username.base64.txt — Public key (register with server)
priv-username.base64.txt — Private key (keep secure, give to user)

The utility generates ECDSA keys using the secp256r1 curve.

Registering public keys

Import via CLI

Add a public key to the ACL store:

sudo -u irisadmin /usr/illumon/latest/bin/dhconfig acls publickeys import \
  -f /path/to/pub-username.base64.txt

Note

Use the full absolute path to the public key file.

List registered keys

View all registered public keys:

sudo -u irisadmin /usr/illumon/latest/bin/dhconfig acls publickeys list

Delete a key

Remove a public key by its hash (obtain the hash from dhconfig acls publickeys list --include-hash):

sudo -u irisadmin /usr/illumon/latest/bin/dhconfig acls publickeys list --include-hash
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig acls publickeys delete --hash <hash>

Client configuration

After registering the public key, configure clients to use the private key.

Java system property

For batch queries and automated processes:

java -DAuthenticationClientManager.defaultPrivateKeyFile=/path/to/priv-username.base64.txt ...

Python client

from deephaven_enterprise.client.session_manager import SessionManager

session_mgr = SessionManager("https://deephaven.example.com:8000/iris/connection.json")
session_mgr.private_key("/path/to/priv-username.base64.txt")

See Public and private keys for complete client configuration options.

Securing private keys

Private keys are equivalent to passwords. Protect them accordingly:

# Restrict permissions to owner only
chmod 600 /path/to/priv-username.base64.txt

# Verify permissions
ls -l /path/to/priv-username.base64.txt
# Should show: -rw-------

Best practices:

Never share private keys.
Store in secure locations only.
Use separate keys for different purposes (user login vs. service accounts).
Rotate keys periodically.
Revoke keys immediately when compromised or no longer needed.

Pre-configured system keys

Deephaven installations include pre-generated keys for system processes in /etc/sysconfig/deephaven/auth/:

Key file	Purpose
`priv-iris.base64.txt`	Default admin/system operations
`priv-merge.base64.txt`	Merge server authentication
`priv-tdcp.base64.txt`	Table Data Cache Proxy
`priv-authreconnect.base64.txt`	Authentication server reconnection
`priv-controllerConsole.base64.txt`	Controller console operations

These are system-level keys and should not be used for regular user authentication.

Public and private keys - Complete server-side key configuration
Keys and keyfiles - Security considerations
CLI ACL editor - Command-line ACL management
Permissions overview