You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@james.apache.org by rc...@apache.org on 2020/10/14 02:31:34 UTC
[james-project] 08/22: JAMES-3424 Better document the use of JWT
This is an automated email from the ASF dual-hosted git repository.
rcordier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
commit 96ce3ed879081ab7c98943bf4097a28f80aa7e67
Author: Benoit Tellier <bt...@linagora.com>
AuthorDate: Sun Oct 11 09:29:35 2020 +0700
JAMES-3424 Better document the use of JWT
- How to generate keys ?
- How to generate tokens?
- How to use these tokens to authentify requests
---
.../servers/pages/distributed/configure/jmap.adoc | 22 ++++++++++++++++++++++
.../pages/distributed/configure/webadmin.adoc | 22 ++++++++++++++++++++++
2 files changed, 44 insertions(+)
diff --git a/docs/modules/servers/pages/distributed/configure/jmap.adoc b/docs/modules/servers/pages/distributed/configure/jmap.adoc
index bc679ac..0b5cce7 100644
--- a/docs/modules/servers/pages/distributed/configure/jmap.adoc
+++ b/docs/modules/servers/pages/distributed/configure/jmap.adoc
@@ -36,3 +36,25 @@ This should not be the same keystore than the ones used by TLS based protocols.
Enabling *TRACE* on `org.apache.james.jmap.wire` enables reactor-netty wiretap, logging of
all incoming and outgoing requests, outgoing requests. This will log also potentially sensible information
like authentication credentials.
+
+== 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" -e 3600 -V
+
+This token can then be passed as `Bearer` of the `Authorization` header :
+
+ curl -H "Authorization: Bearer $token" -XPOST http://127.0.0.1:80/jmap -d '...'
+
+The public key can be referenced as `jwt.publickeypem.url` of the `jmap.properties` configuration file.
diff --git a/docs/modules/servers/pages/distributed/configure/webadmin.adoc b/docs/modules/servers/pages/distributed/configure/webadmin.adoc
index 7b673e1..3e36c4f 100644
--- a/docs/modules/servers/pages/distributed/configure/webadmin.adoc
+++ b/docs/modules/servers/pages/distributed/configure/webadmin.adoc
@@ -64,3 +64,25 @@ 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" -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.
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org