Connection URLs for Kerberos using JDBC Drivers to connect via SQLLine
You can use client-side connection URL parameters for Kerberos authentication in multiple combinations to authenticate a client with Drill.
Client Credentials
A client can provide its credentials in two ways:
- With a ticket granting ticket (TGT) generated on client side. The TGT must be present on client node; Drill does not generate the TGT.
- With a keytab file and the client principal provided in the user property of the connection URL.
Configuration Options
Connection Parameter (Apache Drill JDBC Driver) | Connection Parameter (Drill JDBC Driver) | Description | Mandatory/Optional | Default Value |
auth | AuthMech | Authentication mechanism. The value is deduced if not specified. Kerberos if principal is provided. Plain if a user and password is provided. A Drill client can also explicitly specify a particular authentication mechanism to use using this parameter. For example, for Kerberos along with service_name, service_host or principal and for the Plain authentication with username and password. | Optional | The preference order is Kerberos and Plain. |
principal | KrbPrincipal | Drillbit service principal. The format of the principal is primary/instance@realm. For Kerberos, the Drill service principal is derived if the value is not provided using this configuration. service_name (primary) and service_host (instance) are used to generate a valid principal. Since the ticket or keytab contains the realm information, the realm is optional. | Optional | |
keytab | KrbKeytab | For Kerberos, if the client chooses to authenticate using a keytab rather than a ticket, set the keytab parameter to the location of the keytab file. The client principal must be provided through the user parameter. A Kerberos ticket is used as the default credential (It is assumed to be present on client-side. The Drill client does not generate the required credentials.) | Optional | |
sasl_encrypt | sasl_encrypt | When set to true, ensures that a client connects to a server with encryption capabilities. For example, Drill 1.11 Drillbits, which support client-to-drillbit encryption. | Optional | FALSE |
service_name | KrbServiceName | Primary name of the Drillbit service principal. | Optional | drill |
service_host | KrbHostFQDN | Instance name of the Drillbit service principal. | Optional | Since this value is usually the hostname of the node where a Drillbit is running, the default value is the Drillbit hostname is provided either through ZooKeeper or through a direct connection string. |
realm | KrbRealm | Kerberos realm name for the Drillbit service principal. The ticket or keytab contains the realm information. | Optional |
Client Encryption
A client can specify that it requires a server with encryption capabilities only by setting the
sasl_encrypt
connection parameter to "true." If the cluster to which
client is connecting has encryption disabled, the client will fail to connect to that
server.drill.exec {
security: {
user.auth.enabled: true,
auth.mechanisms: ["KERBEROS"],
auth.principal: "drill/serverhostname@REALM.COM",
auth.keytab: "/etc/drill/conf/drill.keytab",
user.encryption.sasl.enabled: true
}
}
Connection URL Examples
The following five examples show the JDBC connection URL that the embedded JDBC client uses for Kerberos authentication. The first section, Example of a Simple Connection URL, includes a simple connection string and the second section, Examples of Connection URLs Used with Previously Generated TGTs, includes examples to use with previously generated TGTs.
Example of a Simple Connection URL
Example 1: TGT for Client Credentials
jdbc:drill:drillbit=10.10.10.10;principal=<principal for host 10.10.10.10>
In this example, the Drill client uses the:
- Default
service_name
, which isdrill
. service_host
from the Drillbit name provided in the connection URL, which is10.10.10.10
.
The service principal format is <primary>/<instance>@<realm from
TGT>
. The service principal is principal for host
10.10.10.10
.
Examples of Connection URLs Used with Previously Generated TGTs
If you do not provide a service principal in the connection string when using Kerberos
authentication, then use the service_name
or service_host
parameters. Since these parameters are optional, their default values will be used
internally (if not provided) to create a valid principal.
Example 2: Drillbit Provided by Direct Connection String and Configured with a Unique Service Principal
This type of connection string is used when:
- Each Drillbit in the cluster is configured with its own service principal.
-
The instance component is the host address of the Drillbit.
jdbc:drill:drillbit=host1;auth=kerberos
In this example, the Drill client uses the:
- Default
service_name
, which isdrill
. service_host
, which is the Drillbit name provided in the connection URL (host1
).
The internally created service principal will be drill/host1@<realm from
TGT>
.
Example 3: Drillbit Selected by ZooKeeper and Configured with Unique Service Principal
jdbc:drill:zk=host01.aws.lab:5181;auth=kerberos;service_name=myDrill
In this example, the Drill client uses the:
- Provided
service_name
, which ismyDrill
as the primary name of the principal. service_host
as the address of the Drillbit, which is chosen from the list of active drillbits that ZooKeeper provides (host01.aws.lab:5181
).
The internally created service principal will be myDrill/<host address from
zk>@<realm from TGT>
.
Example 4: Drillbit Selected by Zookeeper and Configured with a Common Service Principal
jdbc:drill:zk=host01.aws.lab:5181;auth=kerberos;service_name=myDrill;service_host=myDrillCluster
In this example, the Drill client uses the:
- Provided
service_name
, which ismyDrill
. service_host
, which ismyDrillCluster
.
The internally created service principal, which will be
myDrill/myDrillCluster@<realm from TGT>
.
Example 5: Keytab for Client Credentials
/etc/krb5.conf
file on the node if it is not provided in the
connection URL. All other parameters can be used as shown in the preceding examples (1-4).
This connection string is for the case when all Drillbits in a cluster use the same
principal.jdbc:drill:zk=host01.aws.lab:5181;auth=kerberos;service_name=myDrill;service_host=myDrillCluster;keytab=<path to keytab file>;user=<client principal>
In this example, the Drill client:
- Will authenticate itself with the:
- Keytab (
path to keytab file
) and - Principal provided in the user parameter (
client principal
)
- Keytab (
- Uses the:
- Provided
service_name
, which ismyDrill
. service_host
, which ismyDrillCluster
.
- Provided
The internally created service principal will be
myDrill/myDrillCluster@<realm from krb5.conf>
.