---
title: Private key login
sidebar_label: Private key login
---

This document describes private key "challenge-response" authentication to Deephaven, including server-side public key authorization and client-side private key files.

Private key login is intended for non-interactive clients (batch jobs, automation, service accounts) that cannot prompt for a password or complete SAML login flows, or for command-line utilities like [`dhconfig`](../../configuration/dhconfig/overview.md).

At a high level:

- A client generates [public and private keypair files](../../admin-glossary.md#private-key-login-keypair-files).
- An administrator authorizes the public key to log in as a particular [Deephaven User](../../admin-glossary.md#deephaven-user).
- The client uses the private key to authenticate by signing a nonce from the [Authentication Server](../../core-components/authentication.md) to prove identity.
- The Authentication Server validates that the nonce was signed by an authorized public key, records the user's login, and returns an authentication token.
- The client supplies the authentication token when it requests access to data or to execute code.
- The authentication token must be regularly refreshed, as it expires within, by default, 10 minutes.
- System administrators can [rotate or revoke](#rotation-and-revocation) public keys to prevent future logins with the private key.

Private key login still authenticates a Deephaven user. In a private keypair file, `user` is the authenticated Deephaven user proven by the private key and `operateas` is the effective Deephaven user for Deephaven authorization checks. When `operateas` equals `user`, the session acts as that same Deephaven user. When `operateas` differs from `user`, the login succeeds only if [`localsuperusers` (`superusers.txt`)](#localsuperusers-superuserstxt) permits that authenticated user to operate as the requested effective user.

This is different from [run-as / per-user workers](../../configuration/per-user-workers.md):

- `operateas` changes the [Deephaven user](../../admin-glossary.md#deephaven-user) identity used for authorization.
- run-as changes which [OS service account](../../admin-glossary.md#deephaven-service-accounts) executes workers.

## Generate public and private "keypair files"

Run `generate-iris-keys` and choose a key name:

```bash
/usr/illumon/latest/bin/generate-iris-keys keyname
```

This generates two files in the current directory:

- `pub-<keyname>.base64.txt`: a public keypair file.
- `priv-<keyname>.base64.txt`: a private keypair file.

## Client usage (private key file)

> [!WARNING]
> The private key in the private keypair file is effectively a password. Do not paste private key material into tickets/chat/email. Restrict filesystem permissions and limit access to only the service account(s) that need it.

### Java client

Java clients will use a [private keypair](#private-keypair-file-priv-base64txt) file to authenticate if the system property `AuthenticationClientManager.defaultPrivateKeyFile` is set to a path.

```bash
java \
  -DAuthenticationClientManager.defaultPrivateKeyFile=/path/to/priv-keyname.base64.txt \
  -jar your-client.jar
```

## Keypair file contents

A keypair file is a whitespace-separated dictionary. Lines beginning with `#` are comments.

### Private keypair file (`priv-*.base64.txt`)

A private keypair file contains:

- `user`: the authenticated Deephaven user. The private key proves this identity during login.
- `operateas`: the user that the Deephaven session will act as and use for authorization checks. Requires [`localsuperusers` permissions](#localsuperusers-superuserstxt).
- `public`: the public key in base64-encoded PKCS8/DER format, with `EC:` prefixed before base64 encoding.
- `private`: the private key in base64-encoded PKCS8/DER format, with `EC:` prefixed before base64 encoding.

#### Recommended file permissions

```bash
chmod 600 /path/to/priv-keyname.base64.txt
chown <service-user>:<service-user> /path/to/priv-keyname.base64.txt
```

Example private keypair file:

```text
# Generated on Tue Jan  2 03:04:05 UTC 2024  by  someuser
user myservice
operateas myservice
public RUM6ABC123==
private RUM6ZYX321==
```

If `operateas` differs from `user`, the authenticated Deephaven user must be permitted to operate as the requested effective Deephaven user via the [`localsuperusers`](#localsuperusers-superuserstxt) file.

This file contains a private key; it must be protected with restrictive file permissions and should never leave the machine on which it was created.

### Public key file (`pub-*.base64.txt`)

Example public key file:

```text
myservice RUM6ABC123==
```

This file contains only the `user` name and the public keys; it is safe to distribute.

## `localsuperusers` (`superusers.txt`)

`localsuperusers` is an optional, file-based authorization mechanism that grants **operate-as / impersonation** permissions for [Deephaven users](../../admin-glossary.md#deephaven-user). It controls whether an authenticated Deephaven user may act as another Deephaven user after login. It does not control which OS user executes workers.

### How it interacts with keypair files (`user` and `operateas`)

- `user` is the authenticated Deephaven user proven by the private key.
- `operateas` is the effective Deephaven user whose permissions Deephaven will use for authorization checks.
- If `operateas` differs from `user`, the Authentication Server must be configured to allow that operate-as request or the login will be rejected.

When `localsuperusers` is enabled, operate-as permissions are defined by entries in `superusers.txt`.

### Properties

Enable localsuperusers and configure the file path via Deephaven properties:

```properties
authentication.server.localsuperusers.enabled=true
authentication.server.localsuperusers.file=/etc/sysconfig/deephaven/superusers.txt
```

### File format

Each line defines a user and the set of users they may operate as.

Format:

```text
<username>:<operate_as_user>
```

- Use `*` for `<operate_as_user>` to allow operating as any user.
- Use a comma-separated list to allow operating as specific users.
- One entry per line.

Example:

```text
admin:*
support:testuser,developer1
debugger:developer1
```

### Operational notes

This file is only relevant on machines running an authentication server. Changes take effect after the authentication service is restarted.

### Security guidance

- Limit operate-as permissions to the minimum set of users and target users needed.
- Protect `superusers.txt` with restrictive filesystem permissions.

For additional security guidance, see:

- [Security hardening](../hardening-technical-controls.md)

## ACL store operations

All new Deephaven clusters store authorized public keys in the ACL store ([etcd](../../core-components/etcd.md) or MySQL) by default.

Use of the [deprecated `dsakeys.txt` file](#deprecated-filesystem-based-public-keystore-dsakeystxt) is heavily discouraged.

When using the ACL store, public keys are added and revoked using the [`dhconfig acls publickeys`](../../configuration/dhconfig/acls.md) commands. While you can import the public key from a [public keypair file](#public-key-file-pub-base64txt) or a [private keypair file](#private-keypair-file-priv-base64txt), a private key file should never leave the machine on which it was created.

### Issuing login private keys

1. Generate a keypair ([keypair generation](#generate-public-and-private-keypair-files)).
2. Import the public key to the ACL store ([Add (import)](#add-import)).
3. If you cannot generate the private key on the machine that needs it, distribute the `priv-*.base64.txt` file securely to the client host(s) that need to authenticate.
4. If using `operateas`, configure authorization ([`localsuperusers`](#localsuperusers-superuserstxt))

Use [`dhconfig acls publickeys`](../../configuration/dhconfig/acls.md#publickeys) to manage public keys.

### Add (import)

Import a public key file:

```bash
dhconfig acls publickeys import --file /path/to/pub-username.base64.txt
```

`--file` may be either a public keypair file (`pub-*.base64.txt`) or a private keypair file (`priv-*.base64.txt`).

### List

List public keys:

```bash
dhconfig acls publickeys list
```

List public keys (CSV output, includes full key value):

```bash
dhconfig acls publickeys list --csv
```

List public keys and include key hashes (for use with delete-by-hash):

```bash
dhconfig acls publickeys list --include-hash
```

### Delete

Delete a public key using a keypair file:

```bash
dhconfig acls publickeys delete --file /path/to/pub-username.base64.txt
```

`--file` may be either a public key file (`pub-*.base64.txt`) or a private keypair file (`priv-*.base64.txt`); prefer using the non-sensitive public key.

Delete a public key using a hash from `list --include-hash`:

```bash
dhconfig acls publickeys delete --hash d9b9fbbc
```

## Deprecated filesystem-based public keystore (`dsakeys.txt`)

> [!WARNING]
> `authentication.server.authorizedkeys.file` and `dsakeys.txt` are legacy on-disk public key stores. These are now deprecated and disabled by default. It is preferable to manage public keys in the ACL store, especially if you operate multiple Authentication Servers.

You must explicitly opt in to using the on-disk authorized keys file:

```properties
[service.name=authentication_server] {
  authentication.server.authorizedkeys.enabled=true
  authentication.server.authorizedkeys.file=/etc/sysconfig/illumon.d/resources/dsakeys.txt
}
```

You must also manually keep your `authentication.server.authorizedkeys.file` updated on all Authentication server filesystems, and add, remove and rotate public keys in these files yourself.

## Rotation and revocation

- Rotation:
  - [Generate a new keypair](#generate-public-and-private-keypair-files).
  - [Authorize the new public key on the server](#issuing-login-private-keys).
  - Update clients to use the new keypair file.
  - [Remove the old public key authorization](#delete).

- Revocation:
  - [Remove the public key from the ACL store](#delete).

If you use file-based authorization (for example, `dsakeys.txt`), revoking permissions requires editing your [`authentication.server.authorizedkeys.file`](#deprecated-filesystem-based-public-keystore-dsakeystxt) on all Authentication Server machines, and then those Authentication Servers must be restarted.

## Troubleshooting

- “Authentication failed” or repeated challenge-response failures:
  - Confirm the public key is authorized on the server (`dhconfig acls publickeys list` or your [`authentication.server.authorizedkeys.file`](#deprecated-filesystem-based-public-keystore-dsakeystxt)).
  - Confirm the correct username is being used (the `user` field in the keypair file).
  - If `operateas` differs from `user`, verify that `user` has permission to operate as that user via [`localsuperusers`](#localsuperusers-superuserstxt).
  - Confirm the [client process](#java-client) is actually using the intended key file and has permissions to read the file.

## Related documentation

- [Security hardening](../hardening-technical-controls.md)
- [Security overview](../security-auditing.md)
- [System status](../../troubleshooting/support.md)
- [ACLs](../../permissions/permissions-overview.md)