This is an automated email from the ASF dual-hosted git repository.
btellier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
The following commit(s) were added to refs/heads/master by this push:
new c345494 [DOCUMENTATION] Example for deploying MUA auto-configuration
(#882)
c345494 is described below
commit c345494a04c246fe4c06b1239114d98e9afb3012
Author: Benoit TELLIER <[email protected]>
AuthorDate: Fri Feb 11 15:22:34 2022 +0700
[DOCUMENTATION] Example for deploying MUA auto-configuration (#882)
- RFC-6186 Using SRV records
- Auto-configuration for thunderbirds
- Notes on JMAP auto-configuration
---
examples/README.md | 4 +
examples/imap-autoconf/README.adoc | 86 +++++++++++++++++++++
.../content/.well-known/mail/config-v1.1.xml | 21 +++++
.../imap-autoconf/content/mail/config-v1.1.xml | 21 +++++
examples/imap-autoconf/docker-compose.yml | 21 +++++
examples/imap-autoconf/keystore | Bin 0 -> 2711 bytes
examples/imap-autoconf/thunderbird_autoconf.png | Bin 0 -> 100354 bytes
.../docs/modules/ROOT/pages/configure/imap.adoc | 8 +-
.../docs/modules/ROOT/pages/configure/jmap.adoc | 16 +++-
src/homepage/howTo/imap-server.html | 2 +
src/site/xdoc/server/config-imap4.xml | 4 +
src/site/xdoc/server/config-jmap.xml | 11 +++
12 files changed, 191 insertions(+), 3 deletions(-)
diff --git a/examples/README.md b/examples/README.md
index 301fc7e..b748f9f 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -71,3 +71,7 @@ This example uses:
- [Thunderbird](https://www.thunderbird.net/en-US/) as a Mail User Agent.
(version 91.4.1)
Of course alternative technologies can be used.
+
+## Auto-configuration of Mail User Agents
+
+[This example](imap-autoconf) demonstrates how to deploy auto-configuration
for various mail user agents.
\ No newline at end of file
diff --git a/examples/imap-autoconf/README.adoc
b/examples/imap-autoconf/README.adoc
new file mode 100644
index 0000000..2b855b3
--- /dev/null
+++ b/examples/imap-autoconf/README.adoc
@@ -0,0 +1,86 @@
+= Auto-configuration of Mail User Agents
+
+== RFC-6186 use of SRV records
+
+link:https://tools.ietf.org/html/rfc6186[RFC-6186] defines the usage of SRV
records in order
+to help users configuring their Mail User Agents in order to access your
service, as it allows
+to locate your services (hostnames and ports).
+
+You would then need to publish SRV records on your DNS.
+
+----
+_imaps._tcp.domain.tld. 3600 IN SRV 0 1 993 imap.domain.tld.
+_submission._tcp.domain.tld. 3600 IN SRV 0 1 587 smtp.domain.tld.
+_jmap._tcp.domain.tld. 3600 IN SRV 0 1 443 jmap.domain.tld.
+----
+
+== Thunderbird
+
+Thunderbird relies on a custom XML payload being served on a subdomain.
+
+For `[email protected]` an HTTP GET request would be done at
`http://autoconfig.domain.tld/mail/config-v1.1.xml`
+
+You could for instance serve the following XML payload:
+
+[xml]
+----
+<clientConfig version="1.1">
+ <emailProvider id="MessagingEngine">
+ <domain>domain.tld</domain>
+ <displayName>My company</displayName>
+ <displayShortName>My company</displayShortName>
+ <incomingServer type="imap">
+ <hostname>imap.domain.tld</hostname>
+ <port>993</port>
+ <socketType>SSL</socketType>
+ <authentication>password-cleartext</authentication>
+ <username>%EMAILADDRESS%</username>
+ </incomingServer>
+ <outgoingServer type="smtp">
+ <hostname>smtp.domain.tld</hostname>
+ <port>465</port>
+ <socketType>SSL</socketType>
+ <authentication>password-cleartext</authentication>
+ <username>%EMAILADDRESS%</username>
+ </outgoingServer>
+ </emailProvider>
+</clientConfig>
+----
+
+== JMAP
+
+link:https://datatracker.ietf.org/doc/html/rfc8620[RFC-8620] defining JMAP
core RFC defines precisely service location.
+
+James already redirects `http://jmap.domain.tld/.well-known/jmap` to the JMAP
session.
+
+You can further help your clients by publishing extra SRV records (see above).
+
+== Example
+
+We ship a little example hereby to ease set up.
+
+It is comprised of a docker-compose starting a James and a side container to
serve Thunderbird auto-configuration.
+
+ - 1. Start the docker-compose
+
+----
+docker-compose up
+----
+
+ - 2. Create `domain.tld` and a user `[email protected]` with a strong password
(`123456`)
+
+----
+docker exec -ti james james-cli AddDomain domain.tld
+docker exec -ti james james-cli Adduser [email protected] 123456
+----
+
+ - 3. Register the domains `autoconfig.domain.tld`, `imap.domain.tld` and
`smtp.domain.tld` in your `/etc/hosts` file.
+
+----
+127.0.0.1 domain.tld imap.domain.tld smtp.domain.tld
autoconfig.domain.tld
+# ...
+----
+
+ - 4. Start Thunderbird and enjoy auto-configuration!
+
+image:thunderbird_autoconf.png[Auto-configuration was applied in Thunderbird]
\ No newline at end of file
diff --git a/examples/imap-autoconf/content/.well-known/mail/config-v1.1.xml
b/examples/imap-autoconf/content/.well-known/mail/config-v1.1.xml
new file mode 100644
index 0000000..d1244d0
--- /dev/null
+++ b/examples/imap-autoconf/content/.well-known/mail/config-v1.1.xml
@@ -0,0 +1,21 @@
+<clientConfig version="1.1">
+ <emailProvider id="MessagingEngine">
+ <domain>domain.tld</domain>
+ <displayName>My company</displayName>
+ <displayShortName>My company</displayShortName>
+ <incomingServer type="imap">
+ <hostname>imap.domain.tld</hostname>
+ <port>993</port>
+ <socketType>SSL</socketType>
+ <authentication>password-cleartext</authentication>
+ <username>%EMAILADDRESS%</username>
+ </incomingServer>
+ <outgoingServer type="smtp">
+ <hostname>smtp.domain.tld</hostname>
+ <port>465</port>
+ <socketType>SSL</socketType>
+ <authentication>password-cleartext</authentication>
+ <username>%EMAILADDRESS%</username>
+ </outgoingServer>
+ </emailProvider>
+</clientConfig>
\ No newline at end of file
diff --git a/examples/imap-autoconf/content/mail/config-v1.1.xml
b/examples/imap-autoconf/content/mail/config-v1.1.xml
new file mode 100644
index 0000000..d1244d0
--- /dev/null
+++ b/examples/imap-autoconf/content/mail/config-v1.1.xml
@@ -0,0 +1,21 @@
+<clientConfig version="1.1">
+ <emailProvider id="MessagingEngine">
+ <domain>domain.tld</domain>
+ <displayName>My company</displayName>
+ <displayShortName>My company</displayShortName>
+ <incomingServer type="imap">
+ <hostname>imap.domain.tld</hostname>
+ <port>993</port>
+ <socketType>SSL</socketType>
+ <authentication>password-cleartext</authentication>
+ <username>%EMAILADDRESS%</username>
+ </incomingServer>
+ <outgoingServer type="smtp">
+ <hostname>smtp.domain.tld</hostname>
+ <port>465</port>
+ <socketType>SSL</socketType>
+ <authentication>password-cleartext</authentication>
+ <username>%EMAILADDRESS%</username>
+ </outgoingServer>
+ </emailProvider>
+</clientConfig>
\ No newline at end of file
diff --git a/examples/imap-autoconf/docker-compose.yml
b/examples/imap-autoconf/docker-compose.yml
new file mode 100644
index 0000000..999529e
--- /dev/null
+++ b/examples/imap-autoconf/docker-compose.yml
@@ -0,0 +1,21 @@
+version: '3'
+
+services:
+
+ james:
+ image: apache/james:memory-latest
+ container_name: james
+ hostname: james.local
+ volumes:
+ - ./keystore:/root/conf/keystore
+ ports:
+ - "465:465"
+ - "993:993"
+ - "8000:8000"
+ autoconf:
+ image: nginx
+ container_name: autoconf
+ volumes:
+ - ./content:/usr/share/nginx/html
+ ports:
+ - "80:80"
\ No newline at end of file
diff --git a/examples/imap-autoconf/keystore b/examples/imap-autoconf/keystore
new file mode 100644
index 0000000..361cd01
Binary files /dev/null and b/examples/imap-autoconf/keystore differ
diff --git a/examples/imap-autoconf/thunderbird_autoconf.png
b/examples/imap-autoconf/thunderbird_autoconf.png
new file mode 100644
index 0000000..46c16a9
Binary files /dev/null and b/examples/imap-autoconf/thunderbird_autoconf.png
differ
diff --git
a/server/apps/distributed-app/docs/modules/ROOT/pages/configure/imap.adoc
b/server/apps/distributed-app/docs/modules/ROOT/pages/configure/imap.adoc
index 7acbc0b..57adb35 100644
--- a/server/apps/distributed-app/docs/modules/ROOT/pages/configure/imap.adoc
+++ b/server/apps/distributed-app/docs/modules/ROOT/pages/configure/imap.adoc
@@ -109,9 +109,13 @@ will use the specified value.
|===
-=== OIDC setup
+== OIDC setup
James IMAP support XOAUTH2 authentication mechanism which allow authenticating
against a OIDC providers.
Please configure `auth.oidc` part to use this.
We do supply an
link:https://github.com/apache/james-project/tree/master/examples/oidc[example]
of such a setup.
-It uses the Keycloak OIDC provider, but usage of similar technologies is
definitely doable.
\ No newline at end of file
+It uses the Keycloak OIDC provider, but usage of similar technologies is
definitely doable.
+
+== Mail user agents auto-configuration
+
+Check this example on
link:https://github.com/apache/james-project/tree/master/examples/imap-autoconf[Mail
user agents auto-configuration].
diff --git
a/server/apps/distributed-app/docs/modules/ROOT/pages/configure/jmap.adoc
b/server/apps/distributed-app/docs/modules/ROOT/pages/configure/jmap.adoc
index c324cfd..3217307 100644
--- a/server/apps/distributed-app/docs/modules/ROOT/pages/configure/jmap.adoc
+++ b/server/apps/distributed-app/docs/modules/ROOT/pages/configure/jmap.adoc
@@ -141,4 +141,18 @@ The list of tested JMAP clients are:
- [OpenPaaS](https://open-paas.org/) is actively using the draft version of
the JMAP implementation. Migration to
RFC-8621 is planned.
- Experiments had been run on top of
[LTT.RS](https://github.com/iNPUTmice/lttrs-android). Version in the Accept
- headers needs to be explicitly set to `rfc-8621`. [Read
more](https://github.com/linagora/james-project/pull/4089).
\ No newline at end of file
+ headers needs to be explicitly set to `rfc-8621`. [Read
more](https://github.com/linagora/james-project/pull/4089).
+
+== JMAP auto-configuration
+
+link:https://datatracker.ietf.org/doc/html/rfc8620[RFC-8620] defining JMAP
core RFC defines precisely service location.
+
+James already redirects `http://jmap.domain.tld/.well-known/jmap` to the JMAP
session.
+
+You can further help your clients by publishing extra SRV records.
+
+Eg:
+
+----
+_jmap._tcp.domain.tld. 3600 IN SRV 0 1 443 jmap.domain.tld.
+----
\ No newline at end of file
diff --git a/src/homepage/howTo/imap-server.html
b/src/homepage/howTo/imap-server.html
index 7a9ed5d..b4adf58 100644
--- a/src/homepage/howTo/imap-server.html
+++ b/src/homepage/howTo/imap-server.html
@@ -217,6 +217,8 @@ docker exec james_run java -jar /root/james-cli.jar AddUser
[email protected] secr
<h2><b>Additional features</b></h2>
</header>
+ <p>Check this example on <a
href="https://github.com/apache/james-project/tree/master/examples/imap-autoconf";>Mail
user agents autoconfiguration</a>.</p>
+
<p>James is a large project with many features. You can go
further and complete your installation with
an <a
href="http://james.apache.org/server/config-antispam.html";>AntiSpam system</a>,
or set up
<a
href="http://james.apache.org/server/metrics.html";>metric display</a>, collect
logs in ElasticSearch for a display in Kibana,
diff --git a/src/site/xdoc/server/config-imap4.xml
b/src/site/xdoc/server/config-imap4.xml
index 69dd203..399c9f1 100644
--- a/src/site/xdoc/server/config-imap4.xml
+++ b/src/site/xdoc/server/config-imap4.xml
@@ -105,6 +105,10 @@
<p>We do supply an <a
href="https://github.com/apache/james-project/tree/master/examples/oidc";>example</a>
of such a setup. It uses the
<a href="https://www.keycloak.org/";>Keycloack</a> OIDC provider,
but usage of similar technologies is definitely doable.</p>
</subsection>
+
+ <subsection name="Mail user agents auto-configuration">
+ <p>Check this example on <a
href="https://github.com/apache/james-project/tree/master/examples/imap-autoconf";>Mail
user agents auto-configuration</a>.</p>
+ </subsection>
</section>
</body>
diff --git a/src/site/xdoc/server/config-jmap.xml
b/src/site/xdoc/server/config-jmap.xml
index 03e8834..2c06840 100644
--- a/src/site/xdoc/server/config-jmap.xml
+++ b/src/site/xdoc/server/config-jmap.xml
@@ -174,6 +174,17 @@
headers needs to be explicitly set to `rfc-8621`. <a
href="https://github.com/linagora/james-project/pull/4089";>Read more</a>.</li>
</ul>
</subsection>
+
+ <subsection name="JMAP auto-configuration">
+
+ <p><a
href="https://datatracker.ietf.org/doc/html/rfc8620";>RFC-8620</a> defining JMAP
core RFC defines precisely service location.</p>
+
+ <p>James already redirects
`http://jmap.domain.tld/.well-known/jmap` to the JMAP session.</p>
+
+ <p>You can further help your clients by publishing extra SRV
records.</p>
+
+ <pre><code>_jmap._tcp.domain.tld. 3600 IN SRV 0 1
443 jmap.domain.tld.</code></pre>
+ </subsection>
</section>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
