docs/modules/servers/pages/distributed/configure/webadmin.adoc

= Distributed James Server — webadmin.properties
:navtitle: 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 link:https://github.com/apache/james-project/blob/master/dockerfiles/run/guice/cassandra-rabbitmq/destination/conf/webadmin.properties[example]
to get some examples and hints.

.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
xref:distributed/extending/webadmin-routes.adoc[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 link:https://github.com/vandium-io/jwtgen[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.