$headContent

WebAdmin Configuration

Consult webadmin.properties in GIT to get some examples and hints.

The following settings are available in webadmin.properties to configure the WebAdmin HTTP server:

enabled
Define if WebAdmin is launched (default: false)
port
Define WebAdmin's port (default: 8080)
host
Define WebAdmin's host (default: localhost, use 0.0.0.0 to listen on all addresses)
cors.enable
Allow the Cross-origin resource sharing (default: false)
cors.origin
Specify ths CORS origin (default: null)
jwt.enable
Require JWT (JSON Web Token) authentication (default: false)
jwt.publickeypem.url
Specify the public key used to verify JWT tokens. Must be a url pointing to a PEM file, e.g. file://conf/jwt.public.pem.
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)
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.
maxThreadCount
Maximum threads used by the underlying Jetty server. Optional.
minThreadCount
Minimum threads used by the underlying Jetty server. Optional.

Reverse Proxy Setup

WebAdmin adds the value of X-Real-IP header as part of the logging MDC.

This allows for reverse proxies to cary other the IP address of the client down to the JMAP server for diagnostic purpose.

Authentication

By default, the jwt.enable setting is set to false, i.e. there is no authentication at all, and anyone can access the WebAdmin api with no restrictions. Administrators are highly encouraged to either enable JWT or disable the webadmin interface altogether, to prevent abuse of the server and unrestricted access to user data.

To configure JWT:

  • Generate a pair of authentication keys, using standard algorithms such as RSA or EC. For example, to generate EC keys using openssl:
    openssl ecparam -name prime256v1 -genkey -noout -out jwt.private.pem
    openssl ec -in jwt.private.pem -pubout -out jwt.public.pem
  • Prepare the JWT header and payload claims:
    • alg (header) - the signing algorithm, which must correspond to the key type, e.g. RS256 for RSA or ES256 for EC.
    • kid (header, optional) - identifies the key used to sign and verify the JWT. This is the JWK thumbprint of the key (as defined in RFC 7638).
    • sub - the address of the user, e.g. admin@example.com.
    • admin - must be true (boolean literal, not string) to access admin operations.
    • exp - (optional) the token expiration time, as the number of seconds (not milliseconds) since the epoch, a.k.a "unix time". If this claim is omitted, the token never expires.
    For example, a token might have the header {"alg":"ES256","typ":"JWT"} and payload {"sub":"admin@example.com","admin":true,"exp":946684800}. Additional standard or James-specific claims may be supported in the future to allow finer-grained access control.
  • Encode and sign the JWT data using the private key and encode the final token. There are various tools and tutorials on how to do this. Do note that if you sign it using openssl and EC, you may need to convert the signature from the ASN.1 format to the padded raw numeric values required in the JWT.
  • Save the private key somewhere safe with restrictive permissions. The server does not need it to verify token signatures, but you will need it to generate new tokens in the future.
  • Save the public key somewhere where the server can read it, such as in the James conf folder.
  • Set jwt.enable to true.
  • Set jwt.publickeypem.url to the url of the public key PEM file, e.g. file://conf/jwt.public.pem
  • set https.enable and configure the other related https.* options to enable HTTPS, so that the token will not be intercepted and used by an attacker.

To use the token, send it with every HTTP request using a standard Authorization Bearer header:
Authorization: Bearer <the signed token>