Host-Based Authentication (HBA)¶
This section explains how to configure CrateDB client connection and authentication.
Note
The stock crate.yml shipped with CrateDB explicitly enables host based
authentication and defines a set of basic authentication rules.
If you do not want to use authentication, set auth.host_based.enabled
to false. If authentication is disabled, user management remains active and you must specify the
user crate (with an empty password) when connecting via the PostgreSQL
protocol. HTTP clients do not have to specify a user because they use the
auth.trust.http_default_user if no
user is provided.
Non-runtime cluster-wide settings must be configured the same on every node.
Table of contents
Authentication against CrateDB¶
Client access and authentication is configured via the
auth.host_based.config setting in the crate.yml file.
The general format of the auth.host_based.config setting is a map of remote
client access entries, where the key of the map defines the order in which the
entries are used, which permit authentication to CrateDB. Each entry may
contain no, one, or multiple fields. Allowed fields are user, ip or
cidr, method, protocol and ssl. The description of these
fields can be found in Trust authentication.
When a client sends an authentication request, CrateDB matches the provided username, IP address, protocol and connection scheme against these entries to determine which authentication method is required. If no entry matches, the client authentication request will be denied.
To support proxied clients to authenticate, the X-REAL-IP request header
can be used. For security reasons, this is disabled by default as it allows
clients to impersonate other clients. To enable this feature,
set auth.trust.http_support_x_real_ip to true. If enabled, the
X-REAL-IP request header has priority over the actual client IP address.
If auth.host_based is not set, the host based authentication is disabled.
In this case CrateDB trusts all connections and accepts the user provided by
the client given that this user exists.
If the setting auth.host_based is present and the configurations list does
not contain any entry, then no client can authenticate.
For example, a host based configuration can look like this:
auth:
host_based:
enabled: true
config:
0:
user: mike
address: 32.0.0.0/8
method: trust
protocol: pg
a:
user: barb
address: 172.16.0.0
protocol: pg
ssl: on
b:
user: crate
address: 32.0.0.0/8
method: trust
y:
user: eleven
protocol: pg
e:
user: dustin
address: 172.16.0.0
method: trust
protocol: http
f:
user: trinity
protocol: http
address: 127.0.0.1
ssl: off
g:
user: john
method: jwt
protocol: http
z:
method: password
Note
In the auth.host_based.config setting, the order of the entries is
defined by the natural order of the group keys of the setting. The
authentication method of the first entry that matches the client user,
address, protocol and connection properties will be used. If the
authentication attempt fails, subsequent entries will not be considered.
The entry look-up order is determined by the order identifier of each
entry.
In the example above:
{user: mike, address: 32.0.0.0/8, method: trust, protocol: pg} means that
the user mike can authenticate to CrateDB over the PostgreSQL Wire Protocol
from any IP address ranging from 32.0.0.0 to 32.255.255.255, using the
trust authentication method.
{user: crate, address: 32.0.0.0/8, method: trust} means that the superuser
crate can authenticate to CrateDB over the protocols for which
authentication is supported from any IP address in the range of 32.0.0.0 to
32.255.255.255, using the trust authentication method.
{user: barb, address: 172.16.0.0, protocol: pg, ssl: on} means that the
user barb can authenticate to CrateDB over the PostgreSQL Wire Protocol
from the 172.16.0.0 IP Address only if the connection is done over SSL/TLS.
Since no authentication method is specified, the trust method will be used
by default.
The entry: {user: eleven, protocol: pg} means that the user eleven can
authenticate to CrateDB over the PostgreSQL Wire Protocol from any IP address,
using the trust method.
{user: dustin, address: 172.16.0.0, protocol: http, method: trust} means
that the user dustin can authenticate to CrateDB over HTTP protocol from
the 172.16.0.0 IP Address using the trust method.
{user: trinity, address: 127.0.0.1, protocol: http, ssl: off} means that
the user trinity can authenticate to CrateDB over HTTP from the
127.0.0.1 IP Address only if no SSL/TLS connection is used. Since no
authentication method is specified, the trust method will be used by
default.
{user: john, method: jwt, protocol: http} means
that the user john can authenticate to CrateDB over HTTP protocol using the
JWT method.
And finally the entry {method: password} means that any existing user (or
superuser) can authenticate to CrateDB from any IP address using the
password method for both HTTP and PostgreSQL wire protocol.
Note
For general help managing users and roles, see Users and roles management.
Note
User in the HBA entry for method: jwt must match the user created by
CREATE USER statement. CREATE USER is case insensitive when
name is provided without quotes, see Key words and identifiers.
Thus, if HBA entry has username with uppercase symbols, use CREATE USER
with quotes.
Authenticating as a superuser¶
When CrateDB is started, the cluster contains one predefined superuser. This
user is called crate.
To enable trust authentication for the superuser, crate must be specified in
the auth.host_based setting, like this:
auth:
host_based:
enabled: true
config:
0:
user: crate
Authenticating to Admin UI¶
When trying to access the CrateDB Admin UI, authentication with the user
defined with the auth.trust.http_default_user setting (defaults to crate) will be
attempted initially. If this authentication attempt fails, the browser will
open the standard popup window where the user is asked to fill in credentials.
Depending on the HBA configuration, it may be necessary to a username and
password, or, alternatively, a username only.
Users that log in to the Admin UI must be granted DQL` privileges at the
CLUSTER level in order to be able to access the various monitoring
sections. For example:
cr> GRANT DQL TO admin;
GRANT OK, 1 row affected (... sec)
For more information, consult the privileges section.
Node-to-node communication¶
You can use the Host-Based Authentication mechanism for node-to-node communication.
For example, if you wanted to configure a multi-zone cluster, you should enable certificate authentication like this:
auth:
host_based:
enabled: true
config:
0:
protocol: transport
ssl: on
method: cert