Kerberos Authentication

Overview

Kerberos is a network authentication protocol designed for secure authentication in enterprise environments. Edge Delta supports Kerberos authentication (via GSSAPI/SASL) for connecting to Kerberos-protected services such as Apache Kafka clusters in enterprise deployments.

Kerberos authentication support requires Edge Delta agent version v2.8.0 or higher.

How Kerberos Authentication Works

Kerberos uses a ticket-based authentication system with three main components:

1. Key Distribution Center (KDC): The trusted third party that issues authentication tickets
2. Service Principal: The identity of the service being accessed (e.g., Kafka broker)
3. Client Principal: The identity of the client (Edge Delta agent) requesting access

When Edge Delta connects to a Kerberos-protected service:

1. The agent uses its keytab file to authenticate with the KDC
2. The KDC issues a Ticket Granting Ticket (TGT)
3. The agent requests a service ticket for the target service
4. The service ticket is used to establish a secure connection

Prerequisites

Before configuring Kerberos authentication, ensure you have:

1. Kerberos Infrastructure: A working Kerberos realm with a KDC
2. Service Principal: A principal created for the Edge Delta agent (e.g., edgedelta-agent@EXAMPLE.COM)
3. Keytab File: A keytab file containing the agent’s credentials, accessible by the Edge Delta agent
4. krb5.conf: Kerberos configuration file (optional if using system default)

Creating a Keytab File

Work with your Kerberos administrator to create a keytab for Edge Delta. Example using kadmin:

# In kadmin
addprinc -randkey edgedelta-agent@EXAMPLE.COM
ktadd -k /etc/security/keytabs/edgedelta.keytab edgedelta-agent@EXAMPLE.COM

Ensure the keytab file has appropriate permissions:

chmod 400 /etc/security/keytabs/edgedelta.keytab
chown edgedelta:edgedelta /etc/security/keytabs/edgedelta.keytab

Kerberos Configuration File (krb5.conf)

The krb5.conf file defines Kerberos realms and KDC locations. A typical configuration:

[libdefaults]
    default_realm = EXAMPLE.COM
    dns_lookup_realm = false
    dns_lookup_kdc = false
    ticket_lifetime = 24h
    renew_lifetime = 7d
    forwardable = true

[realms]
    EXAMPLE.COM = {
        kdc = kdc.example.com
        admin_server = kdc.example.com
    }

[domain_realm]
    .example.com = EXAMPLE.COM
    example.com = EXAMPLE.COM

Configuring Kerberos in Edge Delta

Edge Delta supports Kerberos authentication for the following nodes:

• Kafka Source - Consume messages from Kerberos-protected Kafka clusters
• Apache Kudu Destination - Write data to Kerberos-protected Kudu clusters

Kafka Source with Kerberos

To configure the Kafka source with Kerberos authentication:

nodes:
  - name: kafka_kerberos_input
    type: kafka_input
    endpoint: "kafka-broker1.example.com:9093,kafka-broker2.example.com:9093"
    topic: "secure-logs"
    group_id: "edgedelta-consumer"
    sasl:
      mechanism: "gssapi"
      kerberos_config:
        principal: "edgedelta-agent@EXAMPLE.COM"
        keytab: "/etc/security/keytabs/edgedelta.keytab"
        realm: "EXAMPLE.COM"
        krb5_conf_path: "/etc/krb5.conf"

Configuration Parameters

Apache Kudu Destination with Kerberos

To configure the Apache Kudu destination with Kerberos authentication:

nodes:
  - name: kudu_kerberos_output
    type: apache_kudu_output
    hosts:
      - kudu-master1.example.com:7051
      - kudu-master2.example.com:7051
    table_name: secure_logs
    kudu_security:
      auth_type: kerberos
      kerberos:
        principal: edgedelta-agent@EXAMPLE.COM
        keytab: /etc/security/keytabs/edgedelta.keytab
        realm: EXAMPLE.COM
        sasl_protocol_name: kudu
        krb5_conf_path: /etc/krb5.conf
      tls:
        ca_file: /etc/ssl/certs/kudu-ca.crt
    schema_mappings:
      - column_name: id
        column_type: string
        expression: attributes["id"]
        is_key: true

Apache Kudu Configuration Parameters

Kubernetes Deployment

When deploying Edge Delta with Kerberos in Kubernetes, you need to make the keytab and krb5.conf files available to the agent pods.

Using Kubernetes Secrets

1. Create a secret containing the keytab:

kubectl create secret generic edgedelta-kerberos \
  --from-file=edgedelta.keytab=/path/to/edgedelta.keytab \
  -n edgedelta

2. Create a ConfigMap for krb5.conf:

kubectl create configmap krb5-config \
  --from-file=krb5.conf=/path/to/krb5.conf \
  -n edgedelta

3. Configure Helm values to mount the secret and ConfigMap:

# values.yaml
agent:
  extraVolumes:
    - name: kerberos-keytab
      secret:
        secretName: edgedelta-kerberos
        defaultMode: 0400
    - name: krb5-config
      configMap:
        name: krb5-config

  extraVolumeMounts:
    - name: kerberos-keytab
      mountPath: /etc/security/keytabs
      readOnly: true
    - name: krb5-config
      mountPath: /etc/krb5.conf
      subPath: krb5.conf
      readOnly: true

4. Deploy with Helm:

helm upgrade edgedelta edgedelta/edgedelta -i \
  --set secretApiKey.value=<YOUR_API_KEY> \
  -n edgedelta --create-namespace \
  -f values.yaml

Linux Deployment

For Linux-based deployments, ensure the keytab and krb5.conf files are accessible:

1. Place the keytab file in a secure location:

sudo mkdir -p /etc/security/keytabs
sudo cp edgedelta.keytab /etc/security/keytabs/
sudo chmod 400 /etc/security/keytabs/edgedelta.keytab
sudo chown edgedelta:edgedelta /etc/security/keytabs/edgedelta.keytab

2. Configure krb5.conf (typically at /etc/krb5.conf):

sudo cp krb5.conf /etc/krb5.conf
sudo chmod 644 /etc/krb5.conf

3. Restart the Edge Delta agent:

sudo systemctl restart edgedelta

Troubleshooting

Common Issues

Clock Skew Error

Kerberos requires synchronized clocks between clients and KDC (typically within 5 minutes). Ensure NTP is configured:

# Check time synchronization
timedatectl status

# Install and enable NTP if needed
sudo apt install ntp
sudo systemctl enable ntp
sudo systemctl start ntp

Keytab Permission Denied

Ensure the Edge Delta agent has read access to the keytab file:

# Check keytab permissions
ls -la /etc/security/keytabs/edgedelta.keytab

# Verify keytab contents
klist -kt /etc/security/keytabs/edgedelta.keytab

Principal Not Found

Verify the principal exists in the KDC:

# Test authentication with kinit
kinit -kt /etc/security/keytabs/edgedelta.keytab edgedelta-agent@EXAMPLE.COM
klist

KDC Unreachable

Verify network connectivity to the KDC and check krb5.conf settings:

# Test KDC connectivity
nc -zv kdc.example.com 88

# Verify krb5.conf realm configuration
cat /etc/krb5.conf

Debug Logging

Enable Kerberos debug logging by setting the KRB5_TRACE environment variable:

# In Helm values.yaml
agent:
  env:
    - name: KRB5_TRACE
      value: "/dev/stderr"

Security Best Practices

1. Protect Keytab Files: Keytab files contain credentials and should be treated as sensitive. Use restrictive file permissions (0400) and limit access.

2. Use Dedicated Principals: Create dedicated Kerberos principals for Edge Delta rather than sharing principals with other services.

3. Rotate Keytabs Regularly: Work with your Kerberos administrators to establish a keytab rotation schedule.

4. Monitor Authentication Failures: Monitor Edge Delta logs for authentication failures that may indicate security issues.

5. Network Security: Ensure network paths between Edge Delta agents and KDCs are secure.

See Also

• Kafka Source - Configure Kafka input with Kerberos
• Apache Kudu Destination - Configure Kudu output with Kerberos
• Environment Variables - Configure agent environment
• Helm Values - Kubernetes deployment configuration