Distributed James Server — webadmin.properties

The web administration supports for now the CRUD operations on the domains, the users, their mailboxes and their quotas, managing mail repositories, performing cassandra migrations, and much more, as described in the following sections.

WARNING: This API allows authentication only via the use of JWT. If not configured with JWT, an administrator should ensure an attacker can not use this API.

By the way, some endpoints are not filtered by authentication. Those endpoints are not related to data stored in James, for example: Swagger documentation & James health checks.

Configuration

Consult this example to get some examples and hints.

Table 1. webadmin.properties content
Property name explanation

enabled

Define if WebAdmin is launched (default: false)

port

Define WebAdmin’s port (default: 8080)

host

Define WebAdmin’s host (default: localhost)

cors.enable

Allow the Cross-origin resource sharing (default: false)

cors.origin

Specify ths CORS origin (default: null)

jwt.enable

Allow JSON Web Token as an authentication mechanism (default: false)

https.enable

Use https (default: false)

https.keystore

Specify a keystore file for https (default: null)

https.password

Specify the keystore password (default: null)

https.trust.keystore

Specify a truststore file for https (default: null)

https.trust.password

Specify the truststore password (default: null)

jwt.publickeypem.url

Optional. JWT tokens allow request to bypass authentication. Path to the JWT public key. Defaults to the jwt.publickeypem.url value of jmap.properties file if unspecified (legacy behaviour)

extensions.routes

List of Routes specified as fully qualified class name that should be loaded in addition to your product routes list. Routes needs to be on the classpath or in the ./extensions-jars folder. Read mode about creating you own webadmin routes.

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" -c "admin=true" -e 3600 -V

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

curl -H "Authorization: Bearer $token" -XGET http://127.0.0.1:8000/domains

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