svn commit: r1844235 - in /ofbiz/ofbiz-framework/trunk/framework/webapp/src/docs/asciidoc: _include/wa-cross-domains-SSO.adoc _include/wa-cross-domains-auto-auth-navigation.adoc webapp.adoc

Author: jleroux
Date: Thu Oct 18 12:43:49 2018
New Revision: 1844235

URL: http://svn.apache.org/viewvc?rev=1844235&view=rev
Log:
Documented: Document the automated authentification from a domain to another
(OFBIZ-10562)

Renames the file using "SSO" instead of "auto-auth-navigation"
Completes the documentation

Added:
    ofbiz/ofbiz-framework/trunk/framework/webapp/src/docs/asciidoc/_include/wa-cross-domains-SSO.adoc
      - copied, changed from r1843987, ofbiz/ofbiz-framework/trunk/framework/webapp/src/docs/asciidoc/_include/wa-cross-domains-auto-auth-navigation.adoc
Removed:
    ofbiz/ofbiz-framework/trunk/framework/webapp/src/docs/asciidoc/_include/wa-cross-domains-auto-auth-navigation.adoc
Modified:
    ofbiz/ofbiz-framework/trunk/framework/webapp/src/docs/asciidoc/webapp.adoc

Copied: ofbiz/ofbiz-framework/trunk/framework/webapp/src/docs/asciidoc/_include/wa-cross-domains-SSO.adoc (from r1843987, ofbiz/ofbiz-framework/trunk/framework/webapp/src/docs/asciidoc/_include/wa-cross-domains-auto-auth-navigation.adoc)
URL: http://svn.apache.org/viewvc/ofbiz/ofbiz-framework/trunk/framework/webapp/src/docs/asciidoc/_include/wa-cross-domains-SSO.adoc?p2=ofbiz/ofbiz-framework/trunk/framework/webapp/src/docs/asciidoc/_include/wa-cross-domains-SSO.adoc&p1=ofbiz/ofbiz-framework/trunk/framework/webapp/src/docs/asciidoc/_include/wa-cross-domains-auto-auth-navigation.adoc&r1=1843987&r2=1844235&rev=1844235&view=diff
==============================================================================
--- ofbiz/ofbiz-framework/trunk/framework/webapp/src/docs/asciidoc/_include/wa-cross-domains-auto-auth-navigation.adoc (original)
+++ ofbiz/ofbiz-framework/trunk/framework/webapp/src/docs/asciidoc/_include/wa-cross-domains-SSO.adoc Thu Oct 18 12:43:49 2018
@@ -16,23 +16,45 @@ KIND, either express or implied.  See th
 specific language governing permissions and limitations
 under the License.
 ////
-= Authenticated cross-domains navigation
+= Cross-domains Single Sign On (SSO)
 
-In some cases you need to split applications on different servers, and possibly in production on different domains.This can happen for different reasons, most often for performance reason.
+In some cases you need to split the OFBiz applications on different servers, and possibly in production on different domains. This can happen for different reasons, most often for performance reason.
 
-As it's annoying to give a credential when changing from an OFBiz application to another on the same server,  it's annoying to give a credential when changing from an OFBiz application to another on another domain.
+As it's annoying to give each time a credential when changing from an OFBiz application to another on the same server, the same applies when changing from an OFBiz application to another on another domain.
 
-To handle automated sign in from an application to another we have currently 2 possibilities in OFBiz
-* externalLoginKey
-* Tomcat SSO (not used OOTB)
-
-This feature allows to navigate from a domain to another with automated signed in authentication.
+To prevent that on the same server, the ExternalLoginKey mechanism is used. The cross-domains SSO feature allows to navigate from a domain to another with automated SSO.
 
 It based on 3 technologies:
 
-. https://jwt.io/[JWT Official site] -
+JWT:: https://jwt.io/[JWT Official site] -
 https://en.wikipedia.org/wiki/JSON_Web_Token[Wikipedia for JWT]
-. https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS[CORS (Mozilla doc)] - https://en.wikipedia.org/wiki/Cross-origin_resource_sharing[Wikipedia for CORS]
-. Ajax, now well known I guess, in OFBiz we use jQuery for that.
 
-The mechanism is simple. The user is given a JavaScrip link
+CORS:: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS[CORS (Mozilla doc)] - https://en.wikipedia.org/wiki/Cross-origin_resource_sharing[Wikipedia for CORS]
+
+Ajax:: Ajax, now well known I guess, in OFBiz we use jQuery for that.
+
+The mechanism is simple.
+
+.On the source side:
+. When an user log in in an application (webApp) a webappName.securedLoginId cookie is created. This cookie will be used by the mechanism to know the current logged in user. _Note that all webappName.securedLoginId cookies are deleted when the user session is closed or time out. Hence (apart also using an intrinsically secured cookie) the mechanim is secured, even on shared machines. Of course if people are sharing a machine during their sessions, things could get complicated. This unlikely later case is not taken in account._
+
+. The user is given a JavaScript link which passes the URL to reach and the calling webapp name to the sendJWT() Ajax function.
+
+. The sendJWT() Ajax function calls the loadJWT() Ajax function which in turn calls the CommonEvents::loadJWT method through the common controller.
+
+. The CommonEvents::loadJWT method uses the calling webapp name to retrieve the userLoginId from the secured webappName.securedLoginId cookie, creates a JWT containing the userLoginId, and returns it to the loadJWT() Ajax function.
+
+. Then the sendJWT() Ajax function sends an Authorization header containing the JWT to the URL to reach. At this stage, if all things are correct, the flow leaves the source side.
+
+.On the server side:
+. A CORS policy is needed. _Without it, the Authorization token containing the JWT will be rejected. It's a simple policy but you need to strictly define the authorized domains. Never use the lazy "*" for domains (ie all domains), else the https://en.wikipedia.org/wiki/Cross-origin_resource_sharing#Preflight_example[preflight request] will not work._ Here is an example for Apache HTTPD (domain value is "https://localhost:8443" for official OFBiz demo):
+
+* Header set Access-Control-Allow-Origin domain
+* Header set Access-Control-Allow-Headers "Authorization"
+* Header set Access-Control-Allow-Credentials "true"
+
+. The checkJWTLogin preprocessor, similar to the checkExternalLoginKey, intercepts the JWT, checks it and if all is OK signs the user on. That's it !
+
+If you are interested in more details you may refer to  https://issues.apache.org/jira/browse/OFBIZ-10307
+
+

Modified: ofbiz/ofbiz-framework/trunk/framework/webapp/src/docs/asciidoc/webapp.adoc
URL: http://svn.apache.org/viewvc/ofbiz/ofbiz-framework/trunk/framework/webapp/src/docs/asciidoc/webapp.adoc?rev=1844235&r1=1844234&r2=1844235&view=diff
==============================================================================
--- ofbiz/ofbiz-framework/trunk/framework/webapp/src/docs/asciidoc/webapp.adoc (original)
+++ ofbiz/ofbiz-framework/trunk/framework/webapp/src/docs/asciidoc/webapp.adoc Thu Oct 18 12:43:49 2018
@@ -20,4 +20,4 @@ under the License.
 
 The OFBiz webapp is one of the core framework components. It is tightly integrated with other framework components.
 
-include::_include/wa-cross-domains-auto-auth-navigation.adoc[leveloffset=+1]
+include::_include/wa-cross-domains-SSO.adoc[leveloffset=+1]