This is an automated email from the ASF dual-hosted git repository. Arsnael pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/james-project.git
commit 453336f5e06e8addcd1423723865d7cc74fda175 Author: Felix Auringer <[email protected]> AuthorDate: Fri May 15 10:11:05 2026 +0200 refactor(docs): move docs for OIDC and AbstractConfigurableAsyncServer in own partials This also updates and completely reworks these parts of the documentation. Major corrections include: OIDC: - `oidc.oidcConfigurationURL`: This value is not used. - `oidc.scope`: This value is not used. - Clarify how tokens are validated depending on which config options are provided. Server: - `helloName` sometimes documented as `handler.helloName`. - Value of `helloName` is only used if `autodetect` is explicitly set to false. - It is `connectiontimeout`, NOT `connectionTimeout`. - Document default values. --- docs/modules/servers/nav.adoc | 4 + .../servers/pages/distributed/configure/oidc.adoc | 5 ++ .../pages/distributed/configure/server.adoc | 5 ++ .../servers/pages/postgres/configure/oidc.adoc | 5 ++ .../servers/pages/postgres/configure/server.adoc | 5 ++ docs/modules/servers/partials/configure/oidc.adoc | 69 ++++++++++++++++ .../modules/servers/partials/configure/server.adoc | 96 ++++++++++++++++++++++ 7 files changed, 189 insertions(+) diff --git a/docs/modules/servers/nav.adoc b/docs/modules/servers/nav.adoc index 1e619f3879..c2d183c438 100644 --- a/docs/modules/servers/nav.adoc +++ b/docs/modules/servers/nav.adoc @@ -27,6 +27,8 @@ ***** xref:distributed/run/k8s-secrets.adoc[secrets.yaml] *** xref:distributed/configure/index.adoc[] **** Protocols +***** xref:distributed/configure/server.adoc[Common Server Configuration] +***** xref:distributed/configure/oidc.adoc[OIDC Configuration] ***** xref:distributed/configure/imap.adoc[imapserver.xml] ***** xref:distributed/configure/jmap.adoc[jmap.properties] ***** xref:distributed/configure/jmx.adoc[jmx.properties] @@ -96,6 +98,8 @@ **** xref:postgres/run/run-docker.adoc[Run with Docker] *** xref:postgres/configure/index.adoc[] **** Protocols +***** xref:postgres/configure/server.adoc[Common Server Configuration] +***** xref:postgres/configure/oidc.adoc[OIDC 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/oidc.adoc b/docs/modules/servers/pages/distributed/configure/oidc.adoc new file mode 100644 index 0000000000..cacfddc86d --- /dev/null +++ b/docs/modules/servers/pages/distributed/configure/oidc.adoc @@ -0,0 +1,5 @@ += Distributed James Server — OIDC Configuration +:navtitle: OIDC Configuration + +:pages-path: distributed +include::partial$configure/oidc.adoc[] diff --git a/docs/modules/servers/pages/distributed/configure/server.adoc b/docs/modules/servers/pages/distributed/configure/server.adoc new file mode 100644 index 0000000000..ca058ce05a --- /dev/null +++ b/docs/modules/servers/pages/distributed/configure/server.adoc @@ -0,0 +1,5 @@ += Distributed James Server — Common Server Configuration +:navtitle: Common Server Configuration + +:pages-path: distributed +include::partial$configure/server.adoc[] diff --git a/docs/modules/servers/pages/postgres/configure/oidc.adoc b/docs/modules/servers/pages/postgres/configure/oidc.adoc new file mode 100644 index 0000000000..8a1ee5782e --- /dev/null +++ b/docs/modules/servers/pages/postgres/configure/oidc.adoc @@ -0,0 +1,5 @@ += Postgresql James Server — OIDC Configuration +:navtitle: OIDC Configuration + +:pages-path: postgres +include::partial$configure/oidc.adoc[] diff --git a/docs/modules/servers/pages/postgres/configure/server.adoc b/docs/modules/servers/pages/postgres/configure/server.adoc new file mode 100644 index 0000000000..f62acc5170 --- /dev/null +++ b/docs/modules/servers/pages/postgres/configure/server.adoc @@ -0,0 +1,5 @@ += Postgresql James Server — Common Server Configuration +:navtitle: Common Server Configuration + +:pages-path: postgres +include::partial$configure/server.adoc[] diff --git a/docs/modules/servers/partials/configure/oidc.adoc b/docs/modules/servers/partials/configure/oidc.adoc new file mode 100644 index 0000000000..85e3d1b9db --- /dev/null +++ b/docs/modules/servers/partials/configure/oidc.adoc @@ -0,0 +1,69 @@ + +James supports OIDC via both `XOAUTH2` and `OAUTHBEARER`. +Support is only available for Managesieve, IMAP, and SMTP. +OIDC is not supported for POP3 and LMTP. +We provide an link:https://github.com/apache/james-project/tree/master/examples/oidc[example] of an OIDC setup. +It uses Keycloak as identity provider, but usage of other providers is possible. + +== Token Validation + +Every access token is locally validated. +Local validation includes JWT validation using the established `io.jsonwebtoken` library with the configured JWKS and audience validation. +It extracts the username from a claim of the JWT. + +If the introspection URL is configured **and** the local validation was successful, the introspection endpoint is queried. +If the response indicates that the token is not active or the username in the response does not match the local username, the validation fails. + +If the userinfo URL is configured, the introspection URL is **not** configured, **and** the local validation was successful, the userinfo endpoint is queried. +If the username in the response does not match the local username, the validation fails. + +== Configuration + +OIDC authentication is enabled by adding the `oidc` element to the server configuration. +Please see the documentation of the concrete service for the exact location of the `oidc` element. + +.Configuration options for OIDC +|=== +| Property Name | Explanation + +| `oidc.oidcConfigurationURL` +| Sets the OIDC configuration URL (https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig) which can be used to retrieve other OIDC configuration values. +This is currently not used. +However, it is mandatory when OIDC is enabled. + +| `oidc.jwksURL` +| Sets the URL for retrieving the JSON Web Key Set (RFC 7517) used to locally validate access tokens. +It is mandatory when OIDC is enabled. + +| `oidc.claim` +| Configures the name of the claim used to identify a user. +This is usually `email_address` or `sub`. +It is mandatory when OIDC is enabled. + +| `oidc.scope` +| Configures which scopes should be requested (https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims). +This is currently not used as the email client is responsible for requesting the access token. +It is mandatory when OIDC is enabled. + +| `oidc.aud` +| Configures the expected audience for James (RFC 9068). +This should be unique among the clients of your identity provider. +It is mandatory when using OIDC for authentication, but this requirement can be relaxed with `-Djames.sasl.oidc.validate.aud=false`. +However, we strongly recommend to keep the audience validation enabled. + +| `oidc.introspection.url` +| Sets the URL of the OAuth 2.0 introspection endpoint (RFC 7662). +This is an optional value that enables additional checks. +Note that James always verifies the signature of the token even if this configuration is provided. + +| `oidc.introspection.auth` +| Configures the authorization for requests to the introspection endpoint. +If this and the introspection URL are provided, this is added as the value for the `Authorization` header. +Example value: `Basic xyz` + +| `oidc.userinfo.url` +| Sets the URL of the OIDC userinfo endpoint (https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). +This is an optional value that enables an additional check. +Note that James always verifies the signature of the token even if this configuration is provided. + +|=== diff --git a/docs/modules/servers/partials/configure/server.adoc b/docs/modules/servers/partials/configure/server.adoc new file mode 100644 index 0000000000..115a901ab9 --- /dev/null +++ b/docs/modules/servers/partials/configure/server.adoc @@ -0,0 +1,96 @@ +The XML elements of all servers have an optional attribute `enabled` which defaults to `true`. + +.Common configuration options for servers (SMTP, LMTP, POP3, IMAP, Managesieve) +|=== +| Property Name | Explanation + +| `bind` +| The option describes which IPv4 addresses and ports the server should bind to. +IPv6 addresses are not supported. +It is an optional, comma-separated list of `<IPv4>:<port>` tuples. +The default value is the IPv4 address `0.0.0.0` with the default port of the protocol +(24 for LMTP, 25 for SMTP, 110 for POP3, 143 for IMAP, and 4190 for Managesieve). + +| `jmxName` +| An optional name for the JMX of this server. +The default value is `lmtpserver` for LMTP, `smtpserver` for SMTP, `pop3server` for POP3, `imapserver` for IMAP, and `managesieveserver` for Managesieve. + +| `ioWorkerCount` +| Sets the maximum number of IO threads. +IO threads are responsible for receiving incoming messages and framing them +(split line by line). +IO threads also take care of compression and TLS. +Their tasks are short-lived and non-blocking. +It is an optional integer and defaults to 2 times the number of CPUs. + +| `bossWorkerCount` +| Sets the maximum number of boss threads. +Boss threads are responsible for accepting incoming connections and initializing associated resources. +It is an optional integer. +By default, boss threads are not used and and IO threads handle their tasks. + +| `maxExecutorCount` +| Sets the maximum number of worker threads. +Worker threads takes care of potentially blocking tasks like executing commands. +It is an optional integer which defaults to 16. + +| `helloName` +| Defines the server name used in the initial server greeting. +By default, Java libraries are used to get the local hostname. +If that fails, `localhost` is used. +If the element is present and the attribute `autodetect` is set to `false`, the body of this element is used instead. + +| `connectiontimeout` +| Sets the timeout for connection in seconds. +It is an optional integer with the default value 300. + +| `connectionBacklog` +| Sets the maximum number of queued connection requests (backlog). +It is an optional integer which defaults to 200. + +| `connectionLimit` +| Sets the maximum number of simultaneous incoming connections. +It is an optional, positive integer. +If not configured, there is no limit. + +| `connectionLimitPerIP` +| Sets the maximum number of simultaneous incoming connections per client IP. +It is an optional, positive integer. +If not configured, there is no limit. + +| `tls` +| Configures implicit TLS and STARTTLS. +The configuration is described in more detail xref:{pages-path}/configure/ssl.adoc[here]. + +| `gracefulShutdown` +| If `true`, the server attempts a graceful shutdown, which is safer but can take time. +It is a boolean that defaults to `true`. + +| `useEpoll` +| If `true`, the server uses the native EPOLL implementation for Netty, otherwise it uses NIO. +It is a boolean that defaults to `false`. + +| `highWriteBufferWaterMark`, `lowWriteBufferWaterMark` +| Configures a water mark for Netty's write buffer. +If none of the two elements is present, no water mark is set and Netty's defaults apply. +If only one of them is provided, both the high and the low water mark are set to that value. +The last character of the value may be a unit. +Supported units are `B` for bytes, `K` for kibibyte (1,024 bytes), `M` for mebibyte (1,024 kibibytes), and `G` for gibibyte (1,024 mebibytes). +If no unit is given, the value is interpreted as bytes. + +| `proxyRequired` +| Enables HAProxy's PROXY protocol for incoming connections. +PROXY protocol allows a reverse proxy in front of the email server to provide information about the original TCP connection. +This is most relevant for getting the real IP address of the client. +If this is enabled, all connections are **required** to use the PROXY protocol. +It is a boolean that defaults to `false`. + +| `proxyFirst` +| Configures the order of encapsulation of TLS and PROXY protocol. +If `true`, the server expects a PROXY protocol header first and TLS records (if enabled) after that. +This means the reverse proxy transparently proxies TCP connections and does not touch the TLS connection between client and email server. +If `false`, the server expects TLS records (if enabled) that contain a proxied connection. +This means the TLS connection is established between reverse proxy and email server. +It is a boolean that defaults to `true`. + +|=== --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
