From 43e4a318023410fa1f2bc6cae01a8137ce574a30 Mon Sep 17 00:00:00 2001 From: Wei-Chiu Chuang Date: Wed, 18 Feb 2026 17:54:08 -0800 Subject: [PATCH 1/3] HDDS-14466: Update Kerberos documentation Updated the 'Core Concepts > Security > Kerberos' page with comprehensive content covering Kerberos fundamentals, how Ozone uses Kerberos, and various authentication patterns. Removed the 'What Kerberos does not do' section and the 'Kerberized Environment (Secure)' sub-section for conciseness. Refactored the 'How Ozone uses Kerberos' section for improved flow and standard heading formats, and added relevant configuration page references. --- .../04-security/01-kerberos.md | 33 +++++++++++++++++-- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/docs/03-core-concepts/04-security/01-kerberos.md b/docs/03-core-concepts/04-security/01-kerberos.md index 1c87e740a6..ae6dbb8d06 100644 --- a/docs/03-core-concepts/04-security/01-kerberos.md +++ b/docs/03-core-concepts/04-security/01-kerberos.md @@ -1,9 +1,36 @@ --- +title: Kerberos Authentication sidebar_label: Kerberos --- -# Authentication with Kerberos +# Kerberos Authentication in Apache Ozone -**TODO:** File a subtask under [HDDS-9857](https://issues.apache.org/jira/browse/HDDS-9857) and complete this page or section. +This document explains the fundamentals of Kerberos authentication and its application within Apache Ozone to secure communication between clients and services, as well as between Ozone services internally. -## Using SPNEGO to Authenticate with Kerberos over HTTP +## What is Kerberos Authentication Protocol? + +Kerberos is a network authentication protocol that works on the basis of tickets to allow nodes communicating over a non-secure network to prove their identity to one another in a secure manner. It uses strong cryptography so that a client can prove its identity to a server (and vice-versa) across an insecure network connection. + +Key components of Kerberos include: +* **Clients:** Users or services requesting access. +* **Servers:** Services providing resources. +* **Key Distribution Center (KDC):** A trusted third party responsible for issuing tickets and managing user credentials. The KDC typically consists of an Authentication Server (AS) and a Ticket-Granting Server (TGS). +* **Principals:** Unique identities (users or services) within the Kerberos realm. + + + +## How Ozone uses Kerberos + +In a secure, Kerberized Ozone cluster, all communication is authenticated to prevent unauthorized access and ensure integrity. Ozone leverages Kerberos for two primary authentication patterns: + +### Client-to-Service Authentication + +Clients (e.g., `ozone sh`, Spark jobs) authenticate with Ozone services (e.g., Ozone Manager, SCM) by acquiring a Kerberos ticket-granting ticket (TGT) from the KDC. This TGT is then used to obtain service tickets for various Ozone services, proving the client's identity to each service. + +### Service-to-Service Authentication + +Ozone's internal services (e.g., Ozone Manager to SCM, SCM to Datanodes, Datanodes to other Datanodes for replication) also authenticate with each other using Kerberos. Each service runs as a distinct Kerberos principal, and they use service tickets to establish trusted communication channels. For details on configuring Kerberos for Ozone services, refer to the [Configuring Kerberos page](/docs/administrator-guide/configuration/security/kerberos). + +### Kerberos over HTTP using SPNEGO + +For web-based interfaces and REST APIs (e.g., Recon UI, S3 Gateway), Kerberos authentication is often performed using SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism). SPNEGO allows web clients (like browsers) to use their existing Kerberos credentials to authenticate with web servers without requiring explicit username/password input. For configuration details, see [Configuring HTTP authentication using Kerberos SPNEGO](/docs/administrator-guide/configuration/security/https). From 3c17ec36ecb2bb925e971923b2f2c953ed9954db Mon Sep 17 00:00:00 2001 From: Wei-Chiu Chuang Date: Wed, 18 Feb 2026 18:11:23 -0800 Subject: [PATCH 2/3] Fix spelling and markdownlint --- cspell.yaml | 2 ++ docs/03-core-concepts/04-security/01-kerberos.md | 11 +++++------ 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/cspell.yaml b/cspell.yaml index be4511df0f..85e5af7b84 100644 --- a/cspell.yaml +++ b/cspell.yaml @@ -137,6 +137,7 @@ words: - hsync - SASL - GSS +- GSSAPI - jira - jiras - LLAP @@ -153,6 +154,7 @@ words: - libhdfs - awscli - TGT +- TGS - Kerberized - assignadmin - revokeadmin diff --git a/docs/03-core-concepts/04-security/01-kerberos.md b/docs/03-core-concepts/04-security/01-kerberos.md index ae6dbb8d06..1cf638090e 100644 --- a/docs/03-core-concepts/04-security/01-kerberos.md +++ b/docs/03-core-concepts/04-security/01-kerberos.md @@ -3,7 +3,7 @@ title: Kerberos Authentication sidebar_label: Kerberos --- -# Kerberos Authentication in Apache Ozone +## Kerberos Authentication in Apache Ozone This document explains the fundamentals of Kerberos authentication and its application within Apache Ozone to secure communication between clients and services, as well as between Ozone services internally. @@ -12,12 +12,11 @@ This document explains the fundamentals of Kerberos authentication and its appli Kerberos is a network authentication protocol that works on the basis of tickets to allow nodes communicating over a non-secure network to prove their identity to one another in a secure manner. It uses strong cryptography so that a client can prove its identity to a server (and vice-versa) across an insecure network connection. Key components of Kerberos include: -* **Clients:** Users or services requesting access. -* **Servers:** Services providing resources. -* **Key Distribution Center (KDC):** A trusted third party responsible for issuing tickets and managing user credentials. The KDC typically consists of an Authentication Server (AS) and a Ticket-Granting Server (TGS). -* **Principals:** Unique identities (users or services) within the Kerberos realm. - +- **Clients:** Users or services requesting access. +- **Servers:** Services providing resources. +- **Key Distribution Center (KDC):** A trusted third party responsible for issuing tickets and managing user credentials. The KDC typically consists of an Authentication Server (AS) and a Ticket-Granting Server (TGS). +- **Principals:** Unique identities (users or services) within the Kerberos realm. ## How Ozone uses Kerberos From c3044ee88b740bb6c525b4a69b10e00828b74050 Mon Sep 17 00:00:00 2001 From: Wei-Chiu Chuang Date: Wed, 18 Feb 2026 21:46:10 -0800 Subject: [PATCH 3/3] Fix site build --- docs/03-core-concepts/04-security/01-kerberos.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/03-core-concepts/04-security/01-kerberos.md b/docs/03-core-concepts/04-security/01-kerberos.md index 1cf638090e..bbd71fd4a0 100644 --- a/docs/03-core-concepts/04-security/01-kerberos.md +++ b/docs/03-core-concepts/04-security/01-kerberos.md @@ -28,8 +28,8 @@ Clients (e.g., `ozone sh`, Spark jobs) authenticate with Ozone services (e.g., O ### Service-to-Service Authentication -Ozone's internal services (e.g., Ozone Manager to SCM, SCM to Datanodes, Datanodes to other Datanodes for replication) also authenticate with each other using Kerberos. Each service runs as a distinct Kerberos principal, and they use service tickets to establish trusted communication channels. For details on configuring Kerberos for Ozone services, refer to the [Configuring Kerberos page](/docs/administrator-guide/configuration/security/kerberos). +Ozone's internal services (e.g., Ozone Manager to SCM, SCM to Datanodes, Datanodes to other Datanodes for replication) also authenticate with each other using Kerberos. Each service runs as a distinct Kerberos principal, and they use service tickets to establish trusted communication channels. For details on configuring Kerberos for Ozone services, refer to the [Configuring Kerberos page](../../../administrator-guide/configuration/security/kerberos). ### Kerberos over HTTP using SPNEGO -For web-based interfaces and REST APIs (e.g., Recon UI, S3 Gateway), Kerberos authentication is often performed using SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism). SPNEGO allows web clients (like browsers) to use their existing Kerberos credentials to authenticate with web servers without requiring explicit username/password input. For configuration details, see [Configuring HTTP authentication using Kerberos SPNEGO](/docs/administrator-guide/configuration/security/https). +For web-based interfaces and REST APIs (e.g., Recon UI, S3 Gateway), Kerberos authentication is often performed using SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism). SPNEGO allows web clients (like browsers) to use their existing Kerberos credentials to authenticate with web servers without requiring explicit username/password input. For configuration details, see [Configuring HTTP authentication using Kerberos SPNEGO](../../../administrator-guide/configuration/security/https).