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.

At a high level:

• A client generates public and private keypair files.
• An administrator authorizes the public key to log in as a particular Deephaven User.
• The client uses the private key to authenticate by signing a nonce from the Authentication Server 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 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) permits that authenticated user to operate as the requested effective user.

This is different from run-as / per-user workers:

• operateas changes the Deephaven user identity used for authorization.
• run-as changes which OS service account executes workers.

Generate public and private "keypair files"

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

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)

Java client

Java clients will use a private keypair file to authenticate if the system property AuthenticationClientManager.defaultPrivateKeyFile is set to a path.

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.
• 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

Example private keypair file:

If operateas differs from user, the authenticated Deephaven user must be permitted to operate as the requested effective Deephaven user via the localsuperusers 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:

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. 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:

File format

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

Format:

• 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:

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

ACL store operations

All new Deephaven clusters store authorized public keys in the Etcd datastore by default.

Use of the deprecated dsakeys.txt file is heavily discouraged.

When using the ACL store, public keys are added and revoked using the dhconfig acls publickeys commands. While you can import the public key from a public keypair file or a private keypair file, a private key file should never leave the machine on which it was created.

Issuing login private keys

1. Generate a keypair (keypair generation).
2. Import the public key to the ACL store (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)

Use dhconfig acls publickeys to manage public keys.

Add (import)

Import a public key file:

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

List

List public keys:

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

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

Delete

Delete a public key using a keypair file:

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

Deprecated filesystem-based public keystore (dsakeys.txt)

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

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.
  • Authorize the new public key on the server.
  • Update clients to use the new keypair file.
  • Remove the old public key authorization.

• Revocation:

  • Remove the public key from the ACL store.

If you use file-based authorization (for example, dsakeys.txt), revoking permissions requires editing your authentication.server.authorizedkeys.file 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).
  • 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.
  • Confirm the client process is actually using the intended key file and has permissions to read the file.

Related documentation

• Security hardening
• Security overview
• System status
• ACLs