# Hive Native Authentication

Source: https://userguide.qualytics.io/source-datastore/datastore/native/hive/deep-dive/authentication/

Hive Native authenticates with **Kerberos**, and the **Type** selector in the connection form offers nothing else.

That is deliberate. The metastore protocol has no username and password authentication of its own, so a "basic" option would have collected no credential at all: it would have meant "connect to an unauthenticated metastore" while reading as though authentication had taken place. If you need to connect to Hive as a specific named user, use the [Hive](https://userguide.qualytics.io/source-datastore/datastore/jdbc/hive/) connector, which goes through HiveServer2 and does support user and password.

## Client and metastore identities

**Client Principal** names the identity Qualytics logs in as when the connection has its own **Keytab**, for example `qualytics@EXAMPLE.COM`. The keytab must contain that identity's key. Enter the full principal exactly as it appears in the keytab. A principal of the form `service/_HOST` or `service/_HOST@REALM` is not accepted in this field, because login does not substitute a hostname.

Upload a keytab on every connection. A connection without one can only log in on an older self-hosted deployment that has a Kerberos login of its own; see [Connections without a keytab](https://userguide.qualytics.io/source-datastore/datastore/native/hive/deep-dive/authentication/#connections-without-a-keytab).

**Metastore Service Principal** identifies the service Qualytics connects to, for example `hive/_HOST@EXAMPLE.COM`. Here, `_HOST` is replaced with the metastore's hostname. Leave this field empty to use `hive/_HOST@` followed by the Kerberos login realm. Set it explicitly if your metastore uses a different service name or realm.

> **Note: Existing connections with _HOST**
>
> An older connection with no keytab of its own may still have a service principal such as `hive/_HOST@EXAMPLE.COM` saved as its Client Principal. That saved value is not used for the metastore. With **Metastore Service Principal** empty, Qualytics uses `hive/_HOST@` followed by the realm of the deployment's login principal, so the connection keeps working only when the metastore is in that realm. Saving the connection with a `_HOST` value in **Client Principal** is also rejected. When editing the connection, move the saved value to **Metastore Service Principal** and enter the deployment's login principal as **Client Principal**. If you upload a keytab, enter the identity in that keytab instead.

For example, a client principal of `qualytics@CLIENT.EXAMPLE.COM` can connect to a metastore using `hive/_HOST@SERVER.EXAMPLE.COM` when the Kerberos realms permit it. Enter those values in their respective fields.

The client identity is also the account the cluster checks when Qualytics reads table files. See [Hive Native Permissions](https://userguide.qualytics.io/source-datastore/datastore/native/hive/deep-dive/permissions/) for the access it needs. Qualytics derives the storage service's principal from the metastore principal's realm.

## What each field does

| Field | Required | What it is for |
| --- | --- | --- |
| **Client Principal** | Yes | The login identity in the uploaded keytab, for example `qualytics@EXAMPLE.COM`. Do not use `_HOST`. |
| **Metastore Service Principal** | No | The metastore's service identity. Defaults to `hive/_HOST@` followed by the login realm. Specify it when the service name or realm differs, or the client principal omits its realm. |
| **Keytab** | No | The keytab file for the client principal. Upload it on every connection: when omitted, the connection logs in only if the deployment has a Kerberos login of its own (see [Connections without a keytab](https://userguide.qualytics.io/source-datastore/datastore/native/hive/deep-dive/authentication/#connections-without-a-keytab)). Or click **Type a value instead**  and enter a `${key}` reference to the file held in your secrets manager, stored as its base64 form. See [File fields](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/deep-dive/how-it-works/#file-fields). |
| **krb5.conf** | No | The Kerberos configuration for the cluster's realm, so Qualytics knows how to reach that realm's Key Distribution Center. Upload it with the keytab. When omitted, Qualytics falls back to the deployment's own Kerberos configuration, which only older self-hosted deployments have. Or click **Type a value instead**  and enter a `${key}` reference to the file held in your secrets manager. See [File fields](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/deep-dive/how-it-works/#file-fields). |
| **RPC Protection** | No | The protection level of the connection to the metastore: **Authentication only**, **Integrity (signed)**, or **Privacy (encrypted)**. It must match the metastore's own setting. When left empty, it is **Authentication only**. |
| **hdfs-site.xml** | No | The cluster's HDFS client configuration. Required when table locations use a highly available nameservice. |

> **Warning: Name the keytab file .keytab**
>
> Qualytics reads the uploaded file according to its extension, and a keytab is binary. A keytab saved under any other name is read as text and the upload fails. Rename it to end in `.keytab` before uploading.

## RPC protection

Hadoop clusters secured with Kerberos can require more than authentication on the connection to the metastore. **RPC Protection** sets the level Qualytics uses, and it must match the level the metastore requires:

| Option | What it adds |
| --- | --- |
| **Authentication only** | Kerberos authentication, with no protection of the traffic itself. This is the level used when the field is left empty. |
| **Integrity (signed)** | Each message is signed, so tampering is detected. |
| **Privacy (encrypted)** | Each message is encrypted as well as signed. |

When the levels do not match, the connection fails with a Kerberos error from the metastore rather than a message of its own. See [Troubleshooting](https://userguide.qualytics.io/source-datastore/datastore/native/hive/troubleshooting/#the-connection-fails-with-a-protection-level-error).

## HDFS client configuration

When the metastore records table locations on a highly available HDFS cluster, such as `hdfs://<nameservice>/warehouse/orders`, the nameservice is a logical name rather than a host. Qualytics cannot resolve it without the cluster's HDFS client configuration, so reading table files fails. Upload the cluster's `hdfs-site.xml` in the **hdfs-site.xml** field to supply it. Qualytics applies only its `dfs.*` properties.

## Credentials live on the connection

Each connection carries its own Client Principal, Metastore Service Principal, and keytab. Two consequences are worth knowing:

- **A Kerberized cluster no longer needs deployment-wide Kerberos configuration.** On a self-hosted deployment, connecting to a secured cluster used to mean configuring Kerberos for the deployment as a whole. Uploading a keytab on the connection is now enough, and changing a credential is a change to the connection rather than a redeployment. Current Helm chart versions no longer offer a deployment-wide Kerberos setting at all.
- **Several secured clusters can be connected to one Qualytics deployment**, each with its own identity and its own `krb5.conf`.

> **Note: One realm name, one cluster**
>
> The one arrangement that cannot work is two clusters that use the **same realm name** with different Key Distribution Centers. A realm name cannot mean two clusters at once, so a connection naming a realm another datastore has already claimed is refused rather than quietly reading from the wrong place. Give each cluster a distinct realm name, or connect them from separate deployments.

## Connections without a keytab

The **Keytab** field is optional because some older self-hosted deployments have a Kerberos login of their own, set up in the Helm chart before version 2026.9.1. On those deployments, a connection without a keytab logs in with the deployment's principal and keytab. Deployments installed or upgraded with Helm chart 2026.9.1 or later have no such login, so a connection without a keytab has no credentials to log in with. Its connection test fails with one of two errors, and neither mentions the missing keytab, so check the **Keytab** field first when you see either:

- A Kerberos or SASL error from the metastore.
- A message saying the catalog "is already used by another datastore that reads as a different identity" and asking you to "give the datastores distinct catalog names". Qualytics keeps one catalog per metastore address and **Client Principal**, and two datastores can share it only when they log in the same way. This message appears when another datastore already reads the same metastore with the same **Client Principal** using a keytab, while this connection has no keytab and so no Kerberos identity of its own. The Hive Native form has no catalog name to change; upload the keytab instead.

When a connection does rely on the deployment's login:

- **Client Principal** still requires a value. Enter the deployment's login principal, which your deployment administrator can provide. Qualytics ignores this value for login and does not check it against the deployment identity, so changing it alone does not change who logs in.
- The deployment principal's realm supplies the default **Metastore Service Principal** realm.
- Leaving **krb5.conf** empty uses the deployment's Kerberos configuration.

> **Warning: Upgrading the Helm chart removes the deployment's login**
>
> Helm chart 2026.9.1 and later no longer configure Kerberos for the deployment. Before upgrading a self-hosted deployment to one of those versions, upload a keytab and a `krb5.conf` on every Kerberos connection that has none. Otherwise those connections stop logging in after the upgrade.

## How the credentials are stored

The keytab is a password equivalent, so it is stored encrypted and never displayed back to you. Once saved, the field shows that a file was previously uploaded rather than its contents.

- To change the keytab, upload a new one.
- To keep the stored keytab while editing anything else on the connection, leave the field empty and save.

The `krb5.conf` holds realm names and Key Distribution Center hostnames rather than credentials, so it is not treated as a secret.

> **Warning: Edits apply to every datastore on the connection**
>
> Credentials belong to the connection, not to a single datastore. Changing them through [Manage Connections](https://userguide.qualytics.io/settings/connections/manage-connections/) changes them for every datastore that reuses that connection.

---

## See Also

- **Examples**

  Worked scenarios: a partitioned Parquet warehouse, a database of mixed formats, object storage, and two Kerberized clusters.

  [Examples](https://userguide.qualytics.io/source-datastore/datastore/native/hive/deep-dive/examples/)
- **Best Practices**

  Recommendations for planning the connection, splitting tables between the two Hive connectors, and keeping operations fast.

  [Best Practices](https://userguide.qualytics.io/source-datastore/datastore/native/hive/deep-dive/best-practices/)
- **Permissions**

  The access your Hive cluster must grant, plus the Qualytics user role and team permission needed to manage the datastore.

  [Permissions](https://userguide.qualytics.io/source-datastore/datastore/native/hive/deep-dive/permissions/)
- **How It Works**

  One read from start to finish: the services Qualytics reaches, on which ports, and where your cluster's policies apply.

  [How It Works](https://userguide.qualytics.io/source-datastore/datastore/native/hive/deep-dive/how-it-works/)

> **Tip: Credentials from a secrets manager**
>
> Any field on this page can take its value from HashiCorp Vault or another secrets manager instead of being typed in: enable **Secrets Management** on the connection and write `${key}` in the field. See the [HashiCorp Vault](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/deep-dive/introduction/) pages for setup and troubleshooting.

*Last updated: November 13, 2026.*
