---
title: Authentication keys
sidebar_label: 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:

```bash
/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.

### Using ssh-keygen

You can also use standard SSH keys:

```bash
# Ed25519 (recommended)
ssh-keygen -t ed25519 -f ~/.ssh/deephaven_key -C "username@deephaven"

# RSA (4096-bit)
ssh-keygen -t rsa -b 4096 -f ~/.ssh/deephaven_key -C "username@deephaven"
```

> [!NOTE]
> The `generate-iris-keys` utility is primarily for service accounts and inter-process communication. For end-user authentication, `ssh-keygen` is the standard approach.

## Registering public keys

### Import via CLI

Add a public key to the ACL store:

```bash
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:

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

### Delete a key

Remove a public key by its hash (obtain hash from `list --include-hash`):

```bash
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:

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

### Python client

```python
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](../configuration/public-and-private-keys.md) for complete client configuration options.

## Securing private keys

Private keys are equivalent to passwords. Protect them accordingly:

```bash
# 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.

## Related documentation

- [Public and private keys](../configuration/public-and-private-keys.md) - Complete server-side key configuration
- [Keys and keyfiles](../security/keys-and-keyfiles.md) - Security considerations
- [CLI ACL editor](./cli-acl-editor.md) - Command-line ACL management
- [Permissions overview](./permissions-overview.md)