| <?xml version="1.0"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| <document> |
| |
| <properties> |
| <title>Apache James Server 3 - WebAdmin Configuration</title> |
| </properties> |
| |
| <body> |
| |
| <section name="WebAdmin Configuration"> |
| |
| <p>Consult <a href="https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/webadmin.properties">webadmin.properties</a> in GIT to get some examples and hints.</p> |
| |
| <p>The following settings are available in webadmin.properties to configure the WebAdmin HTTP server:</p> |
| |
| <dl> |
| <dt><strong>enabled</strong></dt> |
| <dd>Define if WebAdmin is launched (default: false)</dd> |
| <dt><strong>port</strong></dt> |
| <dd>Define WebAdmin's port (default: 8080)</dd> |
| <dt><strong>host</strong></dt> |
| <dd>Define WebAdmin's host (default: localhost, use 0.0.0.0 to listen on all addresses)</dd> |
| <dt><strong>cors.enable</strong></dt> |
| <dd>Allow the Cross-origin resource sharing (default: false)</dd> |
| <dt><strong>cors.origin</strong></dt> |
| <dd>Specify ths CORS origin (default: null)</dd> |
| <dt><strong>jwt.enable</strong></dt> |
| <dd>Require JWT (JSON Web Token) authentication (default: false)</dd> |
| <dt><strong>jwt.publickeypem.url</strong></dt> |
| <dd>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.</dd> |
| <dt><strong>https.enable</strong></dt> |
| <dd>Use HTTPS (default: false)</dd> |
| <dt><strong>https.keystore</strong></dt> |
| <dd>Specify a keystore file for https (default: null)</dd> |
| <dt><strong>https.password</strong></dt> |
| <dd>Specify the keystore password (default: null)</dd> |
| <dt><strong>https.trust.keystore</strong></dt> |
| <dd>Specify a truststore file for https (default: null)</dd> |
| <dt><strong>https.trust.password</strong></dt> |
| <dd>Specify the truststore password (default: null)</dd> |
| <dt><strong>extensions.routes</strong></dt> |
| <dd>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.</dd> |
| <dt><strong>maxThreadCount</strong></dt> |
| <dd>Maximum threads used by the underlying Jetty server. Optional.</dd> |
| <dt><strong>minThreadCount</strong></dt> |
| <dd>Minimum threads used by the underlying Jetty server. Optional.</dd> |
| </dl> |
| |
| <subsection name="Reverse Proxy Setup"> |
| <p>WebAdmin adds the value of <code>X-Real-IP</code> header as part of the logging MDC.</p> |
| |
| <p>This allows for reverse proxies to cary other the IP address of the client down to the JMAP server for diagnostic purpose.</p> |
| </subsection> |
| |
| <subsection name="Authentication"> |
| <p>By default, the <code>jwt.enable</code> 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. |
| </p> |
| |
| <p>To configure JWT: |
| <ul> |
| <li>Generate a pair of authentication keys, using standard algorithms such as RSA or EC. |
| For example, to generate EC keys using openssl: |
| <br /><code>openssl ecparam -name prime256v1 -genkey -noout -out jwt.private.pem</code> |
| <br /><code>openssl ec -in jwt.private.pem -pubout -out jwt.public.pem</code> |
| </li> |
| <li>Prepare the JWT header and payload claims: |
| <ul> |
| <li><strong>alg</strong> (header) - the signing algorithm, which must correspond |
| to the key type, e.g. <code>RS256</code> for RSA or <code>ES256</code> for EC.</li> |
| <li><strong>kid</strong> (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).</li> |
| <li><strong>sub</strong> - the address of the user, e.g. <code>admin@example.com</code>.</li> |
| <li><strong>admin</strong> - must be true (boolean literal, not string) to access admin operations.</li> |
| <li><strong>exp</strong> - (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.</li> |
| </ul> |
| For example, a token might have the header <code>{"alg":"ES256","typ":"JWT"}</code> |
| and payload <code>{"sub":"admin@example.com","admin":true,"exp":946684800}</code>. |
| Additional standard or James-specific claims may be supported in the future to allow finer-grained access control. |
| </li> |
| <li>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. |
| </li> |
| <li>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.</li> |
| <li>Save the public key somewhere where the server can read it, such as in the James conf folder.</li> |
| <li>Set <code>jwt.enable</code> to true.</li> |
| <li>Set <code>jwt.publickeypem.url</code> to the url of the public key PEM file, e.g. <code>file://conf/jwt.public.pem</code></li> |
| <li>set <code>https.enable</code> and configure the other related https.* options to enable HTTPS, |
| so that the token will not be intercepted and used by an attacker.</li> |
| </ul> |
| </p> |
| |
| <p> |
| To use the token, send it with every HTTP request using a standard Authorization Bearer header: |
| <br /><code>Authorization: Bearer <the signed token></code> |
| </p> |
| </subsection> |
| </section> |
| |
| </body> |
| |
| </document> |
| |
