Author: jleroux
Date: Sat Sep 14 11:37:44 2019
New Revision: 1866940
URL: http://svn.apache.org/viewvc?rev=1866940&view=rev
Log:
Improved: Document how to store the JWT secret key
(OFBIZ-10751)
Copy manually all files from trunk because of weird conflicts
Added:
ofbiz/branches/release16.11/framework/security/src/docs/
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/_include/
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/_include/sy-impersonation.adoc
(with props)
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/_include/sy-password-and-JWT.adoc
(with props)
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/security.adoc
(with props)
Added:
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/_include/sy-impersonation.adoc
URL:
http://svn.apache.org/viewvc/ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/_include/sy-impersonation.adoc?rev=1866940&view=auto
==============================================================================
---
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/_include/sy-impersonation.adoc
(added)
+++
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/_include/sy-impersonation.adoc
Sat Sep 14 11:37:44 2019
@@ -0,0 +1,127 @@
+////
+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.
+////
+
+= Impersonation
+== What is Impersonation in Apache OFBiz
+The Apache OFBiz Project
+Release 17.12
+
+:imagesdir: ../../themes/common-theme/webapp/images/img/
+ifdef::backend-pdf[]
+:title-logo-image: image::OFBiz-Logo.svg[Apache OFBiz Logo, pdfwidth=4.25in,
align=center]
+:source-highlighter: rouge
+endif::[]
+
+=== Introduction to User impersonation
+
+User Impersonation is a feature that offer a way to select a user login and
impersonate it, i.e. see what the user could
+see navigating through the application in his name.
+
+=== How do this work ?
+
+An authorized user _(see <<Security,security>> and <<Controls,controls>>
section for configuration)_, can select a user
+that will be impersonated.
+
+The impersonation start, if everything is well configured, in current
application (partymgr for the demo).
+Everything appears like if we were logged in with the userLoginId and the
valid password (though we know nothing about it)
+
+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=left]
+
+This icon indicates, when clicking on it, the user impersonated, and offer a
way to depersonate.
+
+The impersonate period is stored for audit purpose, and if the impersonator
forgot to depersonate, the period
+is terminated _one hour_ after impersonation start.
+
+=== Security
+
+This feature can draw some concerns about security aspect. This paragraph will
introduce every controls and properties
+that have been implemented around the impersonation feature.
+
+[CAUTION]
+These configuration steps are not to be neglected for a *production
environment* since this feature offer a way to act
+ in place of another user.
+
+==== Properties
+
+The _security.properties_ file introduce two properties that control
impersonation feature :
+
+
+[source]
+security.disable.impersonation = true
+
+This property, set by default to *true*, controls the activation of
impersonation feature. If no configuration is done
+any user trying to use impersonation will face an error message, indicating
that the feature is disabled.
+
+To enable impersonation this property need to be set to *false*
+
+
+[source]
+security.login.authorised.during.impersonate = false
+
+This property controls the way impersonation occurred to the impersonated user
:
+
+In default configuration, the impersonated user see nothing and can use the
application without knowing that he is
+currently impersonated. Several authorized user can impersonate a same login
without any issue.
+
+[NOTE]
+This configuration is intended for testing/QA environment allowing any
authorized user to impersonate a login
+to validate its configuration, test the application etc.
+
+Set to *true*, this configuration improve the control of the data generated by
the impersonated user. Indeed, Only one
+authorized user can impersonate a login at the same time, and during the
impersonation process, the impersonated user
+is unable to act within the application.
+
+Since the impersonation period is stored in database, the actions done by the
+authorized user can be identified if there is the need to do so.
+[NOTE]
+This configuration is intended for production environment
+
+
+==== Controls
+
+The permission::
+
+First, to be able to use impersonation, a user need to possess
_IMPERSONATE_ADMIN_ permissions. Demo data offer
+_IMPERSONATION_ security group for this purpose. +
+In demo data, _FULLADMIN_ security group also possess the permission.
+
+
+Permission based user restriction::
+
+An authorized user cannot impersonate any user. There are two main controls
that will restrict the impersonation feature.
+
+Cannot impersonate Admin user:::
+
+It is impossible to impersonate a user that is granted any of the admin
permission :
+
+ "IMPERSONATE_ADMIN"
+ "ARTIFACT_INFO_VIEW"
+ "SERVICE_MAINT"
+ "ENTITY_MAINT"
+ "UTIL_CACHE_VIEW"
+ "UTIL_DEBUG_VIEW"
+
+Cannot impersonate more privileged user:::
+
+It is impossible to impersonate a user that has more permission than your
user. Even if the missing persmission is
+a minor one.
+
+
Propchange:
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/_include/sy-impersonation.adoc
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/_include/sy-impersonation.adoc
------------------------------------------------------------------------------
svn:keywords = Date Rev Author URL Id
Propchange:
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/_include/sy-impersonation.adoc
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added:
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/_include/sy-password-and-JWT.adoc
URL:
http://svn.apache.org/viewvc/ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/_include/sy-password-and-JWT.adoc?rev=1866940&view=auto
==============================================================================
---
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/_include/sy-password-and-JWT.adoc
(added)
+++
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/_include/sy-password-and-JWT.adoc
Sat Sep 14 11:37:44 2019
@@ -0,0 +1,102 @@
+////
+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.
+////
+
+= Passwords and JWT (JSON Web Tokens) usage
+== How are set and used passwords and JWT in Apache OFBiz
+The Apache OFBiz Project
+Release 17.12
+
+:imagesdir: ../../themes/common-theme/webapp/images/img/
+ifdef::backend-pdf[]
+:title-logo-image: image::OFBiz-Logo.svg[Apache OFBiz Logo, pdfwidth=4.25in,
align=center]
+:source-highlighter: rouge
+endif::[]
+
+=== Passwords
+
+Demo and seed passwords are stored in files loaded through security
ofbiz-component.xml. To know more about that be sure to read:
+
+
+*
https://cwiki.apache.org/confluence/display/OFBIZ/Apache+OFBiz+Technical+Production+Setup+Guidehttp://url[The
technical production setup guide] notably "Initial Data Loading" and "Security
Settings" sections
+*
https://cwiki.apache.org/confluence/display/OFBIZ/How+to+secure+your+deploymenthttp://url[How
to secure your deployment]
+
+[CAUTION]
+These configuration steps are not to be neglected for the security of a
*production environment*
+
+=== JWT usage
+
+https://en.wikipedia.org/wiki/JSON_Web_Token[As says Wikipedia]:
+____
+JSON Web Token (JWT) is an Internet standard for creating JSON-based access
tokens that assert some number of claims.
+____
+
+
+We currently use JWT in 2 places:
+
+. To let users safely recreate passwords (in backend and frontend)
+. 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/.
+
+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 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 used
by 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.
+. If you want to get deeper in this get to this
https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Key_Management_Cheat_Sheet.md#user-content-storage[OWASP
documentation]
+
+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]. I have created
https://issues.apache.org/jira/browse/OFBIZ-11187[OFBIZ-11187] for that.
+
+===== Properties
+
+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
Propchange:
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/_include/sy-password-and-JWT.adoc
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/_include/sy-password-and-JWT.adoc
------------------------------------------------------------------------------
svn:keywords = Date Rev Author URL Id
Propchange:
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/_include/sy-password-and-JWT.adoc
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added:
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/security.adoc
URL:
http://svn.apache.org/viewvc/ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/security.adoc?rev=1866940&view=auto
==============================================================================
---
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/security.adoc
(added)
+++
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/security.adoc
Sat Sep 14 11:37:44 2019
@@ -0,0 +1,23 @@
+////
+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.
+////
+
+= Security
+
+include::_include/sy-password-and-JWT.adoc[leveloffset=+1]
+include::_include/sy-impersonation.adoc[leveloffset=+1]
Propchange:
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/security.adoc
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/security.adoc
------------------------------------------------------------------------------
svn:keywords = Date Rev Author URL Id
Propchange:
ofbiz/branches/release16.11/framework/security/src/docs/asciidoc/security.adoc
------------------------------------------------------------------------------
svn:mime-type = text/plain
