Authentication Methods

There are multiple ways to authenticate against CrateDB.


Authentication methods are an enterprise feature.


CrateDB will never leak information about user existence in the case of failed authentication. If you’re receiving an error trying to authenticate, first make sure that the user exists.

Table of Contents

Trust Method

When the trust authentication method is used, the server just takes the username provided by the client as is without further validation. This is useful for any setup where access is controlled by other means, like network restrictions as implemented by Host Based Authentication (HBA).

Trust Authentication Over Postgres Protocol

The Postgres Protocol requires a user for every connection which is sent by all client implementations.

Trust Authentication Over HTTP

The HTTP implementation takes the value of the X-USER request header as the username.

Since a user is always required for trust authentication, it is possible to specify a default user in case that the X-USER header is not set. This is useful to allow clients which do not provide the possibility to set any headers, for example a web browser connecting to the Admin UI.

The default user can be specified via the setting like this:

    http_default_user: dustin


When the Enterprise Edition, and the User Management are enabled, the user of the Admin UI needs to be granted the following privileges: DQL on sys.shards, sys.nodes, sys.node_checks, sys.checks, sys.cluster, and sys.jobs_log tables. As well as DQL on the doc schema.

These DQL privileges are required by the Admin UI to display the cluster health, monitoring, and checks, to list the available nodes in the cluster and to list the tables.

Client Certificate Authentication Method

When the cert authentication method is used, the client has to connect to CrateDB using SSL with a valid client certificate.

If connecting via HTTP where the username is optional, the common name will be used as username. In case a username is already provided, it has to match the common name of the certificate. Otherwise the authentication will fail. See Trust Method on how to provide a username via HTTP.

The rule that the common name must match the provided username always applies to the postgres wire protocol, as there the username isn’t optional.

Please consult the relevant client documentations for instructions on how to connect using SSL with client certificate.