deephaven_enterprise.client.auth¶

This module provides the AuthClient class for authenticating to a Deephaven authentication server and producing tokens for use with other Deephaven services.

class AuthClient(host=None, port=None, rpc_timeout_seconds=120, channel=None, channel_options=None, client_name=None)[source]¶

Bases: object

AuthClient authenticates to a Deephaven authentication server and produces tokens for use with other Deephaven services.

Presently, password and private key authentication are provided.

Creates an AuthClient and connect to the server.

You may either specify the host and port to connect to, or provide your own grpc channel. The simplest case is to simply provide the host and port, but if you need advanced channel configuration or want to share the channel for several clients, then you can create it and pass it in.

Parameters:

host (str) – the host to connect to, if not None, requires port to be provided， defaults to None
port (int) – the port to connect to, if not None, requires host to be provided, defaults to None
rpc_timeout_seconds (int) – the rpc timeout period to use, defaults to 120 seconds if not provided
channel (grpc.Channel) – a pre-created channel to use for the gRPC messages, it will not be closed by this client, defaults to None
channel_options (Optional[Any]) – a list of options for channel creation (not used if the channel is provided)
client_name (str) – a name for this client to append to the client identifier, useful for debugging and logging, defaults to None

close()[source]¶

Logs out from the authentication server. No further tokens may be requested by this client.

Return type:: None

external_login(auth_key)[source]¶

Authenticates to the server using an external authentication method, such as SAML or a custom, non-standard external authentication module.

This requires that the server be configured with the external authentication module and that the external authentication module should be configured to accept the provided auth_key.

Parameters:: auth_key (Union[str, bytes]) – the key to authenticate with, which may be a string or bytes. If it is a string, it should be the key that the external authentication module expects. If it is bytes, it will be decoded to a string using UTF-8 before sending.
Raises:: AuthenticationFailedException – if the server responds with a failure
Return type:: None

static generate_keypair(user)[source]¶

Generates a new keypair in the Deephaven proprietary format.

The private key can be stored as a file and used to authenticate using the private_key() method. The public key contains a username followed by the public key. The public key should be uploaded to the Deephaven ACL write server.

Parameters:: user (str) – the username to write into the key
Return type:: tuple[str, str]
Returns:: a tuple containing the private key text and the public key text in the Deephaven proprietary format

get_token(service, timeout=None)[source]¶

Gets an authentication token to present to another Deephaven service. This token may only be used one time, as it is consumed by the authentication server during the verification process.

Parameters:

service (str) – the service that will verify the token (e.g., “PersistentQueryController”)
timeout (float) – how long to wait for the gRPC call to complete, defaults to None, meaning to use the value of rpc_timeout_secs of this client

Returns:

the token

Return type:

auth_pb2.Token

Raises:

grpc.RpcError – if the gRPC call fails or timed out

password(user, password, effective_user=None)[source]¶

Authenticates to the server using a username and password.

Parameters:

user (str) – the user to authenticate
password (str) – the user’s password
effective_user (str) – the user to operate as, defaults to None, meaning the same as the user to authenticate

Raises:

AuthenticationFailedException –

Return type:

None

ping()[source]¶

Pings the server, refreshing our cookie.

Return type:: bool
Returns:: True if a ping was sent, False if there is no active cookie on this client.
Raises:: grpc.RpcError – if the gRPC call fails or timed out

private_key(file)[source]¶

Authenticates to the server using a private key in the Deephaven proprietary format.

https://deephaven.io/enterprise/docs/sys-admin/configuration/public-and-private-keys/#how-to-create-deephaven-authentication-keys

Parameters:: file (Union[str, io.StringIO]) – a string file name containing the private key produced by generate_keypair(), or alternatively an io.StringIO instance (which may be closed after it is read)
Raises:: AuthenticationFailedException, ValueError –
Return type:: None

saml(login_uri)[source]¶

Authenticate using SAML, which must be configured on the server.

Parameters:: login_uri (str) – the URI for the Deephaven SAML plugin. Often “https://deephaven-auth-server:9032/dh-saml/”, but is dependent on configuration.
Raises:: AuthenticationFailedException –
Return type:: None

upload_key(pubtext, url, delete=False)[source]¶

Uploads a public key to the ACL write server.

The public key should be in the Deephaven proprietary format, which is a single line containing the username followed by the base64 encoded public key.

Parameters:

pubtext (str) – the public key text in the Deephaven proprietary format
url (str) – the URL of the ACL write server (e.g., https://foo.bar.company.com:9044/acl/)
delete (bool) – True to delete the key instead of adding it, defaults to False

Raises:

ValueError – if the public key text is not in the correct format
RuntimeError – if the server responds with an unexpected status code

exception AuthenticationFailedException[source]¶

Bases: Exception

This exception is raised when the server responds to our authentication request with a failure (e.g. bad password or bad key). Other errors, like the server not responding at all are not covered by this Exception.