svn commit: r1866519 - in /ofbiz/ofbiz-framework/trunk/framework/security/src/docs/asciidoc: _include/sy-impersonation.adoc _include/sy-password-and-JWT.adoc security.adoc

Author: jleroux
Date: Fri Sep  6 15:37:22 2019
New Revision: 1866519

URL: http://svn.apache.org/viewvc?rev=1866519&view=rev
Log:
Improved: Document how to store the JWT secret key
(OFBIZ-10751)

AS discussed in dev ML at https://markmail.org/message/dtjnu7fdi5noeagk and
previously in OFBIZ-9833 & OFBIZ-10307 we want to document how to store the
JWT secret key.

We agreed about keeping it as a property OOTB; and giving a link from the
security properties file to suggest how to better do it in production.

Modified:
    ofbiz/ofbiz-framework/trunk/framework/security/src/docs/asciidoc/_include/sy-impersonation.adoc
    ofbiz/ofbiz-framework/trunk/framework/security/src/docs/asciidoc/_include/sy-password-and-JWT.adoc
    ofbiz/ofbiz-framework/trunk/framework/security/src/docs/asciidoc/security.adoc

Modified: ofbiz/ofbiz-framework/trunk/framework/security/src/docs/asciidoc/_include/sy-impersonation.adoc
URL: http://svn.apache.org/viewvc/ofbiz/ofbiz-framework/trunk/framework/security/src/docs/asciidoc/_include/sy-impersonation.adoc?rev=1866519&r1=1866518&r2=1866519&view=diff
==============================================================================
--- ofbiz/ofbiz-framework/trunk/framework/security/src/docs/asciidoc/_include/sy-impersonation.adoc (original)
+++ ofbiz/ofbiz-framework/trunk/framework/security/src/docs/asciidoc/_include/sy-impersonation.adoc Fri Sep  6 15:37:22 2019
@@ -43,7 +43,7 @@ Everything appears like if we were logge
 
 The only thing showing that we currently are impersonating a user is the little bottom-right image :
 
-image::impersonate-ico.png[Impersonate icon, pdfwidth=0.5in, align=right]
+image::impersonate-ico.png[Impersonate icon, pdfwidth=0.5in, align=left]
 
 This icon indicates, when clicking on it, the user impersonated, and offer a way to depersonate.
 

Modified: ofbiz/ofbiz-framework/trunk/framework/security/src/docs/asciidoc/_include/sy-password-and-JWT.adoc
URL: http://svn.apache.org/viewvc/ofbiz/ofbiz-framework/trunk/framework/security/src/docs/asciidoc/_include/sy-password-and-JWT.adoc?rev=1866519&r1=1866518&r2=1866519&view=diff
==============================================================================
--- ofbiz/ofbiz-framework/trunk/framework/security/src/docs/asciidoc/_include/sy-password-and-JWT.adoc (original)
+++ ofbiz/ofbiz-framework/trunk/framework/security/src/docs/asciidoc/_include/sy-password-and-JWT.adoc Fri Sep  6 15:37:22 2019
@@ -50,27 +50,52 @@ ____
 We currently use JWT in 2 places:
 
 . To let users safely recreate passwords (in backend and frontend)
-. To allow SSO (Single Sig-on) jumpings from an OFBiz instance to another OFBiz instance on another domain, by also using https://en.wikipedia.org/wiki/Cross-origin_resource_sharing[CORS] (
+. To allow SSO (Single Sign-on) jumpings from an OFBiz instance to another on another domain, by also using https://en.wikipedia.org/wiki/Cross-origin_resource_sharing[CORS] (
 Cross-origin resource sharing) on the target server
 
 
 ==== How to secure JWT
-When you use JWT, in order to sign your tokens, you have the choice of using a sole so called secret key or a pair of public/private keys:https://jwt.io/introduction/.
+When you use JWT, in order to sign your tokens, you have the choice of using a sole so called secret key or a pair of public/private keys: https://jwt.io/introduction/.
 
-You might prefer to use pair of public/private keys, but by default OFBiz uses a secret key. Remains the way how to store this secret key.
+You might prefer to use pair of public/private keys, for now by default OFBiz uses a simple secret key. Remains the way how to store this secret key. https://security.stackexchange.com/questions/87130/json-web-tokens-how-to-securely-store-the-key[This is an interesting introduction about this question].
 
-. The first idea which comes to mind is to use a property in the security.properties file. It's safe as long as your filesystem is not compromised.
-. You may also pick a SystemProperty entity. It's safe as long as your DB is not compromised.
-. We recommend to not use an environment variable to pass the uuid as those can be considered weak:
+. The first idea which comes to mind is to use a property in the security.properties file. It's safe as long as your file system is not compromised.
+. You may also pick a SystemProperty entity (overrides the file property). It's safe as long as your DB is not compromised.
+. We recommend to not use an environment variable as those can be considered weak:
+* http://movingfast.io/articles/environment-variables-considered-harmful
+* https://security.stackexchange.com/questions/49725/is-it-really-secure-to-store-api-keys-in-environment-variables
+    
+. You may want to tie the encryption key to the logged in user. This is with the password recreation feature. The JWT secret key is salted with a combination of the current logged in user and her/his password. This is a simple and effective safe way.
+. Use a https://tools.ietf.org/html/rfc7519#section-4.1.7[JTI] (JWT ID). A JTI prevents a JWT from being replayed. This https://auth0.com/blog/blacklist-json-web-token-api-keys/http://url[auth0 blog article get deeper in that].  The same is kinda achieved with the password recreation feature. When the user log in after the new password creation, the password has already been  changed. So the link (in the sent email) containing the JWT for the creation of the new password can't be reused.
+. Tie the encryption key to the hardware. You can refer to this https://en.wikipedia.org/wiki/Hardware_security_module[Wikipedia page] for more information.
 
-    http://movingfast.io/articles/environment-variables-considered-harmful/
-    https://security.stackexchange.com/questions/49725/is-it-really-secure-to-store-api-keys-in-environment-variables
+Note: if you want to use a pair of public/private keys you might want to consider  leveraging the Java Key Store that is also used by the "catalina" component to store certificates. Then don't miss to read:
 
+* https://cryptosense.com/blog/mighty-aphrodite-dark-secrets-of-the-java-keystore/
+* https://neilmadden.blog/2017/11/17/java-keystores-the-gory-details/
 
+Also remember that like everything a https://www.sjoerdlangkemper.nl/2016/09/28/attacking-jwt-authentication/[JWT can be attacked] and, though not used or tried in OFBiz yet,  https://github.com/auth0/java-jwt#using-a-keyprovider[a good way is to mitigate an attack by using a KeyProvider]
 
 ===== Properties
 
-The _security.properties_ file introduce two properties that control impersonation feature :
+The _security.properties_ file contains five related properties:
+
+    # -- If false, then no externalLoginKey parameters will be added to cross-webapp urls
+    security.login.externalLoginKey.enabled=true
+
+    # -- Security key used to encrypt and decrypt the autogenerated password in forgot password functionality.
+    login.secret_key_string=login.secret_key_string
+
+    # -- Time To Live of the token send to the external server in seconds, 10 seconds seems plenty enough OOTB. Custom projects might want set a lower value.
+    security.jwt.token.expireTime=1800
+
+    # -- Enables the internal Single Sign On feature which allows a token based login between OFBiz instances
+    # -- To make this work you also have to configure a secret key with security.token.key
+    security.internal.sso.enabled=false
+
+    # -- The secret key for the JWT token signature. Configuration in the SystemProperty entity is recommended for security reasons.
+    security.token.key=security.token.key
+
 
 === Last but not least
 Be sure to read https://cwiki.apache.org/confluence/display/OFBIZ/Keeping+OFBiz+secure[Keeping OFBiz secure]
\ No newline at end of file

Modified: ofbiz/ofbiz-framework/trunk/framework/security/src/docs/asciidoc/security.adoc
URL: http://svn.apache.org/viewvc/ofbiz/ofbiz-framework/trunk/framework/security/src/docs/asciidoc/security.adoc?rev=1866519&r1=1866518&r2=1866519&view=diff
==============================================================================
--- ofbiz/ofbiz-framework/trunk/framework/security/src/docs/asciidoc/security.adoc (original)
+++ ofbiz/ofbiz-framework/trunk/framework/security/src/docs/asciidoc/security.adoc Fri Sep  6 15:37:22 2019
@@ -19,5 +19,5 @@ under the License.
 
 = Security
 
+include::_include/sy-password-and-JWT.adoc[leveloffset=+1]
 include::_include/sy-impersonation.adoc[leveloffset=+1]
-