(ozone-site) branch master updated: HDDS-16945. Document HTTP SPNEGO _HOST resolution for operators (#569)

[we...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

jojochuang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ozone-site.git


The following commit(s) were added to refs/heads/master by this push:
     new 927be2e141 HDDS-16945. Document HTTP SPNEGO _HOST resolution for operators (#569)
927be2e141 is described below

commit 927be2e1411e06dd49ef880daa5d025056b2d00d
Author: Wei-Chiu Chuang <we...@apache.org>
AuthorDate: Mon Oct 19 13:51:37 2026 -0700

    HDDS-16945. Document HTTP SPNEGO _HOST resolution for operators (#569)
    
    Generated-by: Cursor <cu...@cursor.com>
---
 cspell.yaml                                        |  1 +
 .../02-configuration/03-security/03-https.md       | 36 ++++++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/cspell.yaml b/cspell.yaml
index 5a2013e2ec..582b6ed6a5 100644
--- a/cspell.yaml
+++ b/cspell.yaml
@@ -171,6 +171,7 @@ words:
 - spnego
 - keytab
 - Keytab
+- NIC
 - keyspace
 - Merkle
 - RocksDB
diff --git a/docs/05-administrator-guide/02-configuration/03-security/03-https.md b/docs/05-administrator-guide/02-configuration/03-security/03-https.md
index 06c82d408a..548dbe3b20 100644
--- a/docs/05-administrator-guide/02-configuration/03-security/03-https.md
+++ b/docs/05-administrator-guide/02-configuration/03-security/03-https.md
@@ -31,6 +31,42 @@ However, they can be configured to require Kerberos authentication using HTTP SP
 
 After that, individual component needs to configure properly to completely enable SPNEGO or SIMPLE authentication.
 
+## Resolving `_HOST` in the Kerberos principal
+
+`HTTP/_HOST@REALM` in `*.http.auth.kerberos.principal` is expanded at startup. The
+hostname must match your **keytab** and the **host in the browser URL**.
+
+Ozone takes `_HOST` from the **advertised** web address (`ozone.<service>.http-address`
+or `https-address`), **not** from `*-http-bind-host`. Bind host only chooses where
+the process listens (`0.0.0.0`, `::`, a NIC IP, and so on).
+
+For Datanode, the address keys are `hdds.datanode.http-address` and
+`hdds.datanode.https-address`.
+
+| Property (OM example) | Example | Used for `_HOST` |
+|-----------------------|---------|------------------|
+| `ozone.om.http-address` | `om1.example.com:9874` | Yes |
+| `ozone.om.http-bind-host` | `0.0.0.0` or `::` | No |
+
+Ozone checks enabled schemes, HTTP before HTTPS, and uses the first configured
+hostname that is not an IP literal for all listeners. With `HTTP_AND_HTTPS`, different
+HTTP and HTTPS hostnames still produce one principal: the HTTP name wins when both are
+non-literal hostnames. With `HTTPS_ONLY`, the HTTP address is ignored.
+
+If no enabled `*-address` supplies a hostname (the settings are unset or
+contain IP literals, including `0.0.0.0`, `[::]`, and concrete IP addresses),
+Ozone uses this machine's **canonical hostname**.
+
+**Recommended:** set `*-address` to the FQDN in the keytab; keep `*-bind-host` on
+`0.0.0.0` or `::` if needed; open the UI with that FQDN. For **IPv6 bind `::`**, still
+set a non-wildcard FQDN in `*-address`. S3 web admin (and Kerberos `/secret/*` when
+enabled) follows `ozone.s3g.webadmin.http-address` / `https-address` the same way.
+
+**SPNEGO fails:** check `klist -k -t <keytab>` against `*-address` and the browser URL
+(FQDN, short name, and IP are not interchangeable).
+
+See [HDDS-16347](https://issues.apache.org/jira/browse/HDDS-16347) for the code change.
+
 ## Enable SPNEGO authentication for OM HTTP
 
 | Property | Value |


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@ozone.apache.org
For additional commands, e-mail: commits-help@ozone.apache.org