j1_template_mde 2018.4.10

data/lib/starter_web/pages/start/documentation/user_guide/240_auth_manager/000_includes/attributes.asciidoc

@@ -0,0 +1,119 @@
+// ~/document_base_folder/000_includes
+//  Asciidoc attribute includes:                 attributes.asciidoc
+// -----------------------------------------------------------------------------
+
+
+// URLs - Internal references and/or sources on the Internet
+// -----------------------------------------------------------------------------
+tag::urls[]
+
+:jekyll-home-news:                                https://jekyllrb.com/news/
+
+:patreon-home:                                    https://patreon.com/
+
+:wikipedia-en-gdpr:                               https://en.wikipedia.org/wiki/General_Data_Protection_Regulation
+
+:j1-gh-jekyllone-template-dev:                    https://github.com/jekyll-one/j1_template_mde_dev
+:j1-gh-jekyllone-j1-images:                       https://github.com/jekyll-one/j1_images
+:j1-gh-jekyllone-j1-image-git-repo:               https://github.com/jekyll-one/j1_image.git
+:j1-jekyllone-images:                             https://hub.docker.com/u/jekyllone/
+:j1-jekyllone-images-j1image:                     https://hub.docker.com/r/jekyllone/j1image/
+:j1-jekyllone-images-j1app:                       https://hub.docker.com/r/jekyllone/j1app/
+:j1-jekyllone-images-j1base:                      https://hub.docker.com/r/jekyllone/j1base/
+:j1-jekyllone-images-j1:                          https://hub.docker.com/r/jekyllone/j1/
+
+:j1-kickstarter-docker-in-a-day:                  /pages/start/kickstarter/docker_in_a_day/getting_started/
+:j1-kickstarter-private-sites:                    /pages/start/kickstarter/j1_private_sites/100_introduction/
+
+
+:j1-images-in-a-day-intro:                        /pages/start/kickstarter/j1_images_in_a_day/intro/
+:j1-images-in-a-day-run-and-develop:              /pages/start/kickstarter/j1_images_in_a_day/run_and_develop/
+:j1-images-in-a-day-create-images:                /pages/start/kickstarter/j1_images_in_a_day/create_docker_images/
+:j1-images-in-a-day-cheatsheet:                   /pages/start/kickstarter/j1_images_in_a_day/j1_images_cheatsheet/
+:j1-images-in-a-day-j1-images-project:            /pages/start/kickstarter/j1_images_in_a_day/j1_images_project/
+
+:j1-private-sites-in-a-day-intro:                 /pages/start/kickstarter/j1_private_sites/100_introduction/
+
+:envygeeks-home:                                  https://envygeeks.io/
+:envygeeks-docker-template:                       https://github.com/envygeeks/docker-template
+:envygeeks-wiki:                                  https://github.com/envygeeks/docker-template/wiki
+
+:docker-docs:                                     https://docs.docker.com/
+:docker-docs-squash-image-layers:                 http://docs.docker.oeynet.com/engine/reference/commandline/build/#squash-an-images-layers-squash-experimental-only
+:docker-hub-jekyll-jekyll-image:                  https://hub.docker.com/r/jekyll/jekyll/
+
+:ruby-core-erb:                                   https://ruby-doc.org/stdlib-2.5.3/libdoc/erb/rdoc/ERB.html
+
+end::urls[]
+
+
+// Tags - Asciidoc attributes used internally
+// -----------------------------------------------------------------------------
+tag::tags[]
+
+:window:                                          window="_blank"
+:figure-caption:                                  Figure
+:images-dir:                                      pages/documentation/100_user_guide/200_modules/240_auth_manager
+:y:                                               icon:check[role="green"]
+:n:                                               icon:times[role="red"]
+:c:                                               icon:file-alt[role="blue"]
+:beginner:                                        icon:battery-quarter[role="md-blue"]
+:inter:                                           icon:battery-half[role="md-blue"]
+:advanced:                                        icon:battery-full[role="md-blue"]
+:emdash:                                          —
+:bullet:                                          •
+:bigbullet:                                       ●
+:bigbigbullet:                                    ⬤
+:dot:                                             .
+:dotdot:                                          ..
+:middot:                                          ·
+
+end::tags[] 
+
+
+// Data - Data elements for Asciidoctor extensions
+// -----------------------------------------------------------------------------
+tag::data[]
+
+:data-download-image-create-starter:              "pages/documentation/100_user_guide/200_modules/240_auth_manager/download_image_create_starter.800x600.png, Create a starter web skeleton"
+:data-run-container-build-start-web:              "pages/documentation/100_user_guide/200_modules/240_auth_manager/run_container_build_start_web.800x400.png, Build and run the starter web"
+:data-running-starter-web:                        "pages/documentation/100_user_guide/200_modules/240_auth_manager/run_starter_web.800x700.png, Run the starter web in a browser"
+
+:data-j1-runtime-system:                          "pages/documentation/100_user_guide/200_modules/240_auth_manager/j1_runtime_system-1280x600.png, J1 Runtime System for content development"
+:data-j1-development-system:                      "pages/documentation/100_user_guide/200_modules/240_auth_manager/j1_development_system-1280x600.png, J1 Development System for full-stack development"
+
+:data-2-tier-architecture:                        "pages/documentation/100_user_guide/200_modules/240_auth_manager/2-tier-architecture-1280x600.png, 2-Tier Architecture"
+:data-3-tier-architecture:                        "pages/documentation/100_user_guide/200_modules/240_auth_manager/3-tier-architecture-1280x600.png, 3-Tier Architecture"
+:data-web-app-ruby-rack:                          "pages/documentation/100_user_guide/200_modules/240_auth_manager/rack_based_web_app-1280x600.png, Rack-based J1 Web Application"
+
+:data-j1-authclient-icon:                         "pages/documentation/100_user_guide/200_modules/240_auth_manager/j1-app-authclient-icon.1280x600.png, J1 AuthClient Icon"
+:data-j1-authclient-signin:                       "pages/documentation/100_user_guide/200_modules/240_auth_manager/j1-app-authclient-signin.1280x700.png, J1 AuthClient SignIn Dialog"
+:data-j1-authclient-signout:                      "pages/documentation/100_user_guide/200_modules/240_auth_manager/j1-app-authclient-signout.1280x700.png, J1 AuthClient SignOut Dialog"
+:data-j1-disqus-comment-dialog:                   "pages/documentation/100_user_guide/200_modules/240_auth_manager/j1-disqus-comment-dialog.1280x500.png, J1 Disqus Comment Dialog"
+
+
+
+
+:gh-oauth-autorization-page-data:                 "pages/documentation/100_user_guide/200_modules/240_auth_manager/gh-oauth-autorization-page.png, GH OAuth autorization page used by Jekyll One"
+:gh-oauth-login-page-data:                        "pages/documentation/100_user_guide/200_modules/240_auth_manager/gh-oauth-login-page.png, GH login page for autorization used by Jekyll One"
+
+
+
+
+end::data[]
+
+
+// Product - Document (e.g release) information
+// -----------------------------------------------------------------------------
+tag::product_info[]
+:license:                                         MIT License
+:revdate:                                         2018
+:revnumber:                                       1.0.0
+end::product_info[]
+
+
+// Author - Author information
+// -----------------------------------------------------------------------------
+tag::authors[]
+:uri-author-juergen-adams                         https://jekyll.one
+end::authors[]

data/lib/starter_web/pages/start/documentation/user_guide/240_auth_manager/100_auth_manager.adoc

@@ -0,0 +1,539 @@
+---
+title:                                  Authentication Module
+tagline:                                Template User Guide
+description:                            Authentication Module
+
+tags:                                   [ 
+                                          Authentication, Disqus, Google, 
+                                          Facebook, Twitter, Patreon, Template, 
+                                          Oauth, Oauth2, Module, Modules
+                                        ]
+resources:                              [ lightbox ]
+permalink:                              /user_guide/modules/auth_module/
+regenerate:                             false
+
+resource_options:
+
+  - toccer:
+      collapseDepth:                    3
+---
+
+// Enable the Liquid Preprocessor
+// -----------------------------------------------------------------------------
+:page-liquid:
+
+// Set other global page attributes here
+// -----------------------------------------------------------------------------
+
+// Liquid procedures
+// -----------------------------------------------------------------------------
+{% capture set_env_entry_document %}themes/{{site.template.name}}/procedures/global/set_env_entry_document.proc{%endcapture%}
+
+// Initialize entry document paths
+// -----------------------------------------------------------------------------
+{% include {{set_env_entry_document}} init_folders=all %}
+
+// Load tags and urls
+// -----------------------------------------------------------------------------
+include::{includedir}/attributes.asciidoc[tag=tags]
+include::{includedir}/attributes.asciidoc[tag=urls]
+include::{includedir}/attributes.asciidoc[tag=data]
+
+// Additional Asciidoc page attributes goes here
+// -----------------------------------------------------------------------------
+
+// Include sub-documents
+// -----------------------------------------------------------------------------
+
+link:{jekyll-home}[Jekyll, {window}] and link:{gh-j1-starter-web-example}[J1 Template, {window}]
+are awesome, right? Static site, lightning fast, everything versioned in
+link:{git-home}[Git, {window}]. Simply managed by an good editor.
+
+What else could be ask for?
+
+link:{github-pages-home}[GitHub Pages, {window}] for example are very helpful
+to setup a project web site for free, to present a J1 Template based project 
+on the Internet for free. But what if you want to share that site with only a 
+selected number of people?
+
+To manage private Webs (or selected private content) for a static Jekyll site,
+you need authorization. As you know, a static site has no database. How to get
+users authenticated, how to give them access to private content without a 
+database, without a user management in behind?
+
+Seems not possible -- first place. A user management for authentication is 
+needed. No way.
+
+If you think next corner you may realize that your users, your audience for 
+the protected content are already known members at service providers like 
+_Disqus_, _Github_, _Facebook_, _Twitter_ etc. Nowadays, people have plenty 
+digital identities based on memberships at e.g. social networks or registered 
+already for communication services like _Disqus_.
+
+Why not using the user management of well known internet service providers
+widely used by billion of people?
+
+This could be ask for!
+
+== Introduction
+
+J1 Template has an authorisation system integrated. The authorisation 
+management implemented with J1 is based on *middleware* system written in Ruby. 
+The magic to secure a site created by Jekyll is done out of the box. No 
+additional software, no programming work is needed.
+
+How should that work?
+
+To bring in something in a position the the middle, the architecture
+of your static web has to be changed from a two layer (tier) into a three
+layer architecture. Uhh, sounds not easy to change the architecture of a
+simple static site!
+
+===  Web Applications
+
+It couldn't be called easy to add a authentication system to a static web; but 
+it is manageable using the web development capabilities of the programming 
+language *Ruby*. Ruby has a domain in creating applications for the Web. 
+Powerful Ruby Gems (libraries) like *Rack*, *Sinatra* and others like *Rails* 
+can be used for that. In short: the programming language *Ruby* is widely 
+used to create Web Applications.
+
+ifdef::backend-html5[]
+.2-Tier Architecture of a static web
+lightbox::2-tier-architecture[ 800, {data-2-tier-architecture} ]
+endif::[]
+
+But what are Web Applications?
+
+First of all, a *multi layered* and *dynamic* web page (or web site). A 
+simplified image of the architecture used for Jekyll webs transformed into 
+an web application is shown below.
+
+ifdef::backend-html5[]
+.Rack-based Jekyll Web Application
+lightbox::web-app-ruby-rack[ 800, {data-web-app-ruby-rack} ]
+endif::[]
+
+For a Jekyll web that is *transformed* into an web application, the web
+server can be seen as an interface to access the application; to the 
+processing chain at the core of an application. The transformer software, the 
+Ruby library *Rack* is sitting *in between* and adds additional functionality 
+for managing a requested page.
+
+To *activate* this new 3-layered web site, an application manager is used:
+*rackup*. The application manager *rackup* is controlled by an configuration
+file, the so-called rackup-file *config.ru*.
+
+Don't mind the details for now. What your web browser, the client, connects
+is not longer only the web server. Each request for the pages of a web goes
+over the a middleware *system*, managed by *Rack*.
+
+A middleware system based on Rack is not a *monolithic* block. It is a *stack*
+of *multiple* middleware components. What the name *Rack* implies. What is 
+called *Rack Middlewares* are the next great Ruby libraries (Gem) managing 
+a specific job, a *service* in such a chain.
+
+For now folks, keep in mind a *Jekyll Site* can be run as an App, transformed
+into an *web application* using *Rack*. Rack provides the *magic* in the middle
+to add additional dynamic processes -- the services -- e.g. for authentication.
+
+=== The Vision
+
+What's the vision: whenever someone tries to access a secured web site for
+protected, for private pages the user will be *authorized* using the
+*authorisation* system implemented by J1, for example against _Disqus_ or 
+_GitHub_ to make sure they're a member of your organization at Github. Or 
+simply known as a registered user at _Disqus_ for example.
+
+Service providers like _Disqus_, _Facebook_ or _Github_ and many others support 
+autorization request by third parties using SSO (Single Sign On) technologies. 
+That way: your web site is supported by those providers for authentication!
+
+=== Make it real
+
+The middlewares used by J1 based on *Rack* for autorisation is using the
+Ruby Gem *OmniAuth*. OmniAuth supports a huge number of *strategies* for
+authorisation. See a list of providers supported link:{omniauth-strategies}[from here, {window}].
+
+J1, for now, is focussing providers using *OAuth*, a authorization protocol
+widely used for *SSO* on the Internet by many important providers. Currently,
+the providers:
+
+* Disqus
+* Github
+* Facebook
+* Twitter
+* Patreon
+
+are supported for authentication using OAuth.
+
+
+== Overview
+
+As discussed in section <<Overview>>, the authorisation system of _J1 Template_
+is based on middlewares. From a outer perspective this system can be seen as a
+component providing *services* to a web site. In contrast to dynamic functions
+provided by CSS or Javascript functionality, services are controlling the
+whole web, not single pages.
+
+_J1 Template_ implements 2 authorisation methods:
+
+* explicit autorisation using the _J1 AuthClient_
+* implicit autorisation based on *Page Access*
+
+=== Explicit autorisation
+
+For all people using websites, explicit autorisation is well known: a login
+button, typically in the menu bar, allows to sign in or out. Quite the same
+for _J1_. 
+
+NOTE: The AuthClient is only activated, if a web site is detected as an *App*.
+If a site is started as a simple static web, *no* middlewares are available
+and no authentication services are provided.
+
+If a running web site is detected as an Web Application, the J1 AuthClient
+places an *SignIn* icon into the menu bar on the right. If a user is detected 
+as signed out, a *SignIn* icon is displayed.
+
+ifdef::backend-html5[]
+.J1 AuthClient Icon
+lightbox::j1-authclient-icon[ 800, {data-j1-authclient-icon} ]
+endif::[]
+
+On a click on the signin icon, a dialog starts (as an overlay) presenting the
+providers available to be authenticated with.
+
+ifdef::backend-html5[]
+.J1 AuthClient SignIn Dialog
+lightbox::j1-authclient-signin[ 800, {data-j1-authclient-signin} ]
+endif::[]
+
+No surprise, if a user is detected as authenticated for one of the providers
+available, the AuthClient changes the icon to *SignOut* and a dialog to stop
+the authorisation is displayed.
+
+ifdef::backend-html5[]
+.J1 AuthClient SignOut Dialog
+lightbox::j1-authclient-signout[ 800, {data-j1-authclient-signout} ]
+endif::[]
+
+All these sounds very common, seen hundred times each and every day on the
+internet. But it is *not* the same because you aren't logged in the web, you 
+are authenticated with a provider and logged in with the provider!
+
+What does that mean? J1 supports so-called *OAuth2 Authentication* for the
+supported service providers. And more than this. If a visitor signs in for a
+provider, a set of user specific data is retrived and stored locally with a
+web session cookie. This *user profile* is used to control the access for
+the pages of this private web. More details on that in section 
+<<Implicit autorisation>>.
+
+And more than this again. A successful authorisation results in an 
+provider-specific *Access Token*, valid for weeks to access the web without 
+any login dialog anymore.
+
+J1 support *multi-provider* authentication can use all active *Access Token*
+from all providers in parallell as long this token is valid. This is quite 
+usefull to use provider-based features of a _J1 Web_ using *multi-provider* 
+authentication capabilities. 
+
+If a user signs in for _Disqus_ first but changes the provider for _Github_, 
+e.g. to get access to pages limited to _Github_ users, the authorisation is 
+now valid for _Disqus_ *and* _GitHub_.
+
+ifdef::backend-html5[]
+.J1 Disqus Comment Dialog
+lightbox::j1-disqus-comment-dialog[ 800, {data-j1-disqus-comment-dialog} ]
+endif::[]
+
+=== Implicit autorisation
+
+J1 use a underlying access-control for all pages. Web pages belong to three
+categories:
+
+* public
+* private
+* premium
+
+*Public pages* are accessible for all vistors of a web, *no* authorisation is 
+need to get access to. For secured pages, *Private* and *Public* access can be 
+defined on a provider level. *Private pages* can be used to limit the access
+for a specific provider. Or to specific users authenticated with a provider.
+This may helpfull for a developer team at _Github_ to limit the access for
+a Project Web for all documents that are in state *Work-In-Progress* (WIP) or
+to internal documentation that shouldn't available for the public.
+
+It is very common that web sites offering *payed services* to the public as 
+well. If content is *not* for free, *Premium pages* are an option. Currently 
+the provider link:{patreon-home}[Patreon] is supported for premium services 
+to limit the access to vistors only, that have paid e.g a monthly fee.
+
+*Implicit autorisation* autorisation is based on *regular expressions* like
+so:
+
+[source, yaml]
+----
+content:
+  public:
+      - ^(\/assets)
+      - ^(\/pages\/about)
+      - ^(\/pages\/start)
+  private:
+    - ^(\/private)
+  premium:
+    - ^(\/premium)
+  user:
+    patreon:                          [ all ]
+  permission:
+    patreon:                          [ private, premium ]
+  condition:
+    patreon:
+      private:                        false
+      premium:
+        pledges:                      true
+----
+
+All pages, having a *perma-link* that starts with */premium* needs to be
+authenticated via the provider _Patreon_. But access is given only, if
+the monthly fee (pleges) were paid for the detected user (profile).
+
+Provider-based authentication is a simple and powerful method to implement
+restrictesd access to protected pages of a web. But it has limitations, no
+question. For many standard web sites, static or dynamic, a simple 
+authorisation scheme fits many, many use cases.
+
+On other hand, since the link:{wikipedia-en-gdpr}[General Data Protection Regulation]
+applies to *all* web sites collecting and/or procession personal data of their
+visitors in the European Union, a lot of *legal* constrains are to be taken 
+into account. *GDPR* is an regulation *framework*, not a clear law-wise 
+definition. 
+
+A lot is unclear in this area but one thing is for sure: the penalties 
+are high if a site does *not* apply this rules. If a vistor is using 
+*provider-based authentication*  to get access for the content of a web, it 
+is very certain that a global service provider is compliant with *GDPR*. As 
+all users has to agree the conditions, the term of use, implicisely such a web
+is *GDPR* compliant -- if additional information is given that personal data
+is *used*.
+
+== Auth Service configuration
+
+lorem:sentences[5]
+
+=== Service properties
+
+[source, yaml]
+----
+# ---------------------------------------------------------------
+# J1 Auth Manager (j1_auth)
+#
+# If a site is started as an app, this transforms the web into an
+# Web Application based on Rack and Sinatra using the Omniauth
+# software stack for authentication to enable User Management
+# and Authentication services for secured private web sites.
+j1_auth:
+  enabled:                              true
+  ssl:                                  false
+
+  content:
+    public:
+        - ^(\/assets)
+        - ^(\/pages\/about)
+        - ^(\/pages\/start)
+    private:
+      - ^(\/private)
+    premium:
+      - ^(\/premium)
+
+  provider:
+    activated:                          [ disqus, github, patreon ]
+    home_url:
+      disqus:                           https://disqus.com
+      facebook:                         https://facebook.com
+      github:                           https://github.com
+      patreon:                          https://patreon.com
+      twitter:                          https://twitter.com
+    scope:
+      disqus:                           [ read, write ]
+      facebook:                         [ email ]
+      github:                           [ user ]
+      patreon:                          [ users ]
+      twitter:                          [ user ]
+    user:
+      disqus:                           [ all ]
+      facebook:                         [ all ]
+      github:                           [ all ]
+      patreon:                          [ all ]
+      twitter:                          [ all ]
+    permission:
+      disqus:                           [ private ]
+      facebook:                         [ private ]
+      github:                           [ private ]
+      patreon:                          [ private, premium ]
+      twitter:                          [ private ]
+    condition:
+      disqus:                           false
+      facebook:                         false
+      github:                           false
+      twitter:                          false
+      patreon:
+        private:                        false
+        premium:
+          pledges:                      true
+----
+
+==== enabled
+
+Enables or disables the Auth Manager services for the web.
+If disabled, all pages are accessible without authentication.
+
+values:                             true|false
+default:                            false
+
+
+==== ssl
+
+Enforce SSL communication for the app. If you've got SSL
+set up, ensure SSL is enforced.
+
+values:                             true|false
+default:                            false
+
+
+==== content
+
+lorem:sentences[5]
+
+==== provider
+
+List of enabled OAuth providers to be used for the auth
+service for authentication. The first provider in a list
+is used for default.
+
+===== activated
+
+values:                             [disqus|github|facebook|patreon|twitter]
+default: 
+
+===== home_url
+
+lorem:sentences[5]
+
+===== scope
+
+lorem:sentences[5]
+
+===== user
+
+lorem:sentences[5]
+
+===== permission
+
+lorem:sentences[5]
+
+===== condition
+
+lorem:sentences[5]
+
+
+
+
+
+
+
+
+
+
+== Auth Client configuration
+
+lorem:sentences[5]
+
+=== Client properties
+
+[source, yaml]
+----
+# ------------------------------------------------------------------------------
+# 1. Default settings
+#
+defaults:
+  nav_authclient:
+    enabled:                            false
+    icon_family:                        Material Design Icons
+    icon_color:                         rgba_lighten
+    icon_color_hover:                   rgba_lighten_900
+    signin_icon:                        login
+    signout_icon:                       logout
+...
+# ------------------------------------------------------------------------------
+# 5. Auth client settings
+#
+nav_authclient:
+  enabled:                              true
+
+  auth_signin_modal:                        
+    title:                              SignIn
+    body_text: >
+                                        In order to get <b>signed in</b>, check one of the options below
+                                        and mark a provider for authentication.
+                                        You'll be <b>redirected</b> to authenticate with the provider
+                                        <b>selected</b>. If signed in <b>successfully</b>, you get back
+                                        to this site for the page requested.
+                                        </br></br>
+                                        <b>NOTE:</b> To access protected pages of this site,
+                                        authentication is needed only once.
+                                        </br></br>
+ 
+                           
+  auth_signout_modal:                        
+    title:                              SignOut
+    body_text: >
+                                        In order to <b>signing out completely</b>, check the switch
+                                        below <b>to on</b>.
+                                        After signing out from this site, you'll be <b>redirected</b>
+                                        to the provider you're currently authenticated. From your
+                                        home page at the provider, you can sign out completely.    
+  auth_disqus:
+    id:                                 1
+    title:                              Disqus
+    text: >                             
+                                        SignIn to Disqus. Get access to all <b>PRIVATE</b> content pages.
+  auth_facebook:
+    id:                                 2
+    title:                              Facebook
+    text: >                             
+                                        SignIn to Facebook. Get access to all <b>PRIVATE</b> content pages.
+  auth_github:
+    id:                                 3
+    title:                              Github
+    text: >
+                                        SignIn to Github. Get access to all <b>PRIVATE</b> content pages.
+  auth_patreon:
+    id:                                 4
+    title:                              Patreon
+    text: >
+                                        SignIn to Patreon. Get access to all <b>PREMIUM</b> and <b>PRIVATE</b> content pages.
+  auth_twitter:
+    id:                                 5
+    home_url:                           "https://twitter.com"
+    title:                              Twitter
+    text: >                             
+                                        SignIn to Twitter. Get access to all <b>PRIVATE</b> content pages.
+----
+
+lorem:sentences[3]
+
+== Web App configuration
+
+lorem:sentences[5]
+
+
+
+== Configuration Cheat Sheet
+
+lorem:sentences[5]
+
+
+
+
+
+