Distributed James Server — jmap.properties

JMAP is intended to be a new standard for email clients to connect to mail stores. It therefore intends to primarily replace IMAP + SMTP submission. It is also designed to be more generic. It does not replace MTA-to-MTA SMTP transmission.

Consult this example to get some examples and hints.

Table 1. jmap.properties content
Property name explanation

enabled

true/false. Governs whether JMAP should be enabled

jmap.port

Optional. Defaults to 80. The port this server will be listening on. This value must be a valid port, ranging between 1 and 65535 (inclusive)

tls.keystoreURL

Keystore to be used for generating authentication tokens for password authentication mechanism. This should not be the same keystore than the ones used by TLS based protocols.

tls.secret

Password used to read the keystore

jwt.publickeypem.url

Optional. JWT tokens allow request to bypass authentication

url.prefix

Optional. Configuration urlPrefix for JMAP routes.

Default value: http://localhost.

upload.max.size

Optional. Configuration max size Upload in new JMAP-RFC-8621.

Default value: 30M. Supported units are B (bytes) K (KB) M (MB) G (GB).

view.email.query.enabled

Optional boolean. Defaults to false.

Should simple Email/query be resolved against a Cassandra projection, or should we resolve them against ElasticSearch? This enables a higher resilience, but the projection needs to be correctly populated.

jmap.version.default

Optional string. Defaults to draft. Allowed values: draft, rfc-8621.

Which version of the JMAP protocol should be served when none supplied in the Accept header. Defaults to draft for legacy reasons (avoid breaking changes) but setting the value to rfc-8621 allow compatibility with other third party apps.

Wire tapping

Enabling TRACE on org.apache.james.jmap.wire enables reactor-netty wiretap, logging of all incoming and outgoing requests, outgoing requests. This will log also potentially sensible information like authentication credentials.

Generating a JWT key pair

The Distributed server enforces the use of RSA-SHA-256.

One can use OpenSSL to generate a JWT key pair :

# private key
openssl genrsa -out rs256-4096-private.rsa 4096
# public key
openssl rsa -in rs256-4096-private.rsa -pubout > rs256-4096-public.pem

The private key can be used to generate JWT tokens, for instance using jwtgen:

jwtgen -a RS256 -p rs256-4096-private.rsa 4096 -c "sub=bob@domain.tld" -e 3600 -V

This token can then be passed as Bearer of the Authorization header :

curl -H "Authorization: Bearer $token" -XPOST http://127.0.0.1:80/jmap -d '...'

The public key can be referenced as jwt.publickeypem.url of the jmap.properties configuration file.

Annotated specification

The [annotated documentation](https://github.com/apache/james-project/tree/master/server/protocols/jmap-rfc-8621/doc/specs/spec) presents the limits of the JMAP RFC-8621 implementation part of the Apache James project. We furthermore implement [JSON Meta Application Protocol (JMAP) Subprotocol for WebSocket](https://tools.ietf.org/html/rfc8887).

Some methods / types are not yet implemented, some implementations are naive, and the PUSH is not supported yet.

Users are invited to read these limitations before using actively the JMAP RFC-8621 implementation, and should ensure their client applications only uses supported operations.

Contributions enhancing support are furthermore welcomed.

The list of tested JMAP clients are: