This is an automated email from the ASF dual-hosted git repository. quantranhong1999 pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/james-project.git
commit a4e1e4fffaba86e6b6e4e6d74518dae458bfca9d Author: Quan Tran <[email protected]> AuthorDate: Fri Jul 24 16:49:13 2026 +0700 JAMES-4215 Document Kerberos GSSAPI authentication Document installation and configuration of the optional Kerberos extension for IMAP and SMTP. Describe service principals, keytabs, identity mapping, TLS policy, supported QOP, extension loading, and SMTP token line limits. --- docs/modules/servers/nav.adoc | 2 + .../pages/distributed/configure/kerberos.adoc | 5 ++ .../servers/pages/postgres/configure/kerberos.adoc | 5 ++ .../partials/configure/forExtensionsPartial.adoc | 3 +- docs/modules/servers/partials/configure/imap.adoc | 17 +++- .../servers/partials/configure/kerberos.adoc | 94 ++++++++++++++++++++++ docs/modules/servers/partials/configure/smtp.adoc | 18 ++++- 7 files changed, 137 insertions(+), 7 deletions(-) diff --git a/docs/modules/servers/nav.adoc b/docs/modules/servers/nav.adoc index 96d5345173..3acbcca2ad 100644 --- a/docs/modules/servers/nav.adoc +++ b/docs/modules/servers/nav.adoc @@ -29,6 +29,7 @@ **** Protocols ***** xref:distributed/configure/server.adoc[Common Server Configuration] ***** xref:distributed/configure/oidc.adoc[OIDC Configuration] +***** xref:distributed/configure/kerberos.adoc[Kerberos GSSAPI Configuration] ***** xref:distributed/configure/imap.adoc[imapserver.xml] ***** xref:distributed/configure/jmap.adoc[jmap.properties] ***** xref:distributed/configure/jmx.adoc[jmx.properties] @@ -101,6 +102,7 @@ **** Protocols ***** xref:postgres/configure/server.adoc[Common Server Configuration] ***** xref:postgres/configure/oidc.adoc[OIDC Configuration] +***** xref:postgres/configure/kerberos.adoc[Kerberos GSSAPI Configuration] ***** xref:postgres/configure/imap.adoc[imapserver.xml] ***** xref:postgres/configure/jmap.adoc[jmap.properties] ***** xref:postgres/configure/jmx.adoc[jmx.properties] diff --git a/docs/modules/servers/pages/distributed/configure/kerberos.adoc b/docs/modules/servers/pages/distributed/configure/kerberos.adoc new file mode 100644 index 0000000000..fb96a25922 --- /dev/null +++ b/docs/modules/servers/pages/distributed/configure/kerberos.adoc @@ -0,0 +1,5 @@ += Distributed James Server — Kerberos GSSAPI Configuration +:navtitle: Kerberos GSSAPI Configuration + +:pages-path: distributed +include::partial$configure/kerberos.adoc[] diff --git a/docs/modules/servers/pages/postgres/configure/kerberos.adoc b/docs/modules/servers/pages/postgres/configure/kerberos.adoc new file mode 100644 index 0000000000..fdd0eb8760 --- /dev/null +++ b/docs/modules/servers/pages/postgres/configure/kerberos.adoc @@ -0,0 +1,5 @@ += Postgresql James Server — Kerberos GSSAPI Configuration +:navtitle: Kerberos GSSAPI Configuration + +:pages-path: postgres +include::partial$configure/kerberos.adoc[] diff --git a/docs/modules/servers/partials/configure/forExtensionsPartial.adoc b/docs/modules/servers/partials/configure/forExtensionsPartial.adoc index d1088436e6..b3fed8beb5 100644 --- a/docs/modules/servers/partials/configure/forExtensionsPartial.adoc +++ b/docs/modules/servers/partials/configure/forExtensionsPartial.adoc @@ -12,4 +12,5 @@ By omitting these files, no extra behaviour is added. ** xref:{xref-base}/collecting-events.adoc[This page] documents event collection ** xref:{xref-base}/dsn.adoc[This page] specified how to support SMTP Delivery Submission Notification (link:https://tools.ietf.org/html/rfc3461[RFC-3461]) ** xref:{xref-base}/droplists.adoc[This page] allows configuring drop lists. -** xref:{xref-base}/mta-sts.adoc[This page] for configuring MTA-STS (RFC-8461) \ No newline at end of file +** xref:{xref-base}/mta-sts.adoc[This page] for configuring MTA-STS (RFC-8461) +** xref:{xref-base}/kerberos.adoc[This page] documents optional Kerberos GSSAPI authentication. diff --git a/docs/modules/servers/partials/configure/imap.adoc b/docs/modules/servers/partials/configure/imap.adoc index daaa86acce..459c88d66e 100644 --- a/docs/modules/servers/partials/configure/imap.adoc +++ b/docs/modules/servers/partials/configure/imap.adoc @@ -114,12 +114,19 @@ The `auth` element mentioned above has the following options. | Enables the authentication mechanisms `PLAIN` and `LOGIN`. It is an optional boolean that defaults to `true`. +| `auth.saslMechanisms` +| Optional comma-separated list of SASL mechanism factory class names. +When present, this list replaces the default mechanisms. +Built-in factories can be named by their simple class name; extension factories must use their fully qualified class name. +See xref:{pages-path}/configure/kerberos.adoc[Kerberos GSSAPI authentication] for an extension example. + | `auth.requireSSL` -| Configures whether the authentication mechanisms `PLAIN` and `LOGIN` require a secure connection (TLS or STARTTLS). +| Configures whether the authentication mechanisms `PLAIN`, `LOGIN`, and optional `GSSAPI` require a secure connection (TLS or STARTTLS). It has no effect on other authentication mechanisms. -It also has no effect if `plainAuthEnabled` is `false`. +For `PLAIN` and `LOGIN`, it has no effect if `plainAuthEnabled` is `false`. The value is optional. -If not configured, it uses the value of `plainAuthDisallowed` (which defaults to `true`) as fallback. +For `PLAIN` and `LOGIN`, if not configured, it uses the value of `plainAuthDisallowed` (which defaults to `true`) as fallback. +For `GSSAPI`, if not configured, it defaults to `true`. | `auth.adminUsers` | Configures admin users that are authorized to impersonate any IMAP user. @@ -130,6 +137,10 @@ It is an optional element containing `adminUser` elements. | Configures authentication via OIDC. The configuration is described in more detail xref:{pages-path}/configure/oidc.adoc[here]. +| `auth.gssapi` +| Configures optional Kerberos authentication through the `GSSAPI` SASL mechanism. +The configuration is described in more detail xref:{pages-path}/configure/kerberos.adoc[here]. + |=== == Traffic Shaping diff --git a/docs/modules/servers/partials/configure/kerberos.adoc b/docs/modules/servers/partials/configure/kerberos.adoc new file mode 100644 index 0000000000..5509e3c138 --- /dev/null +++ b/docs/modules/servers/partials/configure/kerberos.adoc @@ -0,0 +1,94 @@ +James supports Kerberos authentication for IMAP and SMTP through the SASL `GSSAPI` mechanism defined by +link:https://www.rfc-editor.org/rfc/rfc4752.html[RFC 4752]. +This mechanism is an optional extension and is not enabled or announced by default. + +== Installation + +Build the `protocols/sasl-kerberos` Maven module and copy its JAR into the `extensions-jars` directory of the Guice James distribution. +The JAR is not included as a runtime dependency of the standard James applications. + +The James host needs a working Kerberos configuration, synchronized time, correct forward DNS, and service principals matching the public mail hostname. +Create distinct service principals and keytabs for each protocol, for example: + +.... +imap/[email protected] +smtp/[email protected] +.... + +Run James with an operating-system account that can read the keytabs, and restrict their filesystem permissions to that account. + +== Configuration + +Add the GSSAPI factory to `auth.saslMechanisms` in each protocol configuration. +An explicit `auth.saslMechanisms` value replaces the protocol defaults, so list every mechanism that should remain enabled. + +For IMAP, `PlainSaslMechanismFactory` also backs the IMAP `LOGIN` command: + +[source,xml] +.... +<auth> + <requireSSL>true</requireSSL> + <saslMechanisms>PlainSaslMechanismFactory,org.apache.james.protocols.sasl.kerberos.GssapiSaslMechanismFactory</saslMechanisms> + <gssapi> + <serviceName>imap</serviceName> + <serverName>mail.example.com</serverName> + <principal>imap/[email protected]</principal> + <keyTab>/run/secrets/james/imap.keytab</keyTab> + </gssapi> +</auth> +.... + +For SMTP, list both password mechanism factories when retaining `LOGIN` and `PLAIN`: + +[source,xml] +.... +<auth> + <announce>always</announce> + <requireSSL>true</requireSSL> + <saslMechanisms>LoginSaslMechanismFactory,PlainSaslMechanismFactory,org.apache.james.protocols.sasl.kerberos.GssapiSaslMechanismFactory</saslMechanisms> + <gssapi> + <serviceName>smtp</serviceName> + <serverName>mail.example.com</serverName> + <principal>smtp/[email protected]</principal> + <keyTab>/run/secrets/james/smtp.keytab</keyTab> + </gssapi> +</auth> +<maxLineLength>65536</maxLineLength> +.... + +The `auth.gssapi` properties are: + +|=== +| Property | Description + +| `serviceName` +| Kerberos service component used by the protocol, e.g. `imap` or `smtp`. + +| `serverName` +| Kerberos host component. It must be the canonical hostname clients use when requesting a service ticket. + +| `principal` +| Acceptor principal. It must exactly match `serviceName/serverName@REALM`. + +| `keyTab` +| Absolute path or `file:` URI of a readable keytab containing the acceptor principal. + +|=== + +GSSAPI uses the top-level `auth.requireSSL` transport policy and defaults to requiring TLS when that property is absent. +SMTP also applies `auth.announce` and `auth.requireSSL` when advertising authentication. +Kerberos tokens can exceed SMTP's default 8,192-byte line limit; set `maxLineLength` to a measured operational value when needed. +The value applies globally to SMTP input and must remain bounded. + +== Identity And Security + +The authenticated Kerberos principal is mapped to a James username, including its realm. +Because James usernames are case-insensitive while Kerberos principals are case-sensitive, James accepts only canonical client principals: +the identity must contain only ASCII characters, principal components must be lower case, and the realm must be upper case, for example `[email protected]`. +Noncanonical variants such as `[email protected]` and `[email protected]` are rejected so that distinct Kerberos principals cannot map to the same James identity. +The resulting James username is lower case; provision that username and domain when the protocol needs a local account, notably for IMAP mailbox access. +When a client requests a different SASL authorization identity, James applies its normal authorization rules. + +The implementation accepts only the SASL `auth` quality of protection. +It does not negotiate a SASL integrity or confidentiality layer; use TLS to protect protocol traffic. +Keeping `auth.requireSSL` set to `true` is recommended. diff --git a/docs/modules/servers/partials/configure/smtp.adoc b/docs/modules/servers/partials/configure/smtp.adoc index 92721f56fc..13e5666d44 100644 --- a/docs/modules/servers/partials/configure/smtp.adoc +++ b/docs/modules/servers/partials/configure/smtp.adoc @@ -136,21 +136,33 @@ However, if authentication capabilities are not announced, only the mechanisms ` | Configures whether announcing authentication capabilities requires a secure connection (TLS or STARTTLS). If this value is `true` and the connection is not secure, authentication capabilities are not announced. This always holds, even if `auth.announce` is set to `always`. +The optional `GSSAPI` mechanism also uses this value to reject authentication attempts over an insecure connection. It is an optional boolean that defaults to `true`. -Note that this configures only the **announcement** of authentication capabilities. -Even if authentication capabilities are not announced, clients can still use the SMTP AUTH command with the mechanisms `PLAIN` and `LOGIN`. +For the built-in mechanisms, this configures only the **announcement** of authentication capabilities. +Even if authentication capabilities are not announced, clients can still use the SMTP AUTH command with `PLAIN` and `LOGIN`. However, as the mechanisms `XOAUTH2` and `OAUTHBEARER` are only available if authentication mechanisms are announced, those mechanisms can only be used in secure connections if `auth.requireSSL` is set to `true`. +When `GSSAPI` is configured and `auth.requireSSL` is `true`, it is both unannounced and unavailable on insecure connections. | `auth.plainAuthEnabled` | Enables the authentication mechanisms `PLAIN` and `LOGIN`. It is an optional boolean that defaults to `true`. +| `auth.saslMechanisms` +| Optional comma-separated list of SASL mechanism factory class names. +When present, this list replaces the default mechanisms. +Built-in factories can be named by their simple class name; extension factories must use their fully qualified class name. +See xref:{pages-path}/configure/kerberos.adoc[Kerberos GSSAPI authentication] for an extension example. + | `auth.oidc` | Configures authentication via OIDC. The configuration is described in more detail xref:{pages-path}/configure/oidc.adoc[here]. +| `auth.gssapi` +| Configures optional Kerberos authentication through the `GSSAPI` SASL mechanism. +The configuration is described in more detail xref:{pages-path}/configure/kerberos.adoc[here]. + | `auth.required` | Requires authentication for submitting an email to the SMTP server. This configuration is intended for submission-only SMTP servers (e.g, port 587). @@ -165,7 +177,7 @@ Note that `authorizedAddresses` are considered authenticated. == Security -James supports authentication with username / password (`PLAIN` and `LOGIN`) and OIDC (`XOAUTH2` and `OAUTHBEARER`). +James supports authentication with username / password (`PLAIN` and `LOGIN`), OIDC (`XOAUTH2` and `OAUTHBEARER`), and optional Kerberos (`GSSAPI`). SMTP authentication is essential to prevent sender address spoofing and open relays. For the concepts explained below, the distinction between local and external users is important. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
